@modusensus/dsh-mneme 0.8.2 → 0.8.3

package/lib/service.js

@@ -1235,7 +1235,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
    * fills + dedupes the remaining slots. Empty query / no cached recall /
    * hybridInject off → pure legacy rule-based selection.
    */
-  function injectCandidates({ query = "", maxItems = 5, threshold = 3, queryVector, scope = null } = {}) {
+  function injectCandidates({ query = "", maxItems = 5, threshold = 3, queryVector, scope = null, rotate = null, rotateWindow = 0 } = {}) {
     const q = String(query ?? "").trim();
     // codingRetrospect 读取侧门控：编码记忆（rejected_solution / pitfall /
     // constraint）只在编码任务时注入，防噪声污染其他业务；编码任务时按
@@ -1246,7 +1246,15 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     // (quality_score null) count as 100 (weight 1), so legacy stores keep their
     // exact summary>preference>importance ordering.
     const qualityWeight = (m) => (m.quality_score != null ? m.quality_score / 100 : 1);
-    const items = store.list({ limit: 200, includeForgotten: false })
+    // Issue #205 补测：候选池必须比轮换窗口大——窗口 N 需要 maxItems×(N+1) 张
+    // 不同的牌，池子只有 maxItems×2 时窗口一开就被吃光、只剩回填（重复率的
+    // 结构性下限由池子大小决定）。无轮换时保持既有 maxItems×2 不变；规则路
+    // 的 200 条上限同样给轮换让路（上限翻倍也只是多读一次 SQL LIMIT）。
+    const rotateWindowN = Number.isInteger(rotateWindow) && rotateWindow > 0 ? rotateWindow : 0;
+    const poolSize = rotateWindowN > 0
+      ? Math.max(maxItems * 2, maxItems * (rotateWindowN + 1))
+      : maxItems * 2;
+    const items = store.list({ limit: Math.max(200, poolSize), includeForgotten: false })
       .filter((m) => !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten &&
         codingGate(m) &&
         (m.type === "summary" || m.type === "preference" || m.importance >= threshold))
@@ -1277,7 +1285,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       const semanticItems = [];
       if (Array.isArray(queryVector) && queryVector.length && vectorIndex) {
         try {
-          const hits = vectorIndex.search(queryVector, { limit: maxItems * 2, threshold: 0 });
+          const hits = vectorIndex.search(queryVector, { limit: poolSize, threshold: 0 });
           for (const m of hits) {
             if (m && !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten &&
               codingGate(m) &&
@@ -1300,7 +1308,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       // 足以把当前话题顶到前排；门控与向量路径一致（含 importance 阈值）。
       // 语义向量命中时本分支不参与，行为不变。
       if (!semanticItems.length) {
-        for (const hit of bm25Recall(q, maxItems * 2)) {
+        for (const hit of bm25Recall(q, poolSize)) {
           if (hit && !hit.archived && INJECT_TYPES.has(hit.type) && !hit.forgotten &&
             codingGate(hit) &&
             (hit.type === "summary" || hit.type === "preference" || hit.importance >= threshold)) {
@@ -1318,10 +1326,10 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         };
         for (const m of semanticItems) {
           push(m);
-          if (merged.length >= maxItems * 2) break;
+          if (merged.length >= poolSize) break;
         }
         for (const m of items) {
-          if (merged.length >= maxItems * 2) break;
+          if (merged.length >= poolSize) break;
           push(m);
         }
         candidates = merged;
@@ -1346,6 +1354,14 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     if (config?.strictScope === true && scope) {
       candidates = candidates.filter((m) => isVisibleInScope(m, scope));
     }
+    // Issue #205：注入位跨轮轮换。rotate = 最近 N 轮注入过的 id 集合（由注入层
+    // 按会话维护并传入）：这些条目本轮不再优先——新鲜者前置（各自内部相对次序
+    // 保持），不足时按原序回填，槽位数与 touchRecall 语义均不变。rotate 为空时
+    // 行为与既有排序完全一致。
+    if (rotate && rotate.size > 0 && candidates.length > 0) {
+      const fresh = candidates.filter((m) => !rotate.has(m.id));
+      if (fresh.length > 0) candidates = [...fresh, ...candidates.filter((m) => rotate.has(m.id))];
+    }
     const selected = candidates.slice(0, maxItems);
     touchRecalled(selected);
     return selected;

package/lib/settings.js

@@ -52,6 +52,7 @@ const FEATURE_FLAG_BOOLEANS = [
   "selectiveInjectEnabled",
   "searchSemanticDedup",
   "rerankEnabled",
+  "resilientModelDownload",
   "adaptiveThresholdEnabled",
   "reflectionUpdateEnabled",
   "reflectionFailureTracking",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 7 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/config.js

@@ -37,6 +37,11 @@ export const Config = z.object({
   distillRateLimitRetries: z.natural().min(0).max(10).default(3),
   distillRateLimitBaseDelayMs: z.natural().min(100).max(60000).default(1000),
   maxInjectedItems: z.natural().min(1).max(20).default(5),
+  // Issue #205：注入位跨轮轮换。同一会话里，最近 N 个不同用户查询轮次注入过
+  // 的记忆本轮不再优先（新鲜优先、原序回填，槽位数不变）；长会话中避免相邻
+  // 轮次反复注入同一条（实测 15.5h 会话 86 次注入 93% 重复）。0 = 关闭（默认，
+  // 保持既有行为）。会话边界自动重置：新会话从零开始。
+  injectRotationTurns: z.natural().min(0).max(20).default(0),
   importanceThreshold: z.natural().min(1).max(5).default(3),
   // 编码记忆蒸馏（codingRetrospect，opt-in，默认关）。开启时，turn/end 蒸馏
   // 额外提取三类编码专属记忆：rejected_solution（被否决方案）/ pitfall（踩坑）/
@@ -180,6 +185,11 @@ export const Config = z.object({
   embedModelCacheDir: z.string().default(""),
   embedModelMirror: z.string().default("https://hf-mirror.com"),
 
+  // issue #194：模型文件下载的断点续传与重试。开启时 transformers.js 的 env.fetch 被
+  // 替换为带断点续传的实现（已收字节落盘、Range/If-Range 续传、空闲看门狗），大文件
+  // 中断后不必整份重来；关闭 = env.fetch 保持原样（线上回滚开关）。
+  resilientModelDownload: z.boolean().default(true),
+
   // 自管运行时目录（issue #131）。空 = ~/.dsh/mneme/runtime：里面放收编或下载来的
   // transformers + onnxruntime 闭包，插件经 src/runtime/loader.js 的三层解析加载它。
   // 目的就是让这条重依赖不必留在宿主 profile 的依赖图里——profile 是所有插件共用的

package/src/index.js

@@ -277,6 +277,7 @@ export const apply = (ctx, config) => {
         runtimeDir: cfg.runtimeDir,
         // #188：embedModelMirror 接成 transformers 的下载镜像（此前死配置）。
         remoteHost: cfg.embedModelMirror,
+        resilientModelDownload: cfg.resilientModelDownload,
         baseUrl: cfg.ollamaBaseUrl,
         logger: ctx.logger
       });
@@ -333,6 +334,7 @@ export const apply = (ctx, config) => {
         // embedModelMirror 此前是死配置，现接成 transformers 的下载镜像。
         useDtype: cfg.rerankDtype,
         remoteHost: cfg.embedModelMirror,
+        resilientModelDownload: cfg.resilientModelDownload,
         logger: ctx.logger
       });
       service.setReranker(reranker);

package/src/inject.js

@@ -94,6 +94,41 @@ export function createInjector(ctx, service, settings, config) {
   const language = langOf(config);
   const maxItems = config.maxInjectedItems ?? 5;
   const threshold = config.importanceThreshold ?? 3;
+  // Issue #205：注入位跨轮轮换。rotationTurns = 最近 N 个「不同用户查询」轮次
+  // 注入过的记忆本轮不再优先（0 = 关闭，保持既有行为）。历史按会话维护——
+  // 新会话从零开始；同一查询的多次渲染（工具调用轮）视为同一轮，不推进窗口。
+  const rotationTurns = Math.max(0, Math.floor(config.injectRotationTurns ?? 0));
+  const rotationHistory = new Map(); // sessionId -> [{ query, ids: Set }]
+  const ROTATION_HISTORY_MAX = 32; // 覆盖 max(20) 配置档仍有余量
+
+  function recentInjectedIds(sessionId, query) {
+    if (rotationTurns <= 0) return null;
+    const deque = rotationHistory.get(sessionId);
+    if (!deque || deque.length === 0) return null;
+    // 只看「之前的轮次」：排除与当前查询相同的条目——同一查询的重复渲染
+    // （工具调用轮）不该拿本轮自己的集合来转自己。
+    const prior = query ? deque.filter((e) => e.query !== query) : deque;
+    if (prior.length === 0) return null;
+    const recent = new Set();
+    for (const entry of prior.slice(-rotationTurns)) {
+      for (const id of entry.ids) recent.add(id);
+    }
+    return recent.size > 0 ? recent : null;
+  }
+
+  function recordInjection(sessionId, query, candidates) {
+    if (rotationTurns <= 0 || !query) return;
+    const deque = rotationHistory.get(sessionId) ?? [];
+    const ids = new Set(candidates.map((c) => c.id));
+    const last = deque[deque.length - 1];
+    if (last && last.query === query) {
+      last.ids = ids; // 同一查询的重复渲染：覆盖本轮内容，不推进窗口
+    } else {
+      deque.push({ query, ids });
+      if (deque.length > ROTATION_HISTORY_MAX) deque.shift();
+      rotationHistory.set(sessionId, deque);
+    }
+  }
   // v0.8.0 A3（issue #17）：注入路径的会话 scope 解析——strictScope 硬过滤
   // 需要。渲染 ctx 与工具 exec 同形（agent.session），解析器直接复用。
   // logger 透传：registry 反查失败时 warnOnce 才有出口。
@@ -226,7 +261,13 @@ export function createInjector(ctx, service, settings, config) {
         // v0.8.0 A3：scope 随请求解析（strict 开启时 injectCandidates 内硬过滤；
         // flag 关闭时解析器返回 null，注入行为不变）。
         const scope = resolveSessionScope(ctx);
-        const candidates = service.injectCandidates({ query, queryVector, maxItems, threshold, scope });
+        // Issue #205：跨轮轮换——最近 N 个查询轮次注入过的 id 本轮不再优先。
+        const sessionId = ctx?.agent?.session?.id ?? "_";
+        const rotate = recentInjectedIds(sessionId, query);
+        // rotateWindow 随集合一起传入：候选池按 maxItems×(N+1) 扩容——窗口要的
+        // 牌比既有 maxItems×2 池多时，轮换才有新鲜牌可换（#205 补测）。
+        const candidates = service.injectCandidates({ query, queryVector, maxItems, threshold, scope, rotate, rotateWindow: rotationTurns });
+        recordInjection(sessionId, query, candidates);
         // Hot memory (v0.5.0 1.3) leads the single memory block: the agent
         // sees the short-term rounds first, then the cross-session recall —
         // the documented injection order 1→2. Folding it here (instead of a
@@ -246,6 +287,7 @@ export function createInjector(ctx, service, settings, config) {
 
   return () => {
     queryVectorCache.clear();
+    rotationHistory.clear();
     for (const dispose of disposers) {
       if (typeof dispose === "function") dispose();
     }

package/src/local-embedder.js

@@ -4,6 +4,7 @@
 // can pick a backend by provider name and degrade gracefully on failure.
 // Methods throw on error — the caller decides the fallback chain.
 import { defaultModelCacheDir, defaultRuntimeDir } from "./runtime/layout.js";
+import { installResilientFetch } from "./runtime/model-fetch.js";
 import { loadTransformers } from "./runtime/loader.js";
 
 const DEFAULT_TIMEOUT_MS = 15000;
@@ -30,7 +31,7 @@ function modelHash(model) {
  * transformers 的选项里。
  */
 async function defaultPipelineLoader(task, model, options) {
-  const { runtimeDir, remoteHost, ...pipelineOptions } = options ?? {};
+  const { runtimeDir, remoteHost, resilientModelDownload, logger, ...pipelineOptions } = options ?? {};
   const { module } = await loadTransformers({
     runtimeDir: runtimeDir || defaultRuntimeDir()
   });
@@ -46,6 +47,12 @@ async function defaultPipelineLoader(task, model, options) {
   // 模型下载源由 env.remoteHost 决定——把镜像接到真正的开关上，否则
   // huggingface.co 不可达的网络连模型都下不下来。
   if (remoteHost) env.remoteHost = remoteHost;
+  // issue #194：模型文件（几百 MB～1GB）下载中断后从断点续传。开关关 = env.fetch 一字不动。
+  installResilientFetch(env, {
+    enabled: resilientModelDownload === true,
+    cacheDir: pipelineOptions.cache_dir,
+    logger
+  });
   return pipeline(task, model, pipelineOptions);
 }
 
@@ -76,6 +83,9 @@ export class LocalEmbedder {
     this.cacheDir = String(opts.cacheDir ?? "").trim() || defaultModelCacheDir();
     // 自管运行时根目录（issue #131）：空表示用默认位置，具体解析交给 loader。
     this.runtimeDir = String(opts.runtimeDir ?? "").trim();
+    // issue #194：模型文件下载断点续传。只在显式传 true 时启用——直连构造的旧调用方
+    // （含测试）保持裸 fetch 的现状，配置默认值由 index.js 传进来。
+    this.resilientModelDownload = opts.resilientModelDownload === true;
     this.useDtype = opts.useDtype || "q8";
     // 模型镜像下载源（embedModelMirror，#188 补充）：空 = transformers 默认。
     this.remoteHost = String(opts.remoteHost ?? "").trim();
@@ -99,6 +109,8 @@ export class LocalEmbedder {
     // 传给注入的 engineFactory，由 defaultPipelineLoader 取走后交给三层解析。
     if (this.runtimeDir) options.runtimeDir = this.runtimeDir;
     if (this.remoteHost) options.remoteHost = this.remoteHost;
+    options.resilientModelDownload = this.resilientModelDownload;
+    options.logger = this.logger;
     this.extractor = await this.engineFactory("feature-extraction", this.model, options);
     this.ready = true; // service reads this to flush queued re-embeds
     this.logger?.info?.(

package/src/reranker.js

@@ -1,4 +1,5 @@
 import { defaultModelCacheDir, defaultRuntimeDir } from "./runtime/layout.js";
+import { installResilientFetch } from "./runtime/model-fetch.js";
 import { loadTransformers } from "./runtime/loader.js";
 
 // Cross-encoder re-ranker for dsh-mneme recall candidates. Uses
@@ -27,7 +28,7 @@ function modelHash(model) {
  * runtimeDir 取走后不混进 transformers 的选项。
  */
 async function defaultPipelineLoader(task, model, options) {
-  const { runtimeDir, remoteHost, ...pipelineOptions } = options ?? {};
+  const { runtimeDir, remoteHost, resilientModelDownload, logger, ...pipelineOptions } = options ?? {};
   const { module } = await loadTransformers({
     runtimeDir: runtimeDir || defaultRuntimeDir()
   });
@@ -40,6 +41,12 @@ async function defaultPipelineLoader(task, model, options) {
   // HF_ENDPOINT（那是 Python huggingface_hub 的变量），下载源由 env.remoteHost
   // 决定。把镜像接到真正的开关上，huggingface.co 不可达的网络才能自动下载。
   if (remoteHost) env.remoteHost = remoteHost;
+  // issue #194：与 embedder 同款断点续传。开关关 = env.fetch 一字不动。
+  installResilientFetch(env, {
+    enabled: resilientModelDownload === true,
+    cacheDir: pipelineOptions.cache_dir,
+    logger
+  });
   return pipeline(task, model, pipelineOptions);
 }
 
@@ -94,6 +101,8 @@ export class LocalReranker {
     this.useDtype = String(opts.useDtype ?? "q8").trim() || "q8";
     // 模型镜像下载源（embedModelMirror，#188 补充）：空 = transformers 默认。
     this.remoteHost = String(opts.remoteHost ?? "").trim();
+    // issue #194：模型文件下载断点续传。只在显式传 true 时启用，与 embedder 同规。
+    this.resilientModelDownload = opts.resilientModelDownload === true;
     this.logger = opts.logger ?? null;
     this.engineFactory = opts.engineFactory || defaultPipelineLoader;
     // Injectable seam: async (query, passage) => number. When set, init()
@@ -129,7 +138,7 @@ export class LocalReranker {
   }
 
   _engineOptions() {
-    const options = { device: this.device, dtype: this.useDtype };
+    const options = { device: this.device, dtype: this.useDtype, resilientModelDownload: this.resilientModelDownload, logger: this.logger };
     if (this.cacheDir) options.cache_dir = this.cacheDir;
     if (this.runtimeDir) options.runtimeDir = this.runtimeDir;
     if (this.remoteHost) options.remoteHost = this.remoteHost;

package/src/runtime/model-fetch.js

@@ -0,0 +1,361 @@
+// 模型文件取件（issue #194）
+//
+// transformers.js 下载模型文件（如 model.onnx，约 1GB）走它自己的 env.fetch；undici
+// socket 中途被重置（TypeError: terminated）时整份下载作废重来。4.2.0 的 env.fetch 是
+// 官方文档化的可替换面（env.js: `fetch: DEFAULT_FETCH`），所以韧性做在这一层：对
+// transformers.js 而言这仍然是一个普通的 fetch，成功路径的语义一点没变；变化只发生在
+// 失败路径 —— 已收的字节落在磁盘 .part 里，重试（包括换一次进程）从断点继续。
+//
+// 硬规矩（与 runtime/download.js 的取件层同一套直觉）：
+//   1. 交给下游的响应永远是规范的 200 + 完整 content-length。hub.js 把非 200 一律当
+//      失败处理，206 直接透传反而会破坏下游；断点拼接是我们内部的事，不能漏出去。
+//   2. 续传前带 If-Range：断点对应的内容若在服务端被换过，服务器会回 200（全量）。
+//      旧断点拼新内容是一份静默损坏的模型 —— 宁可整份重来，不可拼错。
+//   3. 同一 URL 的 .part 同一时刻只允许一个写者。两个进程并发追加同一份字节是写损坏；
+//      抢不到锁就按现状直接转发（裸 fetch），让持锁的那份去落盘。
+//
+// @module dsh-mneme/runtime/model-fetch
+import { createHash } from "node:crypto";
+import { closeSync, createReadStream, existsSync, futimesSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { Readable } from "node:stream";
+import { join } from "node:path";
+import { defaultModelCacheDir } from "./layout.js";
+
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_RETRY_DELAY_MS = 1000;
+const DEFAULT_MAX_RETRY_DELAY_MS = 15000;
+// 看门狗是「连续无字节」上限而不是总时长上限：几百 MB～1GB 的文件在慢网下合法地要下
+// 几十分钟，总时长上限会掐死健康但慢的下载；连续这么久一个字节都没有才是 socket 僵死。
+const DEFAULT_IDLE_TIMEOUT_MS = 120000;
+// 锁的 mtime 超过这么久没刷新 = 持锁方已死（活着的话每个进度节拍都会刷新），可以抢。
+const STALE_LOCK_MS = 30 * 60 * 1000;
+// 进度事件节流：1GB 按 64KB 一块是一万多个事件，逐个发出去日志没法看。
+const PROGRESS_EMIT_INTERVAL_MS = 500;
+
+/** URL → 稳定文件名。断点文件要跨进程、跨重启可复用，所以用内容寻址而不是 pid。 */
+function partName(url) {
+  return createHash("sha256").update(url).digest("hex");
+}
+
+function readMeta(metaPath) {
+  try {
+    return readFileSync(metaPath, "utf8").trim();
+  } catch {
+    return "";
+  }
+}
+
+function writeMeta(metaPath, etag) {
+  writeFileSync(metaPath, `${etag}\n`, "utf8");
+}
+
+/** 断点不可信（比源文件还大 / 内容对不上）时整体作废，而不是试着修剪。 */
+function resetPart(partPath, metaPath) {
+  rmSync(partPath, { force: true });
+  rmSync(metaPath, { force: true });
+}
+
+/**
+ * 拿 .part 的写锁。返回 fd（持有着，供流式期间刷新 mtime）或 null（别人在写）。
+ * 只尝试偷一次过期锁：再抢不到就放弃，调用方按现状裸转发。
+ */
+function acquireLock(lockPath, staleLockMs) {
+  for (let i = 0; i < 2; i++) {
+    try {
+      const fd = openSync(lockPath, "wx");
+      writeSync(fd, String(process.pid));
+      return fd;
+    } catch {
+      let age = Infinity;
+      try {
+        age = Date.now() - statSync(lockPath).mtimeMs;
+      } catch {}
+      if (age > staleLockMs) {
+        rmSync(lockPath, { force: true });
+        continue;
+      }
+      return null;
+    }
+  }
+  return null;
+}
+
+function releaseLock(lockPath, lockFd) {
+  if (lockFd === null) return;
+  try {
+    closeSync(lockFd);
+  } catch {}
+  rmSync(lockPath, { force: true });
+}
+
+/** 进度事件的百分数。total 未知时给 null，让日志退化为「已收字节数」。 */
+function percentOf(received, total) {
+  return Number.isFinite(total) && total > 0 ? Math.floor((received / total) * 100) : null;
+}
+
+/**
+ * 造一个「带断点续传的 fetch」。
+ * @param {object} opts - 选项。
+ * @param {Function} [opts.fetchImpl] - 底层 fetch，测试注入。
+ * @param {string} opts.partDir - 断点文件目录（应与模型缓存同盘）。
+ * @param {number} [opts.attempts] - 含首次在内的总尝试次数。
+ * @param {number} [opts.retryDelayMs] - 退避基数：1s → 2s → 4s，封顶 maxRetryDelayMs。
+ * @param {number} [opts.idleTimeoutMs] - 连续无字节的看门狗上限。
+ * @param {Function} [opts.onEvent] - resume / progress / restart / fail 事件回调。
+ * @param {Function} [opts.hash] - URL → 断点文件名，测试注入。
+ * @returns {Function} 与全局 fetch 同签名的函数。
+ */
+export function createResilientFetch({
+  fetchImpl = fetch,
+  partDir,
+  attempts = DEFAULT_ATTEMPTS,
+  retryDelayMs = DEFAULT_RETRY_DELAY_MS,
+  maxRetryDelayMs = DEFAULT_MAX_RETRY_DELAY_MS,
+  idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
+  onEvent = null,
+  hash = partName
+} = {}) {
+  if (typeof partDir !== "string" || partDir === "") {
+    throw new TypeError("createResilientFetch：partDir 是必填的（.part 断点文件落在这里）");
+  }
+  mkdirSync(partDir, { recursive: true });
+  const emit = (event) => {
+    try {
+      onEvent?.(event);
+    } catch {
+      // 进度回调的异常不该打断下载本身。
+    }
+  };
+
+  return async function resilientFetch(input, init = undefined) {
+    const url = typeof input === "string" ? input : String(input?.url ?? input);
+    const method = String(init?.method ?? "GET").toUpperCase();
+    // 非 GET（HEAD 元数据预检等）与带 body 的请求不落盘：原样转发，语义与裸 fetch 一致。
+    if (method !== "GET" || init?.body != null) return fetchImpl(input, init);
+
+    const partPath = join(partDir, hash(url));
+    const metaPath = `${partPath}.meta`;
+    const lockPath = `${partPath}.lock`;
+    const lockFd = acquireLock(lockPath, STALE_LOCK_MS);
+    if (lockFd === null) {
+      // 另一个进程正在下同一个文件。并发追加同一份 .part 是写损坏，所以这边不参与落盘，
+      // 按改动前的行为裸转发一次 —— 持锁方会正常下完，之后的加载会命中缓存。
+      return fetchImpl(input, init);
+    }
+
+    try {
+      return await downloadWithResume(url, init, {
+        fetchImpl,
+        partPath,
+        metaPath,
+        lockPath,
+        lockFd,
+        attempts,
+        retryDelayMs,
+        maxRetryDelayMs,
+        idleTimeoutMs,
+        emit
+      });
+    } catch (error) {
+      // 失败路径锁在这里释放；成功路径的锁随断点文件一起在响应体流关闭后清理 ——
+      // 若在返回响应时就放锁，另一个进程会在「.part 仍被下游流读着」的窗口里动它。
+      releaseLock(lockPath, lockFd);
+      throw error;
+    }
+  };
+}
+
+async function downloadWithResume(url, init, ctx) {
+  const { fetchImpl, partPath, metaPath, lockPath, lockFd, attempts, retryDelayMs, maxRetryDelayMs, idleTimeoutMs, emit } = ctx;
+  let lastError = null;
+  let lastPercent = null;
+  let lastReceived = 0;
+
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    let offset = 0;
+    if (existsSync(partPath)) {
+      offset = statSync(partPath).size;
+      if (offset > 0) {
+        emit({ type: "resume", url, offset, attempt });
+      }
+    }
+
+    const headers = new Headers(init?.headers);
+    if (offset > 0) {
+      headers.set("Range", `bytes=${offset}-`);
+      // If-Range：断点对应的内容在服务端被换过时，服务器回 200（全量）而不是 206 ——
+      // 那就整份重来。没有它，旧断点 + 新内容会拼出一份静默损坏的模型。
+      const storedEtag = readMeta(metaPath);
+      if (storedEtag) headers.set("If-Range", storedEtag);
+    }
+
+    const controller = new AbortController();
+    const onCallerAbort = () => controller.abort(init?.signal?.reason);
+    init?.signal?.addEventListener("abort", onCallerAbort, { once: true });
+    let idleTimer = null;
+    const armIdle = () => {
+      if (!(idleTimeoutMs > 0)) return;
+      if (idleTimer !== null) clearTimeout(idleTimer);
+      idleTimer = setTimeout(
+        () => controller.abort(new Error(`连接空闲超过 ${Math.round(idleTimeoutMs / 1000)}s 无数据`)),
+        idleTimeoutMs
+      );
+    };
+    armIdle();
+
+    let fd = -1;
+    let received = 0;
+    let total = null;
+    let lastEmitAt = 0;
+    const reportProgress = (force = false) => {
+      const now = Date.now();
+      if (!force && now - lastEmitAt < PROGRESS_EMIT_INTERVAL_MS) return;
+      lastEmitAt = now;
+      lastReceived = offset + received;
+      lastPercent = percentOf(lastReceived, total);
+      futimesSync(lockFd, new Date(), new Date()); // 锁的活着证明与进度同节拍刷新。
+      emit({ type: "progress", url, received: lastReceived, total, percent: lastPercent, attempt });
+    };
+
+    try {
+      const res = await fetchImpl(url, { ...init, headers, signal: controller.signal });
+
+      // Range 起点越过源文件末尾（断点比源还大，通常断点来自被替换前的旧文件）：
+      // 断点不可信 —— 清掉，这次尝试作废，下一次从 0 开始。不处理的话会在 416 上
+      // 把重试次数全部烧完，报一条用户看不懂的错。
+      if (res.status === 416) {
+        emit({ type: "restart", url, offset, attempt, reason: "range-not-satisfiable" });
+        resetPart(partPath, metaPath);
+        lastError = new Error("HTTP 416（断点已重置）");
+        continue;
+      }
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+
+      if (offset > 0 && res.status === 200) {
+        // 服务器无视了 Range，或 If-Range 判定内容已变：整份重来。
+        emit({ type: "restart", url, offset, attempt, reason: "range-rejected" });
+        resetPart(partPath, metaPath);
+        offset = 0;
+      }
+      if (res.status === 206) {
+        const cr = /bytes (\d+)-(\d+)\/(\d+)/.exec(res.headers.get("content-range") ?? "");
+        if (cr === null) throw new Error("206 响应缺少 Content-Range");
+        total = Number(cr[3]);
+        if (Number(cr[1]) !== offset) {
+          // 服务器续的位置和断点对不上：不猜（拼错的字节比下载失败更糟），清掉重来。
+          emit({ type: "restart", url, offset, attempt, reason: "offset-mismatch" });
+          resetPart(partPath, metaPath);
+          throw new Error(`断点偏移不一致（本地 ${offset}，服务器 ${cr[1]}），断点已重置`);
+        }
+      } else {
+        total = Number(res.headers.get("content-length")) || null;
+      }
+      const etag = res.headers.get("etag");
+      if (etag) writeMeta(metaPath, etag);
+
+      fd = openSync(partPath, "a");
+      if (res.body !== null) {
+        const reader = res.body.getReader();
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          writeSync(fd, value);
+          received += value.length;
+          armIdle();
+          reportProgress();
+        }
+      }
+      // 服务端"干净地"提前关流（不抛错、但字节没给够）也是断流的一种，必须查出来。
+      if (total !== null && offset + received !== total) {
+        throw new Error(`下载不完整：收到 ${offset + received}/${total} 字节`);
+      }
+      clearTimeout(idleTimer);
+      idleTimer = null;
+      reportProgress(true);
+      return partResponse(partPath, metaPath, lockPath, lockFd, offset + received, etag);
+    } catch (error) {
+      lastError = error;
+      lastReceived = offset + received;
+      lastPercent = percentOf(lastReceived, total);
+      emit({ type: "fail", url, received: lastReceived, total, percent: lastPercent, attempt, error: String(error?.message ?? error) });
+    } finally {
+      if (fd >= 0) closeSync(fd);
+      if (idleTimer !== null) clearTimeout(idleTimer);
+      init?.signal?.removeEventListener("abort", onCallerAbort);
+    }
+
+    if (attempt < attempts) {
+      // 退避：1s → 2s → 4s，封顶 maxRetryDelayMs。
+      await new Promise((resolve) => setTimeout(resolve, Math.min(retryDelayMs * 2 ** (attempt - 1), maxRetryDelayMs)));
+    }
+  }
+
+  // 最终失败的错误必须带中断位置（issue #194 的第 3 项）：用户要能区分是网络断了
+  // 还是磁盘满了，而不是看到一句干巴巴的 TypeError: terminated。
+  const where = lastPercent !== null ? `中断于 ${lastPercent}%（${lastReceived} 字节）` : `已收 ${lastReceived} 字节`;
+  throw new Error(`模型文件下载失败（试了 ${attempts} 次，${where}）：${lastError?.message ?? lastError}`);
+}
+
+/**
+ * 把完成的断点文件包装成给下游的响应：规范的 200 + 完整 content-length，body 从磁盘
+ * 流式读出（1GB 不进内存）。流关闭即清理断点文件 —— 它给下游（FileCache.put /
+ * arrayBuffer）供字节的使命结束了，不清的话一个 1GB 的副本会一直躺在缓存旁边。
+ */
+function partResponse(partPath, metaPath, lockPath, lockFd, size, etag) {
+  const nodeStream = createReadStream(partPath);
+  const cleanup = () => {
+    try {
+      rmSync(partPath, { force: true });
+      rmSync(metaPath, { force: true });
+      releaseLock(lockPath, lockFd);
+    } catch {}
+  };
+  nodeStream.on("close", cleanup);
+  nodeStream.on("error", cleanup);
+  return new Response(Readable.toWeb(nodeStream), {
+    status: 200,
+    headers: {
+      "content-type": "application/octet-stream",
+      "content-length": String(size),
+      ...(etag ? { etag } : {})
+    }
+  });
+}
+
+/** 把事件映射成日志。只发人该看的行：续传、重来、每次失败的位置 —— 不刷进度条。 */
+export function logModelFetchEvent(logger, event) {
+  const kb = (n) => (n >= 1048576 ? `${(n / 1048576).toFixed(1)}MB` : `${Math.round(n / 1024)}KB`);
+  const where = (e) => (e.percent !== null && e.percent !== undefined ? `${e.percent}%（${kb(e.received)}${e.total ? `/${kb(e.total)}` : ""}）` : kb(e.received ?? 0));
+  switch (event.type) {
+    case "resume":
+      logger?.info?.(`[dsh-mneme] 模型下载带断点续传：已有 ${kb(event.offset)}，第 ${event.attempt} 次尝试`);
+      break;
+    case "restart":
+      logger?.warn?.(`[dsh-mneme] 断点不可用（${event.reason}），模型下载从头再来`);
+      break;
+    case "fail":
+      logger?.warn?.(`[dsh-mneme] 模型下载中断于 ${where(event)}，第 ${event.attempt} 次尝试失败：${event.error}`);
+      break;
+    default:
+      break;
+  }
+}
+
+/**
+ * 把弹性 fetch 装到 transformers.js 的 env 上（embedder / reranker 共用这一个入口）。
+ * @param {object} env - transformers.js 的 env（至少支持赋值 fetch）。
+ * @param {object} opts - 选项。
+ * @param {boolean} [opts.enabled] - 开关；关 = 完全不动 env（默认保持现状的出口）。
+ * @param {string} [opts.cacheDir] - 模型缓存目录，断点文件落在它的 .mneme-partial 下。
+ * @param {object} [opts.logger] - 接收下载进度日志的 logger。
+ * @param {object} [opts.rest] - 透传给 createResilientFetch 的其余选项（测试注入）。
+ * @returns {boolean} 是否实际安装。
+ */
+export function installResilientFetch(env, { enabled = true, cacheDir = "", logger = null, ...rest } = {}) {
+  if (!enabled || !env) return false;
+  const root = String(cacheDir ?? "").trim() || defaultModelCacheDir();
+  const partDir = join(root, ".mneme-partial");
+  mkdirSync(partDir, { recursive: true });
+  env.fetch = createResilientFetch({ partDir, onEvent: (event) => logModelFetchEvent(logger, event), ...rest });
+  return true;
+}