@modusensus/dsh-mneme 0.8.1 → 0.8.3

package/lib/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, ...pipelineOptions } = options ?? {};
+  const { runtimeDir, remoteHost, resilientModelDownload, logger, ...pipelineOptions } = options ?? {};
   const { module } = await loadTransformers({
     runtimeDir: runtimeDir || defaultRuntimeDir()
   });
@@ -41,6 +42,17 @@ async function defaultPipelineLoader(task, model, options) {
   // model is fully cached locally. Mirroring the cache_dir onto env.cacheDir
   // makes that pre-check resolve locally too — fully offline loading.
   if (pipelineOptions.cache_dir) env.cacheDir = pipelineOptions.cache_dir;
+  // issue #188 补充：embedModelMirror 此前是死配置（定义了但全仓无人读取）。
+  // transformers.js 不认 HF_ENDPOINT（那是 Python huggingface_hub 的变量），
+  // 模型下载源由 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);
 }
 
@@ -71,7 +83,12 @@ 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();
     this.logger = opts.logger ?? null;
     // Test hook: replace the pipeline factory without touching modules.
     this.engineFactory = opts.engineFactory || defaultPipelineLoader;
@@ -91,6 +108,9 @@ export class LocalEmbedder {
     if (this.cacheDir) options.cache_dir = this.cacheDir;
     // 传给注入的 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/lib/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, ...pipelineOptions } = options ?? {};
+  const { runtimeDir, remoteHost, resilientModelDownload, logger, ...pipelineOptions } = options ?? {};
   const { module } = await loadTransformers({
     runtimeDir: runtimeDir || defaultRuntimeDir()
   });
@@ -36,6 +37,16 @@ async function defaultPipelineLoader(task, model, options) {
   // 的 cache_dir，回退到 env.cacheDir —— 即使模型已完全缓存在本地也会去请求网络。
   // embedder 侧早就镜像了，reranker 侧一直漏着，于是「已缓存 + 离线」时重排初始化会失败。
   if (pipelineOptions.cache_dir) env.cacheDir = pipelineOptions.cache_dir;
+  // issue #188 补充：embedModelMirror 此前是死配置——transformers.js 不认
+  // 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);
 }
 
@@ -85,6 +96,13 @@ export class LocalReranker {
     this.cacheDir = String(opts.cacheDir ?? "").trim() || defaultModelCacheDir();
     // 自管运行时根目录（issue #131）：空表示用默认位置，解析交给 loader。
     this.runtimeDir = String(opts.runtimeDir ?? "").trim();
+    // 与嵌入层同约定：默认 q8（4 倍小的 model_quantized.onnx），"fp32" 可关。
+    // 此前不传 dtype，即使缓存里有量化文件也会去要 1GB 级的 model.onnx（#188）。
+    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()
@@ -94,6 +112,7 @@ export class LocalReranker {
     this._batchScorer = null;
     this._queryVec = null;
     this._queryKey = null;
+    this._constantScoreWarned = false;
   }
 
   /** Load the model; throws when no strategy can be bound. */
@@ -119,9 +138,10 @@ export class LocalReranker {
   }
 
   _engineOptions() {
-    const options = { device: this.device };
+    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;
     return options;
   }
 
@@ -136,8 +156,14 @@ export class LocalReranker {
         return out.map((r) => clamp01(typeof r?.score === "number" ? r.score : 0));
       };
     } else if (strategy === "tc") {
-      // Classification head: tokenize (query, passage) pairs, score with
-      // sigmoid(l1 - l0) so relevance lands in [0, 1].
+      // Classification head: score so relevance lands in [0, 1]. Branch on the
+      // output width (issue #188): a dual-logit head (num_labels=2 exports,
+      // e.g. bge-reranker-v2-m3) gives the positive class as the softmax
+      // probability sigmoid(l1 - l0); a SINGLE-logit head (e.g.
+      // Xenova/bge-reranker-base) emits one raw relevance logit per pair, and
+      // the positive class is simply sigmoid(logit) — reading l1 as l0 there
+      // collapses every score to sigmoid(0) = 0.5 and silently disables
+      // reranking (no error, status still "ready").
       this._batchScorer = async (query, passages) => {
         const { tokenizer, model } = this.pipeline;
         const inputs = tokenizer(passages.map(() => query), {
@@ -151,10 +177,10 @@ export class LocalReranker {
         const rows = [];
         for (let i = 0; i < dims[0]; i++) {
           const base = i * cols;
-          const l0 = logits.data[base];
-          const l1 = cols > 1 ? logits.data[base + 1] : l0;
-          // sigmoid(l1 - l0) == softmax probability of the positive class.
-          rows.push(clamp01(1 / (1 + Math.exp(l0 - l1))));
+          const score = cols > 1
+            ? 1 / (1 + Math.exp(logits.data[base] - logits.data[base + 1]))
+            : 1 / (1 + Math.exp(-logits.data[base]));
+          rows.push(clamp01(score));
         }
         return rows;
       };
@@ -208,6 +234,19 @@ export class LocalReranker {
         results.push({ id: chunk[j].id, score: clamp01(Number(scores[j]) || 0) });
       }
     }
+    // Silent-failure tripwire (issue #188): a reranker whose every candidate
+    // scores identically is not ranking anything — e.g. a single-logit head
+    // read through the dual-logit formula. Warn once so the degradation is
+    // observable instead of a constant 0.5 column hiding behind a "ready"
+    // status forever.
+    if (results.length > 1 && results.every((r) => r.score === results[0].score)) {
+      if (!this._constantScoreWarned) {
+        this._constantScoreWarned = true;
+        this.logger?.warn?.(
+          `[dsh-mneme] reranker scores degenerated to a constant (${results[0].score}) — check the model's output dims (single vs dual logit head)`
+        );
+      }
+    }
     return results
       .filter((r) => r.score >= this.scoreThreshold)
       .sort((a, b) => b.score - a.score);

package/lib/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;
+}

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) &&
@@ -1292,6 +1300,22 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           if (m && !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten && codingGate(m)) semanticItems.push(m);
         }
       }
+      // Issue #198：首轮（无向量、无缓存召回）的同步兜底——BM25 词法召回领位。
+      // 注入渲染是同步的（宿主 systemPrompt 的 contexts 不支持异步 text），
+      // 查询向量只能异步 prefetch 给下一轮，首轮必 miss；此时纯静态排序会让
+      // 老的高重要性 summary/preference 占满槽位，当前话题的 decision/project
+      // 进不来。查询文本本身就在手上，BM25 是纯进程内同步计算，词法相关性
+      // 足以把当前话题顶到前排；门控与向量路径一致（含 importance 阈值）。
+      // 语义向量命中时本分支不参与，行为不变。
+      if (!semanticItems.length) {
+        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)) {
+            semanticItems.push(hit);
+          }
+        }
+      }
       if (semanticItems.length) {
         const seen = new Set();
         const merged = [];
@@ -1302,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;
@@ -1330,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",