@modusensus/dsh-mneme 0.8.2 → 0.8.3

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@modusensus/dsh-mneme?color=blue&label=npm)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-[![tests](https://img.shields.io/badge/tests-1061%20passed-success)](https://github.com/modusensus/dsh-mneme)
+[![tests](https://img.shields.io/badge/tests-1079%20passed-success)](https://github.com/modusensus/dsh-mneme)
 [![CI](https://img.shields.io/github/actions/workflow/status/modusensus/dsh-mneme/ci.yml)](https://github.com/modusensus/dsh-mneme/actions)
 [![node](https://img.shields.io/badge/node-22%2B-blue)](https://nodejs.org)
 [![npm downloads](https://img.shields.io/npm/dm/@modusensus/dsh-mneme?color=blue&label=downloads)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
@@ -230,6 +230,7 @@ v0.3.0 起新增**记忆基因**层：从记忆里抽取**命名实体**、**带
 |------|------|
 | **v0.8.1** | 归属显式声明与人工纠偏 + 插件版本自检：记忆归属三段式可控——per-dim 来源列 + save/update scope 参数 + 面板可编辑（#170 第 1 步，#171）；sleep 跨 scope 相似对停车进冲突队列人工裁决（第 2 步，#172）；`strictScope` 硬过滤只认显式声明、自动标注降为纯软加权（第 3 步，#173，4.3 已确认）；`GET /api/dsh-mneme/version-check` 只读路由 + 设置页偏差横幅（仅 outdated 渲染，registry 精确 host 白名单 + TTL 缓存 + 全失败静默，pnpm 钉子警示 + 市场收录延迟说明，#174 后续）；1026 测试全绿 |
 | **v0.8.2** | 生态与性能批次（社区贡献集中合入）：LLM 消息补 source 契约——严格 provider 下 dream/summarize/sleep/实体抽取不再序列化抛错（#189/#190）；memory_get 输出 schema 与共享 DTO 同源（#184/#186）；sleep 计时器撞 CD 重排 + 构造挂表（#187/#192）；单 logit 重排器恒 0.5 修复 + 镜像/量化接线（#188/#193）；连通性探测改发 user 消息（#197）；首轮注入 BM25 同步兜底——老偏好不再占满槽位（#198/#199）；autoDream 宽容路径闭环——coverage 不足降级 degraded + archive 类型护栏/批量上限 `dreamMaxArchivePerRun`（#104/#200/#201）；检索路径性能第一批——updated_at 索引 + all() 剪列 + 向量解析缓存（#202/#203，all() 231→51ms、searchVector ~140→16ms）；standalone API 补 profile/rules 路由（#180/#185）；1061 测试全绿 |
+| **v0.8.3** | 注入轮换与下载可靠性批次：注入位跨轮轮换 `injectRotationTurns`（默认 0 = 关）——同一会话相邻轮次不再反复注入同一条，窗口只看之前轮次、同查询工具轮不推进不转自己（sessionId 分桶 FIFO 32，#205/#206）；候选池四处扩容 `poolSize = maxItems × (轮换窗口 + 1)`（下限 200），旋钮开多大、池子就够多大（#208）；模型文件下载断点续传与重试 `resilientModelDownload`（默认开）——Range / If-Range 续传、416 / 偏移失配重置、单写者锁 + 降级直通 + 空闲看门狗（#194/#207）；1079 测试全绿 |
 | **v0.8.0** | 作用域隔离（issue #17 批次 A）+ 冲突集中处理 + 斜杠命令提交 Agent + 注入转义回归修复：记忆按 agent 与工作区双维标注（agent_scope / workspace_scope / sensitivity / occurred_at 四列可空），检索按当前会话作用域加权（命中 ×1.25、他 scope ×0.5 保留可见），opt-in `strictScope` 硬过滤贯通检索/注入/列表/单取（fail-closed）；`scopeEnabled` / `strictScope` 默认关、面板「作用域隔离」组可启停；去重键扩展含作用域三元——跨作用域同标题不再物理合并；`occurred_at` 事件发生时间 + `occurred_from/to` 过滤贯通搜索与列表；冲突冻结（conflictFreezeEnabled）新增人工出口——状态页冲突队列并排对比 + 保留 A/B/仅标记（#166）；斜杠命令经 agent.followup 真正提交模型（#152）；恢复 v0.7.4 的注入花括号转义 + hot memory 跳过 reasoning——`{{.Server.Version}}` 类文本不再卡死会话（#165）；988 测试全绿 |
 | **v0.7.32** | 冲突动作集扩展 + 运行时自管化 + 记忆/提示语言 + 候选集 hybrid 档 + 一批修复：`sleepActionSet` 新增 `full` 档（supersede/differentiate/update/merge/conflict/keep 六分支，默认 `conflict` 零行为变化）——supersede 赢家正文干净、输家归档附「已被取代」注记，differentiate 双留+差异注记；sleep 校验接入 `dreamSkipInvalid` 宽容策略（默认 true，一票否决变宽容，严格可关）；运行时三档取件（收编/本地 .tgz/registry）+ transformers 转可选 peer（#131）；`memory.language`（zh/en）提示/注入/镜像语言可选（#124）；summarize 节流 + 产出上限 + 同会话去重（#127）；inject 正文读取修复（#129）、#135 五连修（前缀解析/effort 最低档/importance 豁免/ready 语义/覆盖度降级告警）、boot 回填指纹短路修复（#128）、degraded 轮跳过明细落库（#104）；916 测试全绿、总覆盖 92.7%（runtime 96%、embedding 100%） |
 | **v0.7.30** | 状态页向量卡修复（issue #118）：改读开放的 `/semantic`——不再吃 `/vector-config` 的 401「加载失败」，ollama/local 模式不再恒显「未启用」；新增「初始化中（embedder 不可达，正在重试）」与「已索引 N / M 条」回填进度显示；legacy OpenAI 兼容 embedder「Object · 0D」显示修复（embedder 显式 `name: "OpenAI"` + 维度回退 `index.dimension`）；「已索引 N / M」分子分母同口径（`embeddedCount` 剔除归档/遗忘，与 `count()` 默认过滤对齐）；embedder init 失败有界重试（共 5 次，不再一次性永久降级，unload 清理定时器）+ `OllamaEmbedder.ready` 生命周期位 + `/semantic` 新增 `ready` 字段；745 测试全绿 |
@@ -339,6 +340,7 @@ v0.3.0 起新增**记忆基因**层：从记忆里抽取**命名实体**、**带
 | **v0.8.0** | ✅ 完成 | 作用域隔离 + 冲突队列 | 按 agent 与工作区双维隔离记忆（标注 / 检索加权 / opt-in strictScope 四路硬过滤，issue #17 批次 A）；冻结冲突新增人工确认队列（状态页并排对比，#166）；斜杠命令真正提交 Agent（#152）；注入转义回归恢复 + hot memory 跳过 reasoning（#162）。图谱增强（兴趣漂移可视化）、跨 workspace 记忆共享仍在规划 |
 | **v0.8.1** | ✅ 完成 | 归属显式声明与人工纠偏 + 插件版本自检 | 归属三段式可控：per-dim 来源列 + save/update scope 参数 + 面板可编辑（#170 第 1 步，#171）；sleep 跨 scope 相似对停车人工裁决接冲突队列（第 2 步，#172）；`strictScope` 硬过滤只认显式声明、自动标注降纯软加权（第 3 步，#173）。插件自报新版本：/version-check 只读路由 + 设置页 outdated 横幅（registry 精确白名单 + TTL 缓存 + 全失败静默，pnpm 钉子警示，#174 后续，#176）；1026 测试全绿 |
 | **v0.8.2** | ✅ 完成 | 生态与性能批次：宽容路径闭环 + 检索提速 + 社区贡献集中合入 | autoDream 宽容路径三方向闭环：coverage 不足降级 degraded、archive 类型护栏 + `dreamMaxArchivePerRun` 批量上限、失败审计明细贯通（#104/#200/#201）；检索路径三处固定成本：updated_at 索引 + all() 剪列 + 向量解析缓存，all() 231→51ms、searchVector ~140→16ms（#202/#203）；LLM 消息补 source 契约（#189/#190）；首轮注入 BM25 同步兜底（#198/#199）；memory_get schema 同源（#184/#186）；sleep CD 重排（#187/#192）；单 logit 重排器修复（#188/#193）；standalone profile/rules 路由（#180/#185）；1061 测试全绿 |
+| **v0.8.3** | ✅ 完成 | 注入轮换 + 模型下载可靠性 | `injectRotationTurns` 跨轮轮换（默认 0 = 关）——相邻轮次注入去重，窗口只看之前轮次、同查询工具轮不推进不转自己；候选池四处扩容 `poolSize = maxItems × (窗口+1)` 配套，轮换越得出窗口（#205/#206/#208，Philia-FY 报告 + A/B + 池子盲区定位）；`resilientModelDownload` 断点续传与重试（默认开）——Range 续传 / 失配重置 / 单写者锁 + 降级直通 / 空闲看门狗（#194/#207，heptaspirit）；1079 测试全绿 |
 
 > 新能力一律做成**可开关的功能**（配置启用/关闭），默认保守开启、不破坏现有行为。`failure_memories` 表与 autoDream 决策引擎已为后续反思性成长铺好路。
 
@@ -404,6 +406,7 @@ dsh web
 | `autoSummarize` | `true` | 会话结束自动提炼摘要 |
 | `summarizeProvider` / `summarizeModel` | 空 | 摘要的 LLM 路由覆盖（空=使用当前会话模型）；推荐轻量模型节省主模型 token |
 | `maxInjectedItems` | `5` | 最多注入几条记忆 |
+| `injectRotationTurns` | `0` | 注入位跨轮轮换：同一条记忆在最近 N 个查询轮次注入过后本轮不再优先（新鲜优先、不足回填，槽位数不变；会话边界自动重置；`0` = 关闭保持现状） |
 | `importanceThreshold` | `3` | 注入的最低重要性（1-5） |
 | `autoDream` | `true` | 自动记忆整理开关 |
 | `dreamThresholdCount` | `10` | 触发整理的记忆条数阈值 |

package/lib/client.js

@@ -322,6 +322,8 @@ window.__ModuleLoader__.load({
         "memory.features.codingRetrospect.hint": "用完整转录（含工具调用与报错）提炼踩坑、约束与被否决方案",
         "memory.features.rerankEnabled": "结果重排",
         "memory.features.rerankEnabled.hint": "本地重排模型对召回结果精排，更慢更准",
+        "memory.features.resilientModelDownload": "模型下载断点续传",
+        "memory.features.resilientModelDownload.hint": "模型文件下载中断后从已下载部分续传并自动重试，失败会记录中断位置；关闭后回到一次性下载",
         "memory.features.searchSemanticDedup": "语义去重",
         "memory.features.searchSemanticDedup.hint": "搜索结果中意思相近的条目只保留一条",
         "memory.features.autoDream": "记忆巩固",
@@ -671,6 +673,8 @@ window.__ModuleLoader__.load({
         "memory.features.codingRetrospect.hint": "Distill pitfalls, constraints and rejected solutions from full transcripts (tools and errors included)",
         "memory.features.rerankEnabled": "Reranking",
         "memory.features.rerankEnabled.hint": "Rerank recalled results with a local model — slower, more precise",
+        "memory.features.resilientModelDownload": "Resumable model downloads",
+        "memory.features.resilientModelDownload.hint": "Resume model file downloads from received bytes and retry on failure; failures log where they stopped",
         "memory.features.searchSemanticDedup": "Semantic dedup",
         "memory.features.searchSemanticDedup.hint": "Keep one entry when search hits near-duplicates",
         "memory.features.autoDream": "Memory consolidation",
@@ -1747,7 +1751,7 @@ window.__ModuleLoader__.load({
     // 属调优噪音，按对齐结论留在配置文件，不上 UI。
     const FEATURE_GROUPS = [
       { key: "group.core", items: ["autoInject", "autoSummarize", "hotMemoryEnabled", "memoryQualityFilter.enabled", "llmAudit.enabled"] },
-      { key: "group.enhance", items: ["entityExtractionEnabled", "codingRetrospect", "rerankEnabled", "searchSemanticDedup", "bm25SearchEnabled"] },
+      { key: "group.enhance", items: ["entityExtractionEnabled", "codingRetrospect", "rerankEnabled", "resilientModelDownload", "searchSemanticDedup", "bm25SearchEnabled"] },
       { key: "group.dream", items: ["autoDream", "sleepModeEnabled"] },
       // v0.8.0 A4（issue #17）：作用域隔离组——标注总开关 + 严格硬过滤。
       { key: "group.scope", items: ["scopeEnabled", "strictScope"] }

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