@modusensus/dsh-mneme 0.8.1 → 0.8.3

package/src/dream.js

@@ -910,8 +910,8 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       maxTokens: config.dreamMaxTokens ?? 4096,
       ...(withEffort && effort ? { reasoningEffort: effort } : {}),
       messages: [
-        { role: "system", content: [{ type: "text", text: consolidationPrompt }] },
-        { role: "user", content: [{ type: "text", text: listText }] }
+        { role: "system", content: [{ type: "text", text: consolidationPrompt }], source: { kind: "plugin", plugin: "dsh-mneme" } },
+        { role: "user", content: [{ type: "text", text: listText }], source: { kind: "plugin", plugin: "dsh-mneme" } }
       ]
     }, reportUsage, (reason) => { streamFailure = describeStreamFailure(reason); }));
     };
@@ -933,8 +933,10 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       logger?.warn?.(`dsh-mneme dream: no json array in llm output (raw length ${decisionText?.length ?? 0}; head: ${head})`);
       return finish({ ok: false, error: "no json array in llm output", summary: false });
     }
-    const { ok, errors, skipped, resolvedShortIds } = validateDecisions(decisions, snapshot, {
+    const { ok, errors, skipped, resolvedShortIds, coverageShortfall } = validateDecisions(decisions, snapshot, {
       maxUpdatePerRun: config.reflectionUpdateMaxPerRun,
+      // Issue #104 方向 2：archive 批量上限（全局闸门，超限整单拒绝）。
+      maxArchivePerRun: config.dreamMaxArchivePerRun,
       minAgeHours: config.reflectionUpdateMinAgeHours,
       // v0.4.4 fix：显式透传，用户配 dreamImplicitKeep:false 时严格模式必须
       // 真正生效，dreamMinExplicitCoverage 决定隐式 keep 下的覆盖率下限。
@@ -972,6 +974,12 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     if (skippedInvalid) {
       logger?.warn?.(`dsh-mneme dream: ${skipped.length} invalid decision(s) skipped (run degrades): ${skipped.map((s) => s.error).join("; ")}`);
     }
+    // Issue #104 方向 1：覆盖率不足降级为 degraded（不再整单拒绝）——合法子集
+    // 照常应用、未提及条目隐式 keep，理由随 outcome.degradations 落库供离线定位。
+    const coverageDegraded = typeof coverageShortfall === "string" && coverageShortfall.length > 0;
+    if (coverageDegraded) {
+      logger?.warn?.(`dsh-mneme dream: ${coverageShortfall} (run degrades: valid subset applied, unclaimed ids kept implicitly)`);
+    }
 
     // Capture pre-update snapshots so the audit records what each update changed.
     const updateSnapshots = {};
@@ -1087,6 +1095,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // claim "merge-archived" (item ②). Conflicts/failures ride along so the
     // audit row records why the run diverged.
     const outcome = { ...buildOutcome(committed), conflicts, failures };
+    if (coverageDegraded) outcome.degradations = [coverageShortfall];
     // Frozen conflicts were not adjudicated: mark both sides pending in the
     // per-id outcome so the audit row shows they were parked, not skipped.
     if (frozenIds.length) {
@@ -1130,8 +1139,8 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       maxTokens: config.dreamMaxTokens ?? 2048,
       ...(withEffort && effort ? { reasoningEffort: effort } : {}),
       messages: [
-        { role: "system", content: [{ type: "text", text: STR.prompts.dreamSummary[language] }] },
-        { role: "user", content: [{ type: "text", text: service.all().filter((m) => !m.archived && m.type !== "summary").map((m) => `- ${m.title}: ${m.content}`).join("\n") }] }
+        { role: "system", content: [{ type: "text", text: STR.prompts.dreamSummary[language] }], source: { kind: "plugin", plugin: "dsh-mneme" } },
+        { role: "user", content: [{ type: "text", text: service.all().filter((m) => !m.archived && m.type !== "summary").map((m) => `- ${m.title}: ${m.content}`).join("\n") }], source: { kind: "plugin", plugin: "dsh-mneme" } }
       ]
     }, reportUsage, (reason) => { summaryStreamFailure = describeStreamFailure(reason); }));
     };
@@ -1171,7 +1180,9 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     //   degraded  — real consolidation landed but the run did not produce its
     //               full output: the summary came back empty/missing, or
     //               skipInvalid dropped individually-invalid decisions
-    //               (Issue #89 — marked, not faked). The valid subset was
+    //               (Issue #89 — marked, not faked), or the explicit-decision
+    //               coverage fell below dreamMinExplicitCoverage (Issue #104
+    //               方向 1 — degrade, don't reject). The valid subset was
     //               absorbed (ok for the baseline).
     let status;
     let okResult;
@@ -1182,7 +1193,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       status = summaryStored ? "ok" : "noop";
       okResult = summaryStored;
     } else {
-      status = summaryStored && !skippedInvalid ? "ok" : "degraded";
+      status = summaryStored && !skippedInvalid && !coverageDegraded ? "ok" : "degraded";
       okResult = true;
     }
     return finish({

package/src/entities/extractor.js

@@ -150,8 +150,8 @@ export async function extractEntities(memory, { store, config, callLLM, logger }
     const userText = buildUserMessage(memory.content);
 
     const messages = [
-      { role: "system", content: [{ type: "text", text: systemPrompt }] },
-      { role: "user", content: [{ type: "text", text: userText }] }
+      { role: "system", content: [{ type: "text", text: systemPrompt }], source: { kind: "plugin", plugin: "dsh-mneme" } },
+      { role: "user", content: [{ type: "text", text: userText }], source: { kind: "plugin", plugin: "dsh-mneme" } }
     ];
 
     // Issue #109: optional provider/model override + reasoning effort are

package/src/index.js

@@ -275,6 +275,9 @@ export const apply = (ctx, config) => {
         batchSize: cfg.localEmbedBatchSize,
         cacheDir: cfg.embedModelCacheDir,
         runtimeDir: cfg.runtimeDir,
+        // #188：embedModelMirror 接成 transformers 的下载镜像（此前死配置）。
+        remoteHost: cfg.embedModelMirror,
+        resilientModelDownload: cfg.resilientModelDownload,
         baseUrl: cfg.ollamaBaseUrl,
         logger: ctx.logger
       });
@@ -327,6 +330,11 @@ export const apply = (ctx, config) => {
         device: cfg.localEmbedDevice,
         cacheDir: cfg.embedModelCacheDir,
         runtimeDir: cfg.runtimeDir,
+        // #188：量化档默认 q8（此前不传 dtype 会去要 1GB 级 fp32 模型）；
+        // 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/lang.js

@@ -23,8 +23,8 @@ const PROMPTS = {
     "en": "You are the memory overview assistant. From the consolidated memories below, produce a 150-200 word memory-library overview covering: user preferences, active projects, key decisions. This will be injected as conversation context. Output only the summary text, nothing else."
   },
   "consolidation": {
-    "zh": "你是记忆库整理助手。下面是全部记忆条目（id、类型、标题、内容、重要性、更新时间）。\n请执行记忆巩固（consolidation），输出一个决策 JSON 数组。\n\n【决策格式（必须严格遵守）】\n每个决策必须是对象，字段固定：\n- \"action\"：必填。取值只能是 \"keep\" / \"merge\" / \"archive\" / \"update\" / \"conflict\" 之一（字段名必须是 action，严禁写成 type）\n- \"ids\"：必填，数组，本决策涉及的记忆 id 列表\n- \"reason\"：可选，字符串，决策理由\n- \"importance\"：可选，整数 1-5\n- merge 额外字段：\"keepSource\"（单个 id 字符串，必须是 ids 之一）+ 合并后的 \"title\"、\"content\"\n- conflict 额外字段：\"winner\" 与 \"loser\"，都是【单个 id 字符串，不是数组】\n- update 额外字段：修正后的 \"title\" 和/或 \"content\"；\"ids\" 只能包含一个 id\n\n【决策 JSON 示例】\n[\n  { \"action\": \"merge\", \"ids\": [\"m1\", \"m2\"], \"keepSource\": \"m1\", \"title\": \"合并标题\", \"content\": \"合并后的摘要内容\", \"importance\": 4, \"reason\": \"主题相近\" },\n  { \"action\": \"conflict\", \"winner\": \"m3\", \"loser\": \"m4\", \"reason\": \"内容矛盾，保留更新的信息\" },\n  { \"action\": \"update\", \"ids\": [\"m5\"], \"content\": \"修正后的内容\", \"reason\": \"信息过时\" },\n  { \"action\": \"archive\", \"ids\": [\"m6\"], \"reason\": \"重复或过时\" }\n]\n\n【任务】\n1. 识别主题相近的条目 → merge（合并为更精炼的摘要，保留信息最完整的 id 作为 keepSource）\n2. 识别重复/过时信息 → archive\n3. 识别内容矛盾的条目 → conflict（按时间新旧、来源完整性、信息具体程度判断 winner/loser）\n4. 发现单条记忆中的信息过时、错误或遗漏 → update（直接修正内容）\n   - update 的 ids 只能包含一个 id\n   - 必须提供修正后的 title 和/或 content\n   - 仅当内容确实需要修正时才使用，不要滥用\n   - 每次整理最多输出 2 个 update\n   - 24 小时内新建的记忆不可 update\n5. 无问题的条目无需输出（未提及的条目将自动保留 keep）\n\n【硬性规则】\n- 字段名必须精确为 \"action\"，严禁写成 \"type\"；字段名统一用双引号\n- conflict 的 winner/loser、merge 的 keepSource 都是【单个 id 字符串，绝不是数组】\n- 每条记忆最多被 claim 一次：同一个 id 不能出现在多个决策中（同一 id 不能被 merge 和 conflict/archive 等重复占用）\n- 未在决策中提及的记忆将自动保留（keep），无需为每条记忆输出 keep\n- merge 的 keepSource 必须是 ids 之一\n- 仅合并同类型条目（type 相同）\n- 不要编造 ids；只使用提供的 id\n- 重要性 1-5，合并后取最高\n- 只输出 JSON 数组，不要其他文字",
-    "en": "You are the memory consolidation assistant. Below are all memory entries (id, type, title, content, importance, updated time).\nPerform memory consolidation and output a JSON array of decisions.\n\n[Decision format (must be followed strictly)]\nEach decision must be an object with fixed fields:\n- \"action\": required. Value must be one of \"keep\" / \"merge\" / \"archive\" / \"update\" / \"conflict\" (the field name must be action, never type)\n- \"ids\": required, array, the list of memory ids involved in this decision\n- \"reason\": optional, string, rationale for the decision\n- \"importance\": optional, integer 1-5\n- merge extra fields: \"keepSource\" (a single id string, must be one of ids) plus the merged \"title\" and \"content\"\n- conflict extra fields: \"winner\" and \"loser\", each a [single id string, never an array]\n- update extra fields: the corrected \"title\" and/or \"content\"; \"ids\" may contain only one id\n\n[Decision JSON examples]\n[\n  { \"action\": \"merge\", \"ids\": [\"m1\", \"m2\"], \"keepSource\": \"m1\", \"title\": \"Merged title\", \"content\": \"Merged summary content\", \"importance\": 4, \"reason\": \"similar topics\" },\n  { \"action\": \"conflict\", \"winner\": \"m3\", \"loser\": \"m4\", \"reason\": \"content contradicts; keep the newer information\" },\n  { \"action\": \"update\", \"ids\": [\"m5\"], \"content\": \"corrected content\", \"reason\": \"information outdated\" },\n  { \"action\": \"archive\", \"ids\": [\"m6\"], \"reason\": \"duplicate or outdated\" }\n]\n\n[Task]\n1. Identify entries with similar topics -> merge (merge into a more refined summary; keep the id with the most complete information as keepSource)\n2. Identify duplicate/outdated information -> archive\n3. Identify entries with contradictory content -> conflict (judge winner/loser by recency, source completeness, and information specificity)\n4. Find outdated, wrong, or missing information in a single memory -> update (correct the content directly)\n   - update's ids may contain only one id\n   - must provide the corrected title and/or content\n   - use only when the content truly needs correction; do not abuse\n   - output at most 2 updates per consolidation run\n   - memories created within the last 24 hours must not be updated\n5. Entries without issues need no output (unmentioned entries are automatically kept)\n\n[Hard rules]\n- Field names must be exactly \"action\", never \"type\"; use double quotes for all field names\n- conflict winner/loser and merge keepSource are [single id strings, never arrays]\n- Each memory may be claimed at most once: the same id must not appear in multiple decisions (an id must not be claimed by both merge and conflict/archive, etc.)\n- Memories not mentioned in any decision are automatically kept (keep); no need to output keep for every memory\n- merge keepSource must be one of ids\n- Only merge entries of the same type (identical type)\n- Never invent ids; use only the provided ids\n- Importance is 1-5; after a merge take the highest\n- Write every title, content, and reason in English\n- Output only the JSON array, nothing else"
+    "zh": "你是记忆库整理助手。下面是全部记忆条目（id、类型、标题、内容、重要性、更新时间）。\n请执行记忆巩固（consolidation），输出一个决策 JSON 数组。\n\n【决策格式（必须严格遵守）】\n每个决策必须是对象，字段固定：\n- \"action\"：必填。取值只能是 \"keep\" / \"merge\" / \"archive\" / \"update\" / \"conflict\" 之一（字段名必须是 action，严禁写成 type）\n- \"ids\"：必填，数组，本决策涉及的记忆 id 列表\n- \"reason\"：可选，字符串，决策理由\n- \"importance\"：可选，整数 1-5\n- merge 额外字段：\"keepSource\"（单个 id 字符串，必须是 ids 之一）+ 合并后的 \"title\"、\"content\"\n- conflict 额外字段：\"winner\" 与 \"loser\"，都是【单个 id 字符串，不是数组】\n- update 额外字段：修正后的 \"title\" 和/或 \"content\"；\"ids\" 只能包含一个 id\n\n【决策 JSON 示例】\n[\n  { \"action\": \"merge\", \"ids\": [\"m1\", \"m2\"], \"keepSource\": \"m1\", \"title\": \"合并标题\", \"content\": \"合并后的摘要内容\", \"importance\": 4, \"reason\": \"主题相近\" },\n  { \"action\": \"conflict\", \"winner\": \"m3\", \"loser\": \"m4\", \"reason\": \"内容矛盾，保留更新的信息\" },\n  { \"action\": \"update\", \"ids\": [\"m5\"], \"content\": \"修正后的内容\", \"reason\": \"信息过时\" },\n  { \"action\": \"archive\", \"ids\": [\"m6\"], \"reason\": \"重复或过时\" }\n]\n\n【任务】\n1. 识别主题相近的条目 → merge（合并为更精炼的摘要，保留信息最完整的 id 作为 keepSource）\n2. 识别重复/过时信息 → archive\n3. 识别内容矛盾的条目 → conflict（按时间新旧、来源完整性、信息具体程度判断 winner/loser）\n4. 发现单条记忆中的信息过时、错误或遗漏 → update（直接修正内容）\n   - update 的 ids 只能包含一个 id\n   - 必须提供修正后的 title 和/或 content\n   - 仅当内容确实需要修正时才使用，不要滥用\n   - 每次整理最多输出 2 个 update\n   - 24 小时内新建的记忆不可 update\n5. 无问题的条目无需输出（未提及的条目将自动保留 keep）\n\n【硬性规则】\n- 字段名必须精确为 \"action\"，严禁写成 \"type\"；字段名统一用双引号\n- conflict 的 winner/loser、merge 的 keepSource 都是【单个 id 字符串，绝不是数组】\n- 每条记忆最多被 claim 一次：同一个 id 不能出现在多个决策中（同一 id 不能被 merge 和 conflict/archive 等重复占用）\n- 未在决策中提及的记忆将自动保留（keep），无需为每条记忆输出 keep\n- merge 的 keepSource 必须是 ids 之一\n- 仅合并同类型条目（type 相同）\n- 不要编造 ids；只使用提供的 id\n- 重要性 1-5，合并后取最高\n- archive 仅用于确属「重复或已过时」的条目；rejected_solution / constraint / pitfall / preference / pattern 属长保留类型，除非确属重复或过时，否则不要归档\n- 每次整理最多输出 8 个 archive\n- 只输出 JSON 数组，不要其他文字",
+    "en": "You are the memory consolidation assistant. Below are all memory entries (id, type, title, content, importance, updated time).\nPerform memory consolidation and output a JSON array of decisions.\n\n[Decision format (must be followed strictly)]\nEach decision must be an object with fixed fields:\n- \"action\": required. Value must be one of \"keep\" / \"merge\" / \"archive\" / \"update\" / \"conflict\" (the field name must be action, never type)\n- \"ids\": required, array, the list of memory ids involved in this decision\n- \"reason\": optional, string, rationale for the decision\n- \"importance\": optional, integer 1-5\n- merge extra fields: \"keepSource\" (a single id string, must be one of ids) plus the merged \"title\" and \"content\"\n- conflict extra fields: \"winner\" and \"loser\", each a [single id string, never an array]\n- update extra fields: the corrected \"title\" and/or \"content\"; \"ids\" may contain only one id\n\n[Decision JSON examples]\n[\n  { \"action\": \"merge\", \"ids\": [\"m1\", \"m2\"], \"keepSource\": \"m1\", \"title\": \"Merged title\", \"content\": \"Merged summary content\", \"importance\": 4, \"reason\": \"similar topics\" },\n  { \"action\": \"conflict\", \"winner\": \"m3\", \"loser\": \"m4\", \"reason\": \"content contradicts; keep the newer information\" },\n  { \"action\": \"update\", \"ids\": [\"m5\"], \"content\": \"corrected content\", \"reason\": \"information outdated\" },\n  { \"action\": \"archive\", \"ids\": [\"m6\"], \"reason\": \"duplicate or outdated\" }\n]\n\n[Task]\n1. Identify entries with similar topics -> merge (merge into a more refined summary; keep the id with the most complete information as keepSource)\n2. Identify duplicate/outdated information -> archive\n3. Identify entries with contradictory content -> conflict (judge winner/loser by recency, source completeness, and information specificity)\n4. Find outdated, wrong, or missing information in a single memory -> update (correct the content directly)\n   - update's ids may contain only one id\n   - must provide the corrected title and/or content\n   - use only when the content truly needs correction; do not abuse\n   - output at most 2 updates per consolidation run\n   - memories created within the last 24 hours must not be updated\n5. Entries without issues need no output (unmentioned entries are automatically kept)\n\n[Hard rules]\n- Field names must be exactly \"action\", never \"type\"; use double quotes for all field names\n- conflict winner/loser and merge keepSource are [single id strings, never arrays]\n- Each memory may be claimed at most once: the same id must not appear in multiple decisions (an id must not be claimed by both merge and conflict/archive, etc.)\n- Memories not mentioned in any decision are automatically kept (keep); no need to output keep for every memory\n- merge keepSource must be one of ids\n- Only merge entries of the same type (identical type)\n- Never invent ids; use only the provided ids\n- Importance is 1-5; after a merge take the highest\n- Write every title, content, and reason in English\n- archive is only for entries that are genuinely \"duplicate or outdated\"; rejected_solution / constraint / pitfall / preference / pattern are long-retention types — do not archive them unless they are truly duplicate or outdated\n- output at most 8 archives per consolidation run\n- Output only the JSON array, nothing else"
   },
   "conflict": {
     "zh": "你是记忆库冲突仲裁助手。下面是检测到的高相似度记忆对，可能内容矛盾或重复。\n对每一对输出一个 decision 对象：\n- 两条确实矛盾/重复 → { \"action\": \"conflict\", \"winner\": <保留的id>, \"loser\": <归档的id>, \"reason\": \"理由\" }\n- 两条只是主题相近、并无矛盾 → { \"action\": \"keep\", \"ids\": [<两个id>] }\n规则：\n- winner 应为信息更完整、更新或更可信的一条\n- 只使用提供的 id，不要编造\n- 每对必须输出一个 decision\n- 只输出 JSON 数组，不要其他文字",

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, ...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/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, ...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);