reply9842 0.2.1 → 0.3.0

package/README.md

@@ -11,6 +11,9 @@ Agent 每请求要重传 1.3–2.2 MB 的完整上下文，日请求 2 万+，
 ```
 
 > 数据来自生产环境连续观测，含推理型模型的完整上下文。见[实测](#实测)。
+>
+> 它对协议本身不做任何假设：只是一个 HTTP 正向转发，任何「请求体大且相邻请求高度相似」
+> 的流量都适用。不绑定任何服务商，也不需要客户端侧改协议。
 
 ---
 
@@ -128,9 +131,9 @@ QUIC 与 TCP/TLS 共用同一个端口。
 ### 2. 客户端（和 Agent 同机）
 
 ```bash
-go build -o relay-client ./cmd/relay-client
+go build -o relay-cli ./cmd/cli
 
-./relay-client \
+./relay-cli \
   -listen 127.0.0.1:18899 \
   -server 47.82.76.102:28443 \
   -server-name magpie.aiweb.xin \
@@ -139,13 +142,35 @@ go build -o relay-client ./cmd/relay-client
 
 然后把 Agent 的 `base_url` 指向 `http://127.0.0.1:18899`。其余不变。
 
+> **用 IP 直连时必须给 `-server-name`。** 服务端证书的 SAN 只有 DNS 没有 IP，
+> 留空会按 `-server` 的 host（那个 IP）推导 SNI，必然 `x509: cannot validate
+> certificate ... doesn't contain any IP SANs`。用域名连则不需要显式指定。
+
+#### 连不上？先怀疑本机代理
+
+如果本机开着代理的 **TUN / 增强模式**（Clash 系常见），它用
+`0.0.0.0/1` + `128.0.0.0/1` 两条路由把整个 IPv4 空间导进 utun，隧道流量也被吞进去；
+代理对 `28443` 这类非标端口没有正确规则，TLS 握手会被中途切断，表现为
+`tcp tls: EOF` 或 `quic ... no application protocol`——看起来像服务端崩了。
+
+两条解法，任选其一：
+
+1. 在代理里把服务器 IP 加进**直连规则**（推荐）
+2. 加 `-local-addr <本机网卡 IP>` 绑定出站源地址，让内核直接走物理网卡：
+
+```bash
+ipconfig getifaddr en0          # macOS 取网卡 IP
+./relay-cli -local-addr 192.168.1.106 ...
+```
+
 ### 客户端参数
 
 | 参数 | 默认 | 说明 |
 |---|---|---|
-| `-listen` | `127.0.0.1:8899` | 本地 HTTP 入口 |
-| `-server` | `127.0.0.1:9000` | relay-server 的 host:port |
-| `-server-name` | 自动推导 | TLS SNI |
+| `-listen` | `127.0.0.1:18899` | 本地 HTTP 入口 |
+| `-server` | `47.82.76.102:28443` | relay-server 的 host:port |
+| `-server-name` | `magpie.aiweb.xin` | TLS SNI（用 IP 连时必须填证书域名）|
+| `-local-addr` | 空 | 绑定出站源地址，绕过代理 TUN 劫持 |
 | `-transport` | `auto` | `auto` / `quic` / `tcp` |
 | `-insecure` | `false` | 跳过证书校验（自签观察期）|
 | `-min-delta` | `16384` | 小于此值的请求体不做 delta |
@@ -168,6 +193,8 @@ go build -o relay-client ./cmd/relay-client
 | `-tmp-mb` | `512` | 活跃区字节预算 |
 | `-idem-mb` | `2048` | 幂等区字节预算 |
 | `-upstream-timeout` | `10m` | 上游请求超时（不随客户端断开取消）|
+| `-health-addr` | 空 | 健康检查监听（如 `127.0.0.1:8080`）；留空不启用 |
+| `-health-probe` | `false` | 探针模式：GET 自己的 `/healthz`，成功 exit 0。给 scratch 镜像的 HEALTHCHECK 用（容器内无 curl）|
 
 ## 三个关键设计决策
 
@@ -320,33 +347,38 @@ tail -f ~/.reply9842/client-$(date +%F).jsonl | \
 
 ```
 cmd/
-├── relay-client/     本地 HTTP 入口 + 基线选择 + delta 编码 + 续传
-└── relay-server/     隧道服务端 + 解码校验 + 上游转发 + spool
+├── cli/              本地 HTTP 入口 + 基线选择 + delta 编码 + 续传（命令行）
+├── gui/              同一套逻辑的图形界面（mygo native UI + 系统托盘）
+└── server/           隧道服务端 + 解码校验 + 上游转发 + spool
 internal/
 ├── meta/             隧道帧格式（magic + 版本 + 类型 + 长度前缀）
 ├── codec/            dcz 编解码、自适应 level、静默损坏防护
+├── downlink/         下行响应压缩
 ├── store/            内容寻址 LRU（零协商）
 ├── basefind/         客户端基线选择（4KB 块哈希命中率）
-├── transport/        QUIC + TCP 双栈 + auto 回退
+├── transport/        QUIC + TCP 双栈 + auto 回退 + 源地址绑定
+├── relayclient/      客户端运行时（配置归一化、runner、设置持久化）
 ├── spool/            磁盘双区域流式缓冲（tmp / idem + 字节预算淘汰）
 ├── idem/             幂等键（callerKeyId + 请求指纹）
 ├── clientstream/     帧 → HTTP 响应 + 续传游标
+├── autostart/        开机自启（launchd / HKCU Run）
+├── glass/            GUI 玻璃材质调色板与 Surface
 ├── e2e/              断线续传端到端测试
-└── stats/            逐请求与汇总统计
+└── stats/            逐请求与汇总统计（JSONL 为事实来源，重启不清零）
 ```
 
 ## 已知限制
 
-1. **响应不压缩**。当前只优化上行；下行 p50 约 18 KB，暂未处理。
-2. **`resend-full` 的线宽统计只计首次尝试**。DeltaMiss 后的全量重发不计入该行
+1. **`resend-full` 的线宽统计只计首次尝试**。DeltaMiss 后的全量重发不计入该行
    `up_wire`，所以含冷启动的窗口其真实占比会高于表格数字（见上文 † 注）。
-3. **冷启动无收益**。服务端首次见到某基线时必然 miss，第一次重发是全量成本（约 20–35%）。
-4. **QUIC 生产未启用**。有回环端到端测试（`TestQUICRoundTrip`）通过，但生产链路仍走
+2. **冷启动无收益**。服务端首次见到某基线时必然 miss，第一次重发是全量成本（约 20–35%）。
+3. **QUIC 生产未启用**。有回环端到端测试（`TestQUICRoundTrip`）通过，但生产链路仍走
    TCP/TLS；启用需放通 UDP 端口并验证中间设备。
-5. **大文档内存**。30 MB 级请求的 delta 需要显著内存，需靠 `PickLevel` 降级。
-6. **单请求体全量缓冲**。客户端与服务端都会把 body 读进内存（为统计与压缩）。
-7. **跨用户字典隔离**。若将来共享字典，必须按租户隔离——混合公私数据的字典存在
+4. **大文档内存**。30 MB 级请求的 delta 需要显著内存，需靠 `PickLevel` 降级。
+5. **单请求体全量缓冲**。客户端与服务端都会把 body 读进内存（为统计与压缩）。
+6. **跨用户字典隔离**。若将来共享字典，必须按租户隔离——混合公私数据的字典存在
    CRIME/BREACH 类攻击面（RFC 9842 §9.2）。
+7. **GUI 无 Linux 后端**。mygo 的 native UI 只支持 macOS / Windows，Linux 只有 cli 与 server。
 
 ## 规范参考
 
@@ -358,22 +390,7 @@ internal/
 | RFC 7694 (Client-Initiated Content-Encoding) | 请求方向编码协商 | 语义参考 |
 | RFC 8785 (JCS) | JSON 规范化 | 若做块哈希则必需（本方案未用）|
 
-## 官网与部署
-
-官网源码在 [`site/`](./site)（纯 HTML + CSS，无框架、无外部字体、无图片资源），
-线上地址 <https://reply9842.jixoai.com>。
-
-`site/` 目录：
-
-```
-site/
-├── index.html     单页落地页（内核数字 / 原理图 / 实测表 / 快速开始）
-├── style.css      全部样式（OKLCH 单品牌色，响应式，含 reduced-motion）
-└── CNAME          reply9842.jixoai.com
-```
-
-推送 `main` 且 `site/**` 有变更时，`.github/workflows/pages.yml` 自动构建并发布到
-GitHub Pages（也可在 Actions 页手动 `workflow_dispatch`）。
+## 官网
 
-DNS 侧 `rfc9842.jixoai.com` 已 CNAME 到 `jixoai.github.io`（Cloudflare、DNS only），
-`site/CNAME` 已写好目标域名，Pages 据此绑定自定义域并自动申请 TLS。
+<https://reply9842.jixoai.com>（源码在 [`site/`](./site)，纯 HTML + CSS，无框架、
+无外部字体、无图片资源）。

package/lib/download.js

@@ -0,0 +1,455 @@
+// 断点续传下载器
+//
+// 事故背景（2026-11-13，见 scripts/deploy.sh 顶部）：跨境链路被短 timeout 打断，
+// 传了 2.5MB / 9.9MB 的 ELF 就被部署，`file` 仍报 "ELF 64-bit LSB executable"
+// （header 完好），真跑起来 status=11/SEGV。二进制下载是同一个风险面，所以这里：
+//
+//   1. 边收边写盘（createWriteStream 语义），大文件不全量驻留内存；
+//   2. 重试时发 `Range: bytes=<已有长度>-`，.part 文件跨进程/跨镜像存活；
+//   3. 结束时**必须**核对字节数（content-length / content-range 的 total），
+//      不一致直接报错，绝不把半截文件 rename 成正式产物；
+//   4. 可选 SHA256 校验（release 里的 SHA256SUMS.txt），能识别「换了镜像但内容不同」。
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { DIRECT } = require("./mirror");
+
+/** 单次请求的空闲超时：多久收不到新字节就判定连接死了。 */
+const DEFAULT_IDLE_TIMEOUT_MS = 30_000;
+
+/** 每个镜像的尝试次数（首次 + 一次重试，重试会带 Range 续传）。 */
+const DEFAULT_ATTEMPTS = 2;
+
+// ---- 纯逻辑（可单测） ----
+
+/**
+ * 续传请求头。已有字节 > 0 才发 Range；否则发空对象（保持普通 GET）。
+ * @returns {{Range?: string}}
+ */
+function buildRangeHeader(existingBytes) {
+  if (!Number.isFinite(existingBytes) || existingBytes <= 0) return {};
+  return { Range: `bytes=${existingBytes}-` };
+}
+
+/**
+ * 解析 `Content-Range`。
+ *   "bytes 100-200/300" → { start: 100, end: 200, total: 300 }
+ *   "bytes 100-200/*"   → { start: 100, end: 200, total: null }
+ *   "bytes *​/300"       → { start: null, end: null, total: 300 }   (416 用)
+ */
+function parseContentRange(header) {
+  if (typeof header !== "string") return null;
+  const m = /^bytes\s+(?:(\d+)-(\d+)|\*)\/(\d+|\*)$/i.exec(header.trim());
+  if (!m) return null;
+  return {
+    start: m[1] === undefined ? null : Number(m[1]),
+    end: m[2] === undefined ? null : Number(m[2]),
+    total: m[3] === "*" ? null : Number(m[3]),
+  };
+}
+
+/**
+ * 决定「这次响应怎么处理」。纯函数，206/200/416 分支都在这。
+ *
+ * 关键区分：只有「body 的起点正好等于要写入的偏移」才能用这段 body。
+ *   append  —— 206 且 start == 已有长度（真正的续传）
+ *   restart —— body 从 0 开始，清空 .part 后可直接写（206 start=0 / 200）
+ *   refetch —— body 起点与本地长度都对不上（206 start 既不等于已有长度也不是 0，
+ *              或 416 且总长 ≠ 已有长度）：**这段 body 不可用**，必须删掉 .part
+ *              重新发一次不带 Range 的请求
+ *   complete —— 416 且已有长度正好等于服务端总长（.part 其实已完整）
+ *
+ * @param {{status:number, existingBytes:number, headers:{get:(n:string)=>string|null}}} args
+ * @returns {{action:"append"|"restart"|"refetch"|"complete", total:number|null, reason?:string}}
+ */
+function classifyResponse({ status, existingBytes, headers }) {
+  const get = (name) => (headers && typeof headers.get === "function"
+    ? headers.get(name)
+    : null);
+
+  if (status === 206) {
+    const range = parseContentRange(get("content-range"));
+    if (!range || range.start === null) {
+      throw new Error("服务端返回 206 但缺少合法的 Content-Range");
+    }
+    const length = Number(get("content-length") || 0);
+    if (length > 0 && range.end !== null && length !== range.end - range.start + 1) {
+      throw new Error(
+        `206 响应的 content-length(${length}) 与 Content-Range(${range.start}-${range.end}) 不一致`,
+      );
+    }
+    if (range.start === existingBytes) {
+      return { action: "append", total: range.total };
+    }
+    if (range.start === 0) {
+      // 服务端无视了 Range，但我们拿到的仍是从 0 开始的完整数据，清空重写即可
+      return {
+        action: "restart",
+        total: range.total,
+        reason: `服务端从 0 开始返回（本地已有 ${existingBytes}），从头写`,
+      };
+    }
+    // 起点既不是 0 也不是本地长度：body 是中间片段，接到 .part 上会拼出坏文件
+    return {
+      action: "refetch",
+      total: range.total,
+      reason: `服务端从 ${range.start} 开始返回，本地已有 ${existingBytes}，需重新请求`,
+    };
+  }
+
+  if (status === 200) {
+    // 服务端不支持 Range（忽略了我们发的头），body 从 0 开始，清空重写
+    const total = Number(get("content-length") || 0) || null;
+    return {
+      action: "restart",
+      total,
+      reason: existingBytes > 0 ? "服务端不支持 Range，从头下载" : undefined,
+    };
+  }
+
+  if (status === 416) {
+    const range = parseContentRange(get("content-range"));
+    const total = range ? range.total : null;
+    if (total !== null && total === existingBytes) {
+      return { action: "complete", total };
+    }
+    // .part 比服务端文件还长（或总长未知）：这段残留不可信，丢掉重来
+    return {
+      action: "refetch",
+      total,
+      reason: `416：本地 .part(${existingBytes} 字节)与文件实际长度${total === null ? "不符" : `(${total} 字节)不符`}，丢弃重来`,
+    };
+  }
+
+  throw new Error(`HTTP ${status}`);
+}
+
+/** 字节数校验。不一致要报错，不能静默接受半截文件。 */
+function verifySize(actualBytes, expectedBytes, context) {
+  if (expectedBytes == null) return; // 服务端没给长度，只能靠 SHA256 兜底
+  if (actualBytes !== expectedBytes) {
+    throw new Error(
+      `下载不完整${context ? `（${context}）` : ""}: 实际 ${actualBytes} 字节，` +
+        `服务端声明 ${expectedBytes} 字节，相差 ${expectedBytes - actualBytes}`,
+    );
+  }
+}
+
+/** 解析 SHA256SUMS.txt：`<hex>  <name>` 每行一条。 */
+function parseChecksums(text) {
+  const map = new Map();
+  for (const line of String(text || "").split(/\r?\n/)) {
+    const m = /^([0-9a-fA-F]{64})\s+\*?(.+?)\s*$/.exec(line);
+    if (m) map.set(m[2], m[1].toLowerCase());
+  }
+  return map;
+}
+
+async function sha256File(file) {
+  const hash = crypto.createHash("sha256");
+  await new Promise((resolve, reject) => {
+    const rs = fs.createReadStream(file);
+    rs.on("data", (c) => hash.update(c));
+    rs.on("error", reject);
+    rs.on("end", resolve);
+  });
+  return hash.digest("hex");
+}
+
+// ---- 落盘 ----
+
+function tempPath(dest) {
+  return `${dest}.part`;
+}
+
+/** 记录「第一次下载时服务端声明的总长 / ETag」，用于识别换镜像后内容不同。 */
+function metaPath(dest) {
+  return `${dest}.part.json`;
+}
+
+async function readMeta(dest) {
+  try {
+    return JSON.parse(await fs.promises.readFile(metaPath(dest), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+async function writeMeta(dest, meta) {
+  try {
+    await fs.promises.writeFile(metaPath(dest), JSON.stringify(meta));
+  } catch {
+    /* meta 只是优化，写不进去不影响正确性 */
+  }
+}
+
+async function cleanupTemp(dest) {
+  for (const p of [tempPath(dest), metaPath(dest)]) {
+    await fs.promises.rm(p, { force: true });
+  }
+}
+
+async function fileSize(file) {
+  try {
+    return (await fs.promises.stat(file)).size;
+  } catch (e) {
+    if (e.code === "ENOENT") return 0;
+    throw e;
+  }
+}
+
+/** 丢弃不再需要的响应体（不消费会占着连接，keep-alive 池里泄漏）。 */
+async function discardBody(res) {
+  if (!res || !res.body) return;
+  try {
+    if (typeof res.body.cancel === "function") await res.body.cancel();
+  } catch {
+    /* 已经结束/已取消 */
+  }
+}
+
+// ---- 单次传输 ----
+
+/**
+ * 从单个前缀拉一次，成功返回 { bytes, total }。
+ * 失败时 .part 保留（续传素材），只有内容明显不对才删。
+ */
+async function downloadOnce({ url, prefix, dest, fetchImpl, onProgress, idleTimeoutMs }) {
+  const existing = await fileSize(tempPath(dest));
+  const controller = new AbortController();
+  let idleTimer = null;
+  const armIdle = () => {
+    if (!idleTimeoutMs) return;
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(
+      () => controller.abort(new Error(`连接空闲超过 ${idleTimeoutMs}ms`)),
+      idleTimeoutMs,
+    );
+  };
+
+  armIdle();
+  let res;
+  try {
+    res = await fetchImpl(prefix + url, {
+      redirect: "follow",
+      headers: buildRangeHeader(existing),
+      signal: controller.signal,
+    });
+  } catch (e) {
+    if (idleTimer) clearTimeout(idleTimer);
+    throw e;
+  }
+
+  try {
+    const plan = classifyResponse({
+      status: res.status,
+      existingBytes: existing,
+      headers: res.headers,
+    });
+
+    if (plan.action === "complete") {
+      await discardBody(res);
+      return { bytes: existing, total: plan.total };
+    }
+    if (plan.reason) {
+      onProgress({ phase: "info", message: plan.reason });
+    }
+    if (plan.action === "refetch") {
+      // 这段 body 的起点和我们盘上的字节对不上，接到 .part 上会拼出坏文件。
+      // 丢掉残留后让上层重发一次不带 Range 的请求（416 / 起点错位都走这里）。
+      await discardBody(res);
+      await cleanupTemp(dest);
+      throw Object.assign(new Error(plan.reason || "需要重新请求"), { restart: true });
+    }
+
+    // 换镜像/服务端声明的总长变了 → 之前下的那段不是这个文件，必须丢
+    const meta = await readMeta(dest);
+    if (plan.action === "append" && meta.total != null && plan.total != null && meta.total !== plan.total) {
+      await cleanupTemp(dest);
+      throw Object.assign(
+        new Error(`服务端文件大小(${plan.total})与已下载部分(${meta.total})不符，已丢弃重来`),
+        { restart: true },
+      );
+    }
+    const etag = res.headers.get("etag");
+    if (plan.action === "append" && meta.etag && etag && meta.etag !== etag) {
+      await cleanupTemp(dest);
+      throw Object.assign(
+        new Error("镜像返回的 ETag 与已下载部分不一致，已丢弃重来"),
+        { restart: true },
+      );
+    }
+
+    const startingAt = plan.action === "append" ? existing : 0;
+    const tmp = tempPath(dest);
+    await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+    const handle = await fs.promises.open(tmp, plan.action === "append" ? "a" : "w");
+
+    if (plan.action !== "append") {
+      // 从头写：旧 meta 已失效，避免下一次续传拿它做总长比对
+      await fs.promises.rm(metaPath(dest), { force: true });
+    }
+    if (plan.total == null) {
+      onProgress({
+        phase: "info",
+        message: "服务端未声明文件长度，只能靠 SHA256 校验完整性",
+      });
+    }
+
+    let written = startingAt;
+    try {
+      if (plan.total != null) {
+        await writeMeta(dest, { total: plan.total, etag: etag || meta.etag || null });
+        onProgress({ phase: "start", written, total: plan.total, resumed: startingAt > 0 });
+      }
+      if (res.body) {
+        for await (const chunk of res.body) {
+          armIdle();
+          await handle.write(chunk);
+          written += chunk.length;
+          if (plan.total) onProgress({ phase: "progress", written, total: plan.total });
+        }
+      }
+    } catch (e) {
+      // 网络中断：把已有进度刷盘，交给下一次尝试续传
+      await handle.close();
+      throw new Error(
+        `传输中断（已写入 ${written} 字节${plan.total ? ` / ${plan.total}` : ""}）：${e.message}`,
+      );
+    }
+    const st = await handle.stat();
+    await handle.close();
+
+    // ★ 完整性闸门：字节数对不上绝不 rename
+    verifySize(st.size, plan.total, prefix ? new URL(prefix).hostname : "直连");
+    if (written !== st.size) {
+      throw new Error(`写入计数(${written})与磁盘大小(${st.size})不一致`);
+    }
+    return { bytes: st.size, total: plan.total };
+  } catch (e) {
+    await discardBody(res); // 复核失败/HTTP 非 2xx：别把响应体挂在那里
+    throw e;
+  } finally {
+    if (idleTimer) clearTimeout(idleTimer);
+  }
+}
+
+// ---- 多镜像编排 ----
+
+function hostOf(prefix) {
+  if (prefix === DIRECT) return "github.com（直连）";
+  try {
+    return new URL(prefix).hostname;
+  } catch {
+    return prefix;
+  }
+}
+
+/**
+ * 依次尝试镜像下载到 dest（原子 rename）。返回 { bytes, prefix }。
+ *
+ * 每个镜像默认尝试两次：第一次失败留下的 .part 会被第二次用 Range 续上；
+ * 换镜像同样续，因为同一版本同一文件内容一致——但服务端声明的总长或 ETag
+ * 变化时判定为不同内容，丢弃重下。
+ */
+async function downloadArtifact({
+  url,
+  dest,
+  prefixes,
+  fetchImpl = globalThis.fetch,
+  onProgress = () => {},
+  log = () => {},
+  attempts = DEFAULT_ATTEMPTS,
+  idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
+  expectedSha256 = null,
+}) {
+  const tmp = tempPath(dest);
+  let lastErr;
+  const list = prefixes && prefixes.length ? prefixes : [DIRECT];
+
+  for (const prefix of list) {
+    const label = hostOf(prefix);
+    let attempt = 0;
+    let refunded = 0; // 「内容不符 → 丢弃重来」不占用尝试次数，但每个镜像最多退一次
+    while (attempt < attempts) {
+      attempt++;
+      const has = await fileSize(tmp);
+      log(`  ${label}${attempt > 1 ? `（第 ${attempt} 次尝试）` : ""}${has > 0 ? `，已有 ${(has / 1048576).toFixed(1)}MB 续传` : ""} …`);
+      try {
+        const { bytes } = await downloadOnce({
+          url, prefix, dest, fetchImpl, onProgress, idleTimeoutMs,
+        });
+
+        if (expectedSha256) {
+          const actual = await sha256File(tmp);
+          if (actual !== expectedSha256) {
+            await cleanupTemp(dest);
+            throw Object.assign(
+              new Error(`SHA256 校验失败（期望 ${expectedSha256.slice(0, 12)}…，实际 ${actual.slice(0, 12)}…），已丢弃`),
+              { restart: true },
+            );
+          }
+        }
+
+        await fs.promises.rename(tmp, dest); // 原子落盘
+        await fs.promises.rm(metaPath(dest), { force: true });
+        if (process.platform !== "win32") await fs.promises.chmod(dest, 0o755);
+        return { bytes, prefix };
+      } catch (e) {
+        lastErr = e;
+        log(`    失败：${e.message}`);
+        if (!e.restart) continue; // 网络/HTTP 错误：留给同一镜像的下一次尝试续传
+
+        // 内容层面的错误（大小/ETag/SHA256 不符）：.part 已删，值得立刻从头重来一次
+        if (refunded === 0) {
+          refunded++;
+          attempt--; // 这次不算数
+        }
+        // 同一个镜像连续两次内容都不对 → 换镜像
+      }
+    }
+  }
+  throw lastErr || new Error("全部镜像失败");
+}
+
+/** 取 SHA256SUMS.txt（best-effort，任何失败都返回 null，不阻塞下载）。 */
+async function fetchChecksums({ url, prefixes, fetchImpl = globalThis.fetch, idleTimeoutMs = 15_000 }) {
+  for (const prefix of prefixes && prefixes.length ? prefixes : [DIRECT]) {
+    const controller = new AbortController();
+    const timer = idleTimeoutMs
+      ? setTimeout(() => controller.abort(new Error("timeout")), idleTimeoutMs)
+      : null;
+    try {
+      const res = await fetchImpl(prefix + url, { redirect: "follow", signal: controller.signal });
+      if (!res.ok) continue;
+      const text = await res.text();
+      const map = parseChecksums(text);
+      if (map.size > 0) return map;
+    } catch {
+      /* 忽略，继续下一个前缀 */
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  DEFAULT_ATTEMPTS,
+  DEFAULT_IDLE_TIMEOUT_MS,
+  buildRangeHeader,
+  classifyResponse,
+  cleanupTemp,
+  downloadArtifact,
+  downloadOnce,
+  fetchChecksums,
+  metaPath,
+  parseChecksums,
+  parseContentRange,
+  sha256File,
+  tempPath,
+  verifySize,
+};

package/lib/mirror.js

@@ -0,0 +1,149 @@
+// 镜像（加速前缀）配置解析
+//
+// 契约（npm 下载器 / Go update 包 / GUI 设置页三处共用，改这里要同步三处）：
+//
+//   优先级：REPLY9842_MIRROR 环境变量 > 内置默认列表
+//   格式：  逗号分隔的前缀列表，顺序即优先级（回退链）
+//   特殊值：direct 或空值 = 直连（不加前缀）
+//   拼接：  <前缀><完整 url>，前缀末尾自动补 "/"，已带则不动
+//
+// 为什么不复用 npm_config_*：npm 会吃掉自己前缀的变量并做一层 config 解析，
+// 用户从 .npmrc 传下来的值语义会变形；REPLY9842_ 前缀无歧义。
+
+"use strict";
+
+/** 内置默认列表：先国内镜像，最后官方直连兜底。顺序是 2026-11 实测下来的。 */
+const DEFAULT_MIRRORS = [
+  "https://gh-proxy.com/",
+  "https://ghfast.top/",
+  "https://ghproxy.net/",
+  "", // 空串 = 直连
+];
+
+/** 覆盖用的环境变量名 */
+const MIRROR_ENV = "REPLY9842_MIRROR";
+
+/** 直连前缀（空串，拼接后仍是原 url） */
+const DIRECT = "";
+
+function isDirect(token) {
+  return token === DIRECT || token.toLowerCase() === "direct";
+}
+
+/**
+ * 规范化单个前缀：末尾补 "/"。
+ * 代理契约是 `<prefix><url>` 直接字符串拼接，少一个斜杠就会拼出
+ * `https://my.mirrorhttps://github.com/...` 这种坏 URL。
+ */
+function normalizePrefix(prefix) {
+  if (prefix === DIRECT) return DIRECT;
+  return prefix.endsWith("/") ? prefix : `${prefix}/`;
+}
+
+/**
+ * 校验前缀是 http(s) URL。
+ *
+ * 校验放在补斜杠**之后**：`https://m.example.com` 补成 `https://m.example.com/`
+ * 才是真正参与拼接的形态，用最终形态校验才等价于 Go 侧。
+ */
+function validatePrefix(value, raw) {
+  // WHATWG URL 会把 "https:///x" 的额外斜杠当空 authority 丢弃、解析成 host=x，
+  // 而 Go 的 url.Parse 得到 Host=""（拒绝）。为了让两侧接受集合**完全相同**，
+  // 这里显式要求 authority 非空，不依赖 URL 解析器的宽松行为。
+  const authority = /^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)/i.exec(value);
+  if (authority && authority[1].trim() === "") {
+    throw new Error(
+      `${MIRROR_ENV} 里的镜像前缀缺少主机名：${JSON.stringify(raw)}`,
+    );
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    if (/^https?:\/\/$/i.test(value)) {
+      throw new Error(
+        `${MIRROR_ENV} 里的镜像前缀缺少主机名：${JSON.stringify(raw)}`,
+      );
+    }
+    throw new Error(
+      `${MIRROR_ENV} 里的镜像前缀不是合法 URL：${JSON.stringify(raw)}`,
+    );
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(
+      `${MIRROR_ENV} 只接受 http(s) 前缀，收到：${JSON.stringify(raw)}`,
+    );
+  }
+  if (!parsed.hostname) {
+    throw new Error(
+      `${MIRROR_ENV} 里的镜像前缀缺少主机名：${JSON.stringify(raw)}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * 解析一行镜像配置文本，返回前缀数组（含 "" 表示直连）。
+ *
+ * 规则：
+ *  - 逗号切分，每项 trim；
+ *  - 空项跳过（`a,,b` → [a, b]，直连必须显式写 direct）；
+ *  - `direct`（大小写不敏感）与整串为空 → 直连；
+ *  - 无任何有效项 → 直连（尊重用户显式设置，不回退默认）；
+ *  - 保持顺序去重。
+ */
+function parseMirrorList(raw) {
+  const text = String(raw == null ? "" : raw).trim();
+  if (text === "") return [DIRECT];
+
+  const out = [];
+  const seen = new Set();
+  const push = (prefix) => {
+    if (seen.has(prefix)) return;
+    seen.add(prefix);
+    out.push(prefix);
+  };
+
+  for (const piece of text.split(",")) {
+    const token = piece.trim();
+    if (token === "") continue; // 容忍 `a,,b` 与结尾逗号
+    if (isDirect(token)) {
+      push(DIRECT);
+      continue;
+    }
+    push(normalizePrefix(validatePrefix(token, piece)));
+  }
+
+  return out.length > 0 ? out : [DIRECT];
+}
+
+/**
+ * 解析当前生效的镜像列表。
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+function resolveMirrors(env = process.env) {
+  const raw = env ? env[MIRROR_ENV] : undefined;
+  if (raw === undefined) return DEFAULT_MIRRORS.slice(); // 未设置 = 默认行为
+  return parseMirrorList(raw);
+}
+
+/** 给人看的镜像名：直连显示 github.com，其余显示 hostname。 */
+function mirrorLabel(prefix) {
+  if (prefix === DIRECT) return "github.com（直连）";
+  try {
+    return new URL(prefix).hostname;
+  } catch {
+    return prefix;
+  }
+}
+
+module.exports = {
+  DEFAULT_MIRRORS,
+  DIRECT,
+  MIRROR_ENV,
+  mirrorLabel,
+  normalizePrefix,
+  parseMirrorList,
+  resolveMirrors,
+};

package/lib/run.js

@@ -10,8 +10,12 @@
 //   - 用户只为自己的平台付一次下载，而不是装一次拿到 13 个二进制
 //   - 缓存按版本隔离，换版本不会串
 //
-// 国内加速：GitHub Release 直连在国内经常超时。按下列前缀顺序尝试（社区惯例的
-// gh-proxy 系列），任一成功即用；全部失败才回退直连。
+// 国内加速：GitHub Release 直连在国内经常超时。按前缀顺序尝试（社区惯例的
+// gh-proxy 系列），任一成功即用；全部失败才回退直连。前缀列表可用
+// REPLY9842_MIRROR 环境变量覆盖，见 lib/mirror.js 的契约说明。
+//
+// 断点续传：见 lib/download.js —— 边收边写 .part，中断后下次启动带 Range 续上，
+// 并在 rename 前核对字节数与 SHA256（防「半截二进制跑出 SEGV」）。
 
 "use strict";
 
@@ -21,15 +25,8 @@ const os = require("node:os");
 const { spawn } = require("node:child_process");
 
 const PKG = require("../package.json");
-
-// 加速前缀。顺序即优先级：先国内镜像，最后官方直连兜底。
-// 这类代理的契约是 `<prefix><完整 url>`，社区通用。
-const MIRRORS = [
-  "https://gh-proxy.com/",
-  "https://ghfast.top/",
-  "https://ghproxy.net/",
-  "", // 空串 = 直连
-];
+const { MIRROR_ENV, mirrorLabel, resolveMirrors } = require("./mirror");
+const { downloadArtifact, fetchChecksums, tempPath } = require("./download");
 
 const REPO = "jixoai/reply9842";
 const KINDS = ["cli", "gui", "server"];
@@ -96,56 +93,81 @@ function releaseUrl(version, name) {
   return `https://github.com/${REPO}/releases/download/v${version}/${name}`;
 }
 
-/** 下载到 dest，带进度。mirror 为前缀，空串表示直连。 */
-async function download(url, dest, mirror) {
-  const res = await fetch(mirror + url, { redirect: "follow" });
-  if (!res.ok) throw new Error(`HTTP ${res.status}`);
-
-  const tmp = `${dest}.part`;
-  await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+function checksumsUrl(version) {
+  return `https://github.com/${REPO}/releases/download/v${version}/SHA256SUMS.txt`;
+}
 
-  const total = Number(res.headers.get("content-length") || 0);
-  const chunks = [];
-  let got = 0;
+/** 进度条（stderr，10% 一档，避免刷屏拖慢传输） */
+function makeProgress(name) {
   let lastPct = -1;
-
-  for await (const chunk of res.body) {
-    chunks.push(chunk);
-    got += chunk.length;
-    if (total > 0) {
-      const pct = Math.floor((got / total) * 100);
-      if (pct !== lastPct && pct % 10 === 0) {
-        process.stderr.write(`\r  下载 ${pct}% (${(got / 1048576).toFixed(1)}MB)`);
-        lastPct = pct;
+  let drawn = false;
+  const clear = () => {
+    if (drawn) process.stderr.write("\r" + " ".repeat(52) + "\r");
+    drawn = false;
+  };
+  return {
+    onProgress(ev) {
+      if (ev.phase === "info") {
+        process.stderr.write(`    ${ev.message}\n`);
+        return;
       }
-    }
-  }
-  if (total > 0) process.stderr.write("\r" + " ".repeat(40) + "\r");
-
-  await fs.promises.writeFile(tmp, Buffer.concat(chunks));
-  await fs.promises.rename(tmp, dest); // 原子落盘
-  if (process.platform !== "win32") await fs.promises.chmod(dest, 0o755);
-}
-
-/** 依次尝试镜像，任一成功即返回 */
-async function downloadWithMirrors(url, dest) {
-  let lastErr;
-  for (const m of MIRRORS) {
-    const label = m ? new URL(m).hostname : "github.com（直连）";
-    process.stderr.write(`  尝试 ${label} …\n`);
-    try {
-      await download(url, dest, m);
-      return true;
-    } catch (e) {
-      lastErr = e;
-      process.stderr.write(`    失败：${e.message}\n`);
-    }
+      if (ev.phase === "start" && ev.resumed) {
+        process.stderr.write(
+          `    续传：从 ${(ev.written / 1048576).toFixed(1)}MB / ${(ev.total / 1048576).toFixed(1)}MB 继续\n`,
+        );
+        lastPct = -1;
+      }
+      if (ev.phase !== "progress" || !ev.total) return;
+      const pct = Math.floor((ev.written / ev.total) * 100);
+      if (pct === lastPct) return;
+      if (pct % 10 !== 0 && pct !== 100) return;
+      lastPct = pct;
+      drawn = true;
+      process.stderr.write(
+        `\r    下载 ${name} ${String(pct).padStart(3)}% (${(ev.written / 1048576).toFixed(1)}MB)`,
+      );
+    },
+    clear,
+  };
+}
+
+/** 依次尝试镜像下载，返回实际使用的镜像前缀 */
+async function downloadWithMirrors(url, dest, { prefixes, expectedSha256 } = {}) {
+  const list = prefixes || resolveMirrors();
+  const prog = makeProgress(path.basename(dest));
+  try {
+    const { bytes, prefix } = await downloadArtifact({
+      url,
+      dest,
+      prefixes: list,
+      expectedSha256,
+      onProgress: prog.onProgress,
+      log: (line) => process.stderr.write(line + "\n"),
+    });
+    return { bytes, prefix, mirrors: list };
+  } finally {
+    prog.clear();
   }
-  throw lastErr || new Error("全部镜像失败");
 }
 
 // ---- 主流程 ----
 
+/**
+ * 解析镜像列表，失败时给出可操作提示并退出（不甩栈：这是配置错误，不是程序缺陷）。
+ * @returns {string[]|null} 且在出错时已 process.exit
+ */
+function effectiveMirrors() {
+  try {
+    return resolveMirrors();
+  } catch (e) {
+    process.stderr.write(
+      `reply9842: ${MIRROR_ENV} 配置有误 —— ${e.message}\n` +
+        `  示例: ${MIRROR_ENV}=https://gh-proxy.com/  或  ${MIRROR_ENV}=direct\n`,
+    );
+    process.exit(1);
+  }
+}
+
 function usage(kind) {
   const bins = {
     cli: "reply9842 [参数...]",
@@ -159,7 +181,23 @@ function usage(kind) {
     `  ${bins[kind] || "reply9842 <cli|gui|server> [参数...]"}`,
     "",
     "首次运行会从 GitHub Release 下载对应平台的二进制（8-17MB），",
-    "缓存后不再重复下载。国内网络自动走 gh-proxy 加速。",
+    "缓存后不再重复下载。中断后再次运行会从断点续传（.part 落盘）。",
+    "",
+    "镜像（加速前缀）配置:",
+    `  ${MIRROR_ENV}=<前缀>[,<前缀>...]`,
+    "",
+    "  - 逗号分隔，顺序即优先级（回退链）；每项两侧空白会被忽略，空项跳过",
+    "  - 前缀末尾的 / 可省略，会自动补全",
+    "  - 写 direct 表示直连（如 REPLY9842_MIRROR=direct）；整串留空同样视为直连",
+    "  - 只写前缀，程序会在后面拼完整 URL：<前缀>https://github.com/...",
+    "  - 不设置该变量时使用下面内置的默认顺序",
+    "",
+    "  例:",
+    `    ${MIRROR_ENV}=https://gh-proxy.com/ npx reply9842`,
+    `    ${MIRROR_ENV}="https://my.mirror/,https://gh-proxy.com/,direct" npx reply9842`,
+    "",
+    "  当前生效顺序:",
+    ...effectiveMirrors().map((p, i) => `    ${i + 1}. ${mirrorLabel(p)}${p ? `  (${p})` : ""}`),
     "",
     `缓存目录: ${cacheRoot()}`,
     "",
@@ -167,8 +205,8 @@ function usage(kind) {
 }
 
 /** 根据调用名或首参数决定 kind */
-function resolveKind(argv) {
-  const invoked = path.basename(process.argv[1] || "");
+function resolveKind(argv, argv1 = process.argv[1]) {
+  const invoked = path.basename(argv1 || "");
   if (invoked === "reply9842-gui") return { kind: "gui", args: argv };
   if (invoked === "reply9842-server") return { kind: "server", args: argv };
   if (argv.length > 0 && KINDS.includes(argv[0])) {
@@ -197,25 +235,49 @@ async function ensureBinary(kind, version) {
     /* 未缓存，继续下载 */
   }
 
-  process.stderr.write(`reply9842: 首次运行，下载 ${name}（v${version}）\n`);
   const url = releaseUrl(version, name);
+  const prefixes = effectiveMirrors();
+  const partialBytes = await fs.promises
+    .stat(tempPath(dest))
+    .then((s) => s.size)
+    .catch(() => 0);
+
+  process.stderr.write(
+    `reply9842: 首次运行，下载 ${name}（v${version}）` +
+      (partialBytes > 0
+        ? `，检测到未完成的下载 ${(partialBytes / 1048576).toFixed(1)}MB，将续传\n`
+        : "\n"),
+  );
+
+  // SHA256SUMS.txt 是 best-effort：取不到就只靠字节数校验，不阻塞下载
+  let expectedSha256 = null;
+  const sums = await fetchChecksums({ url: checksumsUrl(version), prefixes });
+  if (sums) expectedSha256 = sums.get(name) || null;
+
   try {
-    await downloadWithMirrors(url, dest);
-    process.stderr.write(`  已缓存到 ${dest}\n`);
+    const { bytes, prefix } = await downloadWithMirrors(url, dest, {
+      prefixes,
+      expectedSha256,
+    });
+    process.stderr.write(
+      `  已缓存到 ${dest}（${(bytes / 1048576).toFixed(1)}MB，来源 ${mirrorLabel(prefix)}` +
+        `${expectedSha256 ? "，SHA256 已校验" : ""}）\n`,
+    );
     return dest;
   } catch {
     process.stderr.write(
       `\nreply9842: 下载失败。\n` +
         `  手动下载：${url}\n` +
         `  放到：${dest}\n` +
-        `  或源码构建：go install github.com/${REPO}/cmd/${kind}@v${version}\n`,
+        `  或源码构建：go install github.com/${REPO}/cmd/${kind}@v${version}\n` +
+        `  镜像加速：${MIRROR_ENV}=https://gh-proxy.com/ npx reply9842\n`,
     );
     process.exit(1);
   }
 }
 
-async function main() {
-  const { kind, args } = resolveKind(process.argv.slice(2));
+async function main(argv = process.argv.slice(2)) {
+  const { kind, args } = resolveKind(argv);
 
   if (args[0] === "-h" || args[0] === "--help") {
     usage(kind);
@@ -247,7 +309,33 @@ async function main() {
   });
 }
 
-main().catch((e) => {
-  process.stderr.write(`reply9842: ${e.stack || e.message}\n`);
-  process.exit(1);
-});
+/** 只有被 bin/*.js 或直接 node lib/run.js 启动时才跑主流程，测试里 require 保持纯函数可测 */
+function invokedAsEntry() {
+  if (require.main === module) return true;
+  const name = path.basename((require.main && require.main.filename) || "");
+  return (
+    name === "reply9842.js" ||
+    name === "reply9842-gui.js" ||
+    name === "reply9842-server.js"
+  );
+}
+
+if (invokedAsEntry()) {
+  main().catch((e) => {
+    process.stderr.write(`reply9842: ${e.stack || e.message}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  artifactName,
+  binaryPath,
+  cacheRoot,
+  ensureBinary,
+  goarch,
+  goos,
+  main,
+  releaseUrl,
+  resolveKind,
+  usage,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reply9842",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "RFC 9842 增量压缩隧道：把 AI Agent 的上行带宽砍掉 99.8%。启动器按需下载对应平台的 cli / gui / server 二进制",
   "keywords": [
     "rfc9842",