@modusensus/dsh-mneme 0.8.4 → 0.8.6

package/src/inject.js

@@ -1,6 +1,19 @@
 import { createScopeResolver } from "./scope.js";
 import { createHotMemory } from "./hot-memory.js";
 import { STR, langOf } from "./lang.js";
+import { MEMORY_GUIDE_SECTION } from "./guide.js";
+import { adaptiveInjectBudget } from "./search/adaptive.js";
+
+// Issue #179：注入预览的数据底座。systemPrompt 渲染是同步回调，面板只能事后
+// 拉取，所以在这里旁路缓存「最近一帧组装」——快照就是本次渲染用过的同一份
+// candidates/hotText/body，不重新检索、不二次组装，零额外开销。模块级单例：
+// 注入器全局唯一（index.js 仅在 autoInject 开启时注册一个），面板经 api.js 的
+// 只读 getter 读取；autoInject 关闭时注入器不存在，快照保持 null——「预览
+// 不可用」本身就是「注入关闭」的诚实呈现。
+let injectionSnapshot = null;
+export function getInjectionSnapshot() {
+  return injectionSnapshot;
+}
 
 // Best-effort extraction of the current user's latest message text from the
 // live session, for semantic-first injection (Bug4). The system-prompt
@@ -92,7 +105,7 @@ function extractRounds(ctx, maxRounds) {
 
 export function createInjector(ctx, service, settings, config) {
   const language = langOf(config);
-  const maxItems = config.maxInjectedItems ?? 5;
+  const baseMaxItems = config.maxInjectedItems ?? 5;
   const threshold = config.importanceThreshold ?? 3;
   // Issue #205：注入位跨轮轮换。rotationTurns = 最近 N 个「不同用户查询」轮次
   // 注入过的记忆本轮不再优先（0 = 关闭，保持既有行为）。历史按会话维护——
@@ -143,13 +156,18 @@ export function createInjector(ctx, service, settings, config) {
   // stale 1500) and an entry that would exceed it collapses to its title only.
   const maxContent = config.injectContentMaxChars ?? 300;
   const MAX_BLOCK = Math.max(1500, maxContent + 600);
+  // #249 第一批：pin 条目的正文硬顶。逐字保真不等于无界——单条上限取
+  // injectContentMaxChars 与 2000 的较大者，默认档下约束/偏好不会因常规截断
+  // 失真，同时给「一条超长约束每轮吃满常驻段」留一道闸（超顶仍带截断提示）。
+  const PINNED_CONTENT_MAX = Math.max(maxContent, 2000);
 
-  // Compressed injection (v0.5.0 2.1): a sleep-demoted row already carries its
-  // summary in `content` with the original parked in `_full_content` — inject
-  // the summary verbatim instead of re-truncating the (already short) text.
-  // Regular long rows keep the hard truncate.
+  // Compressed injection (v0.5.0 2.1): a sleep-demoted row carries its summary in
+  // `content` with the original parked in `_full_content` — inject the summary
+  // verbatim instead of re-truncating the (already short) text. 但「降级过」不等于
+  // 「天然够短」：原先那条 `_full_content` 早返回的唯一效果就是**跳过 maxLength**
+  // （两条分支取的都是 m.content），于是 pin 的硬顶在这一路上形同不存在（#266 评审）。
+  // 现在只有一条截断路径：超限照旧带提示，原文永远可通过 memory_get 取回。
   function injectMemory(m, maxLength = maxContent) {
-    if (m?._full_content) return String(m.content ?? "");
     const text = String(m?.content ?? "");
     if (text.length <= maxLength) return text;
     return `${text.slice(0, maxLength)}…${STR.truncatedHint[language](maxLength, text.length, m.id)}`;
@@ -192,26 +210,41 @@ export function createInjector(ctx, service, settings, config) {
     return escapePromptVars(STR.hotHeader[language](rounds.length, body));
   }
 
-  function render(candidates) {
+  function render(candidates, pinnedStats = null) {
     if (!candidates.length) return "";
     const header = STR.memoryHeader[language];
     const lines = [header];
     let budget = MAX_BLOCK - header.length;
-    for (const m of candidates) {
+    // #249 第一批：pin 池（约束/偏好）排在块头且不参与块的塌缩预算——「与情景
+    // 日志抢同一份预算后被降级」正是本议题要修的结构缺陷。单条仍有硬顶
+    // （PINNED_CONTENT_MAX），超出照旧带截断提示，不静默。
+    const pinnedCount = Math.max(0, Math.min(candidates.length, pinnedStats?.shown ?? 0));
+    for (let i = 0; i < candidates.length; i++) {
+      const m = candidates[i];
+      const pinned = i < pinnedCount;
       // Epistemic trust (v0.4.5): when enabled, measured observations are
       // flagged so the agent can weigh them above guesses/opinions.
       const verified = config.trustEpistemicWeighting === true && m.epistemic_status === "observation"
         ? STR.verified[language]
         : "";
       const title = STR.entryTitle[language](m.title, m.importance);
-      const content = injectMemory(m);
+      const content = injectMemory(m, pinned ? PINNED_CONTENT_MAX : maxContent);
       const full = STR.entryLine[language](m.type, verified, title, content);
-      if (budget - full.length >= 0) {
+      if (pinned) {
+        // pin 不扣块预算（上面那条设计注释的落地）：pin 一条就够击穿 MAX_BLOCK
+        // （PINNED_CONTENT_MAX 2000 > MAX_BLOCK 1500），照扣会把 budget 压成负数，
+        // 同一轮随后的普通候选全部退化成标题行——正是本议题要修的结构缺陷。
+        lines.push(full);
+      } else if (budget - full.length >= 0) {
         lines.push(full);
         budget -= full.length;
       } else {
         lines.push(`- [${m.type}] ${verified}${title}`);
       }
+      if (pinned && i === pinnedCount - 1) {
+        const hidden = Math.max(0, pinnedStats?.suppressed ?? 0);
+        if (hidden > 0) lines.push(STR.pinnedOverflow[language](hidden));
+      }
     }
     return escapePromptVars(lines.join("\n"));
   }
@@ -250,7 +283,17 @@ export function createInjector(ctx, service, settings, config) {
     return escapePromptVars(lines.join("\n"));
   }
 
+  // #249 第一批：能力说明的系统提示段。order 150 = 插件指引段的既有惯例
+  // （ACP 的 ACP_SYSTEM_PROMPT 与 mnemon 的 routing 段都在 150）。文本是常量、
+  // 同会话内不随轮次变化，故不影响其后的前缀缓存，也不逐轮复读。宿主若不提供
+  // section seam 就静默跳过——#249 §3 的口径是「只用现成 seam，拿不到位的语义
+  // 降级处理」：能力说明仍落在工具描述上，不算失败。
+  const guideSection = config.injectGuidanceEnabled === true && typeof ctx.systemPrompt?.section === "function"
+    ? ctx.systemPrompt.section({ name: "memory-guide", order: 150, text: MEMORY_GUIDE_SECTION })
+    : null;
+
   const disposers = [
+    ...(guideSection ? [guideSection] : []),
     ctx.systemPrompt.context({
       name: "memory",
       order: 90,
@@ -270,16 +313,48 @@ export function createInjector(ctx, service, settings, config) {
         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);
+        // Issue #239（第 5 项）：注入条数的查询自适应（默认关）。确定性强的话题收缩
+        // 条数、模糊话题维持上限——单向收缩，绝不越过 maxInjectedItems；判据只看查询
+        // 本身，不做额外检索（先探针检索等于白付一次 fuseRecall）。
+        const maxItems = config.injectUncertaintyAdaptive === true
+          ? adaptiveInjectBudget(query, baseMaxItems)
+          : baseMaxItems;
+        // #249 第一批：pin 池统计走可选出参，不动 injectCandidates 的数组契约。
+        const pinnedStats = {};
+        const candidates = service.injectCandidates({ query, queryVector, maxItems, threshold, scope, rotate, rotateWindow: rotationTurns, pinnedStats });
+        // #249：pin 条目不进轮换历史——它们每轮固定前置，记进去只会占满轮换
+        // 窗口、挤掉情景候选的新鲜度（验收：pin 不参与跨轮轮换）。
+        recordInjection(sessionId, query, pinnedStats.shown > 0 ? candidates.slice(pinnedStats.shown) : 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
         // separate context) keeps the prompt assembly stable at two blocks.
         const hotText = renderHotContext(ctx);
-        const body = render(candidates);
-        if (!hotText) return body;
-        return body ? `${hotText}\n\n${body}` : hotText;
+        const body = render(candidates, pinnedStats);
+        const finalBody = !hotText ? body : body ? `${hotText}\n\n${body}` : hotText;
+        // Issue #179：旁路缓存一帧——面板「注入预览」卡据此展示构成与体积。
+        // chars 为条目内容的截断后近似值（与 render 同一函数计长），totalChars
+        // 是本次实际返回块的精确长度。maxItems 反映自适应收缩后的生效值。
+        injectionSnapshot = {
+          at: Date.now(),
+          sessionId,
+          query: query || "",
+          maxItems,
+          threshold,
+          adaptive: config.injectUncertaintyAdaptive === true,
+          scoped: scope && (scope.agent_scope || scope.workspace_scope) ? scope : null,
+          rotated: rotate ? rotate.size : 0,
+          hotChars: hotText.length,
+          entries: candidates.map((m) => ({
+            id: m.id,
+            type: m.type,
+            title: m.title,
+            importance: m.importance,
+            chars: injectMemory(m).length
+          })),
+          totalChars: finalBody.length
+        };
+        return finalBody;
       }
     }),
     ctx.systemPrompt.context({
@@ -292,6 +367,7 @@ export function createInjector(ctx, service, settings, config) {
   return () => {
     queryVectorCache.clear();
     rotationHistory.clear();
+    injectionSnapshot = null; // 注入器卸载即失效：快照不得跨生命周期存留
     for (const dispose of disposers) {
       if (typeof dispose === "function") dispose();
     }

package/src/lang.js

@@ -75,6 +75,12 @@ export const STR = {
     zh: (max, len, id) => `〔已截断：上限 ${max}，原 ${len} 字符；全文用 memory_get "${id}" 查看〕`,
     en: (max, len, id) => `[truncated: limit ${max}, original ${len} chars; memory_get "${id}" for full text]`
   },
+  // Issue #249（第一批）：pin 池超预算时的如实标注——分层不等于丢弃，也不允许
+  // 静默省略未展示条数（agent 才知道库里的约束不止这几条，需按需 memory_search）。
+  pinnedOverflow: {
+    zh: (n) => `〔约束/偏好类另有 ${n} 条未展示〕`,
+    en: (n) => `[${n} more constraint/preference entries not shown]`
+  },
   userSettingsHeader: {
     zh: "[用户设置] 来自 dsh-mneme 的用户画像与规则：",
     en: "[User settings] Profile and rules from dsh-mneme:"

package/src/local-embedder.js

@@ -21,6 +21,32 @@ function modelHash(model) {
   return `${model}#${hashString(model)}`;
 }
 
+/**
+ * Model families whose embedding is the CLS token rather than a mean over tokens.
+ *
+ * BGE (BAAI/bge-*) is trained that way: the model's own `1_Pooling/config.json`
+ * declares `pooling_mode_cls_token: true` / `pooling_mode_mean_tokens: false`, and
+ * the official README says "select the last hidden state of the first token" plus
+ * L2 normalization. transformers.js's `feature-extraction` defaults to `mean`, so
+ * feeding it a BGE model silently produces slightly-off vectors — no error, just a
+ * worse ranking. This table is the extension point: a family goes in only once its
+ * pooling is confirmed against the model's own `1_Pooling` (or equivalent) config.
+ */
+const CLS_POOLED_MODEL_PATTERNS = [/bge/i];
+
+/**
+ * Resolve the pooling to embed with.
+ *
+ * `auto` (default) picks by model family — BGE → `cls`, everything else → `mean`,
+ * so models that were never affected keep their exact previous behavior. An
+ * explicit `cls` / `mean` wins over the family table.
+ */
+export function resolvePooling(pooling, model) {
+  const mode = String(pooling ?? "auto").trim().toLowerCase();
+  if (mode === "cls" || mode === "mean") return mode;
+  return CLS_POOLED_MODEL_PATTERNS.some((re) => re.test(String(model ?? ""))) ? "cls" : "mean";
+}
+
 /**
  * Lazy default loader: dynamic import keeps module load cheap.
  *
@@ -71,8 +97,9 @@ function tensorToRows(tensor) {
 
 /**
  * ONNX text embedder backed by transformers.js (onnxruntime-node underneath).
- * Runs fully offline with mean pooling + L2 normalization for BERT-style
- * models like bge-small-zh. `engineFactory` is injectable for tests.
+ * Runs fully offline; pooling is resolved per model family (BGE → CLS, else mean —
+ * see resolvePooling) and vectors are L2-normalized. `engineFactory` is injectable
+ * for tests.
  */
 export class LocalEmbedder {
   constructor(opts = {}) {
@@ -87,6 +114,10 @@ export class LocalEmbedder {
     // （含测试）保持裸 fetch 的现状，配置默认值由 index.js 传进来。
     this.resilientModelDownload = opts.resilientModelDownload === true;
     this.useDtype = opts.useDtype || "q8";
+    // 池化：配置值（auto/cls/mean）→ 生效值（cls/mean）。解析结果既进 embed()，
+    // 也进 modelHash —— 换池化就是换向量空间，旧索引必须被判失配后重建。
+    this.poolingMode = String(opts.pooling ?? "auto").trim().toLowerCase();
+    this.pooling = resolvePooling(this.poolingMode, this.model);
     // 模型镜像下载源（embedModelMirror，#188 补充）：空 = transformers 默认。
     this.remoteHost = String(opts.remoteHost ?? "").trim();
     this.logger = opts.logger ?? null;
@@ -114,19 +145,19 @@ export class LocalEmbedder {
     this.extractor = await this.engineFactory("feature-extraction", this.model, options);
     this.ready = true; // service reads this to flush queued re-embeds
     this.logger?.info?.(
-      `[dsh-mneme] local embedder ready: ${this.model} (dim=${this._dimension}, device=${this.device})`
+      `[dsh-mneme] local embedder ready: ${this.model} (dim=${this._dimension}, device=${this.device}, pooling=${this.pooling})`
     );
     return this;
   }
 
-  /** Embed many texts with mean pooling; chunks at batchSize. */
+  /** Embed many texts with the model's pooling; chunks at batchSize. */
   async embed(texts) {
     if (!Array.isArray(texts)) throw new TypeError("embed expects an array of strings");
     if (!this.extractor) throw new Error("LocalEmbedder not initialized");
     const out = [];
     for (let i = 0; i < texts.length; i += this.batchSize) {
       const chunk = texts.slice(i, i + this.batchSize);
-      const tensor = await this.extractor(chunk, { pooling: "mean", normalize: true });
+      const tensor = await this.extractor(chunk, { pooling: this.pooling, normalize: true });
       out.push(...tensorToRows(tensor));
     }
     return out;
@@ -142,7 +173,14 @@ export class LocalEmbedder {
   }
 
   get modelHash() {
-    return modelHash(this.model);
+    // Pooling is part of the vector space: a CLS index cannot be queried with mean
+    // vectors (or vice versa). Keep the historical `model#hash` shape for `mean` so
+    // indexes that were never affected are not invalidated needlessly; every other
+    // pooling gets a fingerprint of its own, which makes the index-consistency gate
+    // flag the stale mean-space index and rebuild it.
+    return this.pooling === "mean"
+      ? modelHash(this.model)
+      : modelHash(`${this.model}@${this.pooling}`);
   }
 
   dispose() {