@modusensus/dsh-mneme 0.13.0 → 0.14.0-beta.2

package/src/heat.js

@@ -1,144 +1,144 @@
-// dsh-mneme/src/heat.js
-// 热度（heat）纯函数模块：基于广义指数遗忘曲线计算 memory 的当前热度。
-// 零数据库依赖，不引入任何外部依赖。
-//
-// 曲线选型（issue #218，2026-09-18 与维护者对齐）：H = exp(-λ·Δt^β)。
-// FadeMem v2 Eq4 的广义指数族——λ 管速率（per-type 差异），β 管形状
-// （β=1 退化为纯指数，β<1 呈亚线性长尾）；λ=0 免疫位在指数式下同样恒 1。
-// v0.7.0–0.8.3 存量为幂律 H=(1+λΔt)^-α；幂律在 #164 已收集论文集外，
-// 真实负载回放（#218 验收 4）时对两个曲线族做拟合 A/B，幂律更贴合再议。
-
-/**
- * 默认的 per-type 衰减因子 λ。
- * λ = 0 表示该类型免疫热度衰减，热度恒为 1.0。
- */
-export const TYPE_DECAY_DEFAULTS = Object.freeze({
-  preference: 0,    // 免疫：用户画像需长期保持
-  pattern: 0,       // 免疫：发现型稳定规律
-  summary: 0,       // 免疫：已是压缩产物
-  document: 0,      // 免疫：指针行（#230）——全文在文件系统，行失效靠 supersede
-                    // 记账而非遗忘；遗忘曲线灭掉指针 = 按需读全文的入口消失
-  project: 0.0008,  // 慢衰减
-  decision: 0.002,  // 中速衰减
-  history: 0.006,   // 较快（会话摘要不断被合并）
-});
-
-const HOUR_MS = 3600000;
-const DEFAULT_BETA = 1.0;
-const DEFAULT_LAMBDA = 0.002;
-
-/**
- * 将可能的日期值统一转成毫秒时间戳。
- * 支持 Date、number、ISO 字符串；无法解析时返回 NaN。
- */
-function toTimestamp(value) {
-  if (value === null || value === undefined) return NaN;
-
-  if (value instanceof Date) {
-    return Number.isFinite(value.getTime()) ? value.getTime() : NaN;
-  }
-
-  if (typeof value === 'number') {
-    return Number.isFinite(value) ? value : NaN;
-  }
-
-  if (typeof value === 'string') {
-    const parsed = Date.parse(value);
-    return Number.isFinite(parsed) ? parsed : NaN;
-  }
-
-  return NaN;
-}
-
-/**
- * 获取用于计算热度的参考时间点 ref。
- * 优先取 last_accessed_at；缺失时退到 created_at。
- * 绝不 fallback 到 updated_at。
- */
-function getRef(memory) {
-  if (!memory || typeof memory !== 'object') return NaN;
-  return toTimestamp(memory.last_accessed_at ?? memory.created_at);
-}
-
-/**
- * 解析并校验配置，提供安全的 β 与衰减表。
- */
-function resolveConfig(config) {
-  const safe = config && typeof config === 'object' ? config : {};
-
-  let beta = safe.heatGlobalBeta ?? DEFAULT_BETA;
-  if (!Number.isFinite(beta) || beta <= 0) {
-    beta = DEFAULT_BETA;
-  }
-
-  const decayMap = safe.heatTypeDecay ?? TYPE_DECAY_DEFAULTS;
-
-  return { beta, decayMap };
-}
-
-/**
- * 构建热度信号对象，便于调试与后续扩展。
- *
- * @param {object} memory - memory 记录
- * @param {object} config - 插件配置
- * @param {number} [now=Date.now()] - 当前毫秒时间戳
- * @returns {{ type, ref, lambda, beta, deltaHours }}
- */
-export function buildHeatSignals(memory, config, now = Date.now()) {
-  const nowMs = Number.isFinite(now) ? now : Date.now();
-  const ref = getRef(memory);
-  const { beta, decayMap } = resolveConfig(config);
-
-  const type = memory?.type;
-
-  // 取对应类型的 λ，未知类型走默认
-  let lambda = decayMap[type];
-  if (!Number.isFinite(lambda)) {
-    lambda = DEFAULT_LAMBDA;
-  }
-  // λ < 0 视为非法，回退到默认；λ === 0 保留为免疫
-  if (lambda < 0) {
-    lambda = DEFAULT_LAMBDA;
-  }
-
-  let deltaHours;
-  if (!Number.isFinite(ref)) {
-    deltaHours = NaN;
-  } else if (nowMs < ref) {
-    deltaHours = 0;
-  } else {
-    deltaHours = (nowMs - ref) / HOUR_MS;
-  }
-
-  return { type, ref, lambda, beta, deltaHours };
-}
-
-/**
- * 计算 memory 的热度 H ∈ [0, 1]。
- *
- * 公式：H = exp(-λ · ΔtHours^β)
- *
- * @param {object} memory - memory 记录
- * @param {number} [now=Date.now()] - 当前毫秒时间戳
- * @param {object} [config={}] - 插件配置
- * @returns {number} 热度值
- */
-export function computeHeat(memory, now = Date.now(), config = {}) {
-  const signals = buildHeatSignals(memory, config, now);
-  const { beta, lambda, deltaHours, ref } = signals;
-
-  // 无有效参考时间、或未来时间，热度视为满格
-  if (!Number.isFinite(ref) || deltaHours <= 0) {
-    return 1.0;
-  }
-
-  // λ = 0 的类型免疫，热度恒满
-  if (lambda === 0) {
-    return 1.0;
-  }
-
-  const heat = Math.exp(-lambda * deltaHours ** beta);
-
-  // 防止浮点误差越界
-  return Math.min(1, Math.max(0, heat));
-}
+// dsh-mneme/src/heat.js
+// 热度（heat）纯函数模块：基于广义指数遗忘曲线计算 memory 的当前热度。
+// 零数据库依赖，不引入任何外部依赖。
+//
+// 曲线选型（issue #218，2026-09-18 与维护者对齐）：H = exp(-λ·Δt^β)。
+// FadeMem v2 Eq4 的广义指数族——λ 管速率（per-type 差异），β 管形状
+// （β=1 退化为纯指数，β<1 呈亚线性长尾）；λ=0 免疫位在指数式下同样恒 1。
+// v0.7.0–0.8.3 存量为幂律 H=(1+λΔt)^-α；幂律在 #164 已收集论文集外，
+// 真实负载回放（#218 验收 4）时对两个曲线族做拟合 A/B，幂律更贴合再议。
+
+/**
+ * 默认的 per-type 衰减因子 λ。
+ * λ = 0 表示该类型免疫热度衰减，热度恒为 1.0。
+ */
+export const TYPE_DECAY_DEFAULTS = Object.freeze({
+  preference: 0,    // 免疫：用户画像需长期保持
+  pattern: 0,       // 免疫：发现型稳定规律
+  summary: 0,       // 免疫：已是压缩产物
+  document: 0,      // 免疫：指针行（#230）——全文在文件系统，行失效靠 supersede
+                    // 记账而非遗忘；遗忘曲线灭掉指针 = 按需读全文的入口消失
+  project: 0.0008,  // 慢衰减
+  decision: 0.002,  // 中速衰减
+  history: 0.006,   // 较快（会话摘要不断被合并）
+});
+
+const HOUR_MS = 3600000;
+const DEFAULT_BETA = 1.0;
+const DEFAULT_LAMBDA = 0.002;
+
+/**
+ * 将可能的日期值统一转成毫秒时间戳。
+ * 支持 Date、number、ISO 字符串；无法解析时返回 NaN。
+ */
+function toTimestamp(value) {
+  if (value === null || value === undefined) return NaN;
+
+  if (value instanceof Date) {
+    return Number.isFinite(value.getTime()) ? value.getTime() : NaN;
+  }
+
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : NaN;
+  }
+
+  if (typeof value === 'string') {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : NaN;
+  }
+
+  return NaN;
+}
+
+/**
+ * 获取用于计算热度的参考时间点 ref。
+ * 优先取 last_accessed_at；缺失时退到 created_at。
+ * 绝不 fallback 到 updated_at。
+ */
+function getRef(memory) {
+  if (!memory || typeof memory !== 'object') return NaN;
+  return toTimestamp(memory.last_accessed_at ?? memory.created_at);
+}
+
+/**
+ * 解析并校验配置，提供安全的 β 与衰减表。
+ */
+function resolveConfig(config) {
+  const safe = config && typeof config === 'object' ? config : {};
+
+  let beta = safe.heatGlobalBeta ?? DEFAULT_BETA;
+  if (!Number.isFinite(beta) || beta <= 0) {
+    beta = DEFAULT_BETA;
+  }
+
+  const decayMap = safe.heatTypeDecay ?? TYPE_DECAY_DEFAULTS;
+
+  return { beta, decayMap };
+}
+
+/**
+ * 构建热度信号对象，便于调试与后续扩展。
+ *
+ * @param {object} memory - memory 记录
+ * @param {object} config - 插件配置
+ * @param {number} [now=Date.now()] - 当前毫秒时间戳
+ * @returns {{ type, ref, lambda, beta, deltaHours }}
+ */
+export function buildHeatSignals(memory, config, now = Date.now()) {
+  const nowMs = Number.isFinite(now) ? now : Date.now();
+  const ref = getRef(memory);
+  const { beta, decayMap } = resolveConfig(config);
+
+  const type = memory?.type;
+
+  // 取对应类型的 λ，未知类型走默认
+  let lambda = decayMap[type];
+  if (!Number.isFinite(lambda)) {
+    lambda = DEFAULT_LAMBDA;
+  }
+  // λ < 0 视为非法，回退到默认；λ === 0 保留为免疫
+  if (lambda < 0) {
+    lambda = DEFAULT_LAMBDA;
+  }
+
+  let deltaHours;
+  if (!Number.isFinite(ref)) {
+    deltaHours = NaN;
+  } else if (nowMs < ref) {
+    deltaHours = 0;
+  } else {
+    deltaHours = (nowMs - ref) / HOUR_MS;
+  }
+
+  return { type, ref, lambda, beta, deltaHours };
+}
+
+/**
+ * 计算 memory 的热度 H ∈ [0, 1]。
+ *
+ * 公式：H = exp(-λ · ΔtHours^β)
+ *
+ * @param {object} memory - memory 记录
+ * @param {number} [now=Date.now()] - 当前毫秒时间戳
+ * @param {object} [config={}] - 插件配置
+ * @returns {number} 热度值
+ */
+export function computeHeat(memory, now = Date.now(), config = {}) {
+  const signals = buildHeatSignals(memory, config, now);
+  const { beta, lambda, deltaHours, ref } = signals;
+
+  // 无有效参考时间、或未来时间，热度视为满格
+  if (!Number.isFinite(ref) || deltaHours <= 0) {
+    return 1.0;
+  }
+
+  // λ = 0 的类型免疫，热度恒满
+  if (lambda === 0) {
+    return 1.0;
+  }
+
+  const heat = Math.exp(-lambda * deltaHours ** beta);
+
+  // 防止浮点误差越界
+  return Math.min(1, Math.max(0, heat));
+}

package/src/hot-memory.js

@@ -1,107 +1,119 @@
-import { safeSlice } from "./safe-slice.js";
-// Issue #611：图片块改用占位文本，不再落进空串（见 roundsFromEvents 里的注释）。
-import { contentToText } from "./attachment-text.js";
-
-// Session-scoped hot memory (v0.5.0 召回率优化 1.3): a short-term buffer of
-// the latest dialogue rounds, kept strictly apart from the long-term memory
-// store. The injector renders it ahead of the long-term recall block so the
-// agent sees "what we were just talking about" without those rounds ever
-// being persisted as memories. Bounded two ways: maxRounds (count) and
-// maxTokens (budget) — whichever evicts first.
-
-// CJK-aware token estimate: one Chinese character ≈ 0.6 tokens (clustering
-// behavior of mainstream tokenizers), one ASCII char ≈ 0.25.
-export function estimateTokens(text) {
-  const s = String(text ?? "");
-  let cjk = 0;
-  for (const ch of s) if (ch >= "\u4e00" && ch <= "\u9fff") cjk++;
-  return Math.ceil(cjk * 0.6 + (s.length - cjk) * 0.25);
-}
-
-/**
- * @param {{maxRounds?: number, maxTokens?: number}} opts
- * @returns {{add(round: {query: string, response?: string}): void,
- *            getContext(): string,
- *            rounds(): Array, clear(): void}}
- */
-export function createHotMemory({ maxRounds = 5, maxTokens = 2000 } = {}) {
-  const buffer = [];
-
-  function totalTokens() {
-    return buffer.reduce(
-      (sum, r) => sum + estimateTokens(`Q: ${r.query}\nA: ${r.response ?? ""}`),
-      0
-    );
-  }
-
-  return {
-    add(round) {
-      if (!round?.query) return;
-      buffer.push({ query: String(round.query), response: String(round.response ?? "") });
-      while (buffer.length > maxRounds) buffer.shift();
-      while (buffer.length > 1 && totalTokens() > maxTokens) buffer.shift();
-    },
-    getContext() {
-      return buffer.map((r) => `Q: ${r.query}\nA: ${r.response ?? ""}`).join("\n\n");
-    },
-    rounds: () => [...buffer],
-    clear() { buffer.length = 0; }
-  };
-}
-
-// Issue：rewind（surfaceOp replace）/compact 遮蔽过的事件仍留在 append-only 事件
-// 流里——热记忆若直接遍历原始流，被撤回的轮次会回流进 prompt（用户实测：一次
-// 撤回 3+ 条后模型仍能复述大部分内容）。宿主在 session.surface.nodes 维护
-// 「模型可见事件 seq」列表（dsh-rewind 插件即据此计算替换区间）；调用方把可见
-// 集合传入本函数，只统计可见事件，热记忆与模型看到的对话因此同源。visibleSeqs
-// 传 null 表示宿主未提供 surface（老版本 DSH），保持旧行为——宁可持续旧偏差，
-// 绝不误删仍可见的轮次。
-//
-// 配对规则与 inject.js 原实现一致：user/message（source.kind 缺省或 "user"）开启
-// 新一轮；下一条 assistant 起源的事件关闭该轮。tool/system 等携带正文的事件不得
-// 冒充模型回复；rewind 标记（source.kind = "dsh-rewind"）不是用户提问。
-export function roundsFromEvents(events, maxRounds, visibleSeqs = null) {
-  const rounds = [];
-  let pendingQuery = null;
-  const textOf = (event) => {
-    // user/message 的正文就在 data 上，而 assistant/message（以及 tool/result）的消息体
-    // 嵌在 data.message 下 —— DSH 侧由 @deepseek-ai/dsh-session 的
-    // assertMessageEventShape 一行写死：const message = type === "user/message" ? record : record?.["message"]。
-    // 只读 data.content 会让每一轮的 response 恒为空（Issue #129）。
-    // 这里用 ?? 兜底而不是直接改成 data.message.content：user 消息与旧的扁平形状都照旧可用。
-    const parts = event?.data?.content ?? event?.data?.message?.content;
-    if (!Array.isArray(parts)) return "";
-    // 只取正文 part（type === "text" 或字符串），跳过 reasoning（issue #162）：
-    // reasoning 里出现 Go template / Vue / Handlebars / 正则 / 日志原文的概率远高于
-    // 正文，把它带进 hot memory 会让 `{{...}}` 模板片段注入 prompt。旧的扁平形状
-    // （字符串 part）照旧取用，无 type 字段的兜底视为正文。
-    //
-    // Issue #611：图片 part 原先在这里也落进空串分支，于是「用户发了截图」这件事
-    // 在 hot memory 里完全消失。改走 attachment-text 的占位口径：`[图: 名称 宽x高]`。
-    // hot memory 每轮都进 prompt，占位刻意保持短——它不是描述，只是「这里有过一张
-    // 图」的坐标。
-    return contentToText(parts).trim();
-  };
-  for (const event of events) {
-    // surface 投影：不在「模型可见面」上的事件（被 rewind 撤回、被 compact 替换）
-    // 不参与配对。
-    if (visibleSeqs && !visibleSeqs.has(event?.seq)) continue;
-    const kind = event?.data?.source?.kind;
-    const isUser = event?.type === "user/message" && (kind === undefined || kind === "user");
-    if (isUser) {
-      if (pendingQuery) rounds.push({ query: pendingQuery, response: "" });
-      pendingQuery = safeSlice(textOf(event), 500);
-      continue;
-    }
-    // Only assistant-originated events close a round; tool/system events
-    // carrying text must not be mistaken for the model's reply.
-    const isAssistant = typeof event?.type === "string" && event.type.includes("assistant")
-      || kind === "assistant";
-    const body = isAssistant ? textOf(event) : "";
-    if (!body || !pendingQuery) continue;
-    rounds.push({ query: pendingQuery, response: safeSlice(body, 800) });
-    pendingQuery = null;
-  }
-  if (pendingQuery) rounds.push({ query: pendingQuery, response: "" });
-  return rounds.slice(-maxRounds);
-}
+import { safeSlice } from "./safe-slice.js";
+// Issue #611：图片块改用占位文本，不再落进空串（见 roundsFromEvents 里的注释）。
+import { contentToText } from "./attachment-text.js";
+
+// Session-scoped hot memory (v0.5.0 召回率优化 1.3): a short-term buffer of
+// the latest dialogue rounds, kept strictly apart from the long-term memory
+// store. The injector renders it ahead of the long-term recall block so the
+// agent sees "what we were just talking about" without those rounds ever
+// being persisted as memories. Bounded two ways: maxRounds (count) and
+// maxTokens (budget) — whichever evicts first.
+
+// CJK-aware token estimate: one Chinese character ≈ 0.6 tokens (clustering
+// behavior of mainstream tokenizers), one ASCII char ≈ 0.25.
+export function estimateTokens(text) {
+  const s = String(text ?? "");
+  let cjk = 0;
+  for (const ch of s) if (ch >= "\u4e00" && ch <= "\u9fff") cjk++;
+  return Math.ceil(cjk * 0.6 + (s.length - cjk) * 0.25);
+}
+
+/**
+ * @param {{maxRounds?: number, maxTokens?: number}} opts
+ * @returns {{add(round: {query: string, response?: string}): void,
+ *            getContext(): string,
+ *            rounds(): Array, clear(): void}}
+ */
+export function createHotMemory({ maxRounds = 5, maxTokens = 2000 } = {}) {
+  const buffer = [];
+
+  function totalTokens() {
+    return buffer.reduce(
+      (sum, r) => sum + estimateTokens(`Q: ${r.query}\nA: ${r.response ?? ""}`),
+      0
+    );
+  }
+
+  return {
+    add(round) {
+      if (!round?.query) return;
+      buffer.push({ query: String(round.query), response: String(round.response ?? "") });
+      while (buffer.length > maxRounds) buffer.shift();
+      while (buffer.length > 1 && totalTokens() > maxTokens) buffer.shift();
+    },
+    getContext() {
+      return buffer.map((r) => `Q: ${r.query}\nA: ${r.response ?? ""}`).join("\n\n");
+    },
+    rounds: () => [...buffer],
+    clear() { buffer.length = 0; }
+  };
+}
+
+// Issue：rewind（surfaceOp replace）/compact 遮蔽过的事件仍留在 append-only 事件
+// 流里——热记忆若直接遍历原始流，被撤回的轮次会回流进 prompt（用户实测：一次
+// 撤回 3+ 条后模型仍能复述大部分内容）。宿主在 session.surface.nodes 维护
+// 「模型可见事件 seq」列表（dsh-rewind 插件即据此计算替换区间）；调用方把可见
+// 集合传入本函数，只统计可见事件，热记忆与模型看到的对话因此同源。visibleSeqs
+// 传 null 表示宿主未提供 surface（老版本 DSH），保持旧行为——宁可持续旧偏差，
+// 绝不误删仍可见的轮次。
+//
+// 配对规则与 inject.js 原实现一致：user/message（source.kind 缺省或 "user"）开启
+// 新一轮；下一条 assistant 起源的事件关闭该轮。tool/system 等携带正文的事件不得
+// 冒充模型回复；rewind 标记（source.kind = "dsh-rewind"）不是用户提问。
+//
+// omitPendingRound（Issue #637）：尾部 pending 轮是「正在组装的这一轮」——它的
+// 提问已经以真实 user message 出现在 prompt 里，热记忆再渲染一份只有空 `A:` 的
+// 行是纯冗余；更糟的是回答落地后这一行会从空 `A:` 抖成正文，而宿主对动态
+// systemPrompt context 的契约是「文本变了就追加一份快照」（旧份永久留在会话
+// 历史里），于是同一轮内注入块反复变体、旧快照越积越多（报告实测 4 轮 → 10 份
+// runtime-context、75% 重复率，其中记忆与设置两段是恒定的，抖动全来自热记忆）。
+// 只省略尾部这一条；循环中途被新 user/message 顶掉的历史 pending 是已被放弃的
+// 提问，渲染成空 `A:` 是既有语义，不动。注入侧传 true：一轮内块文本恒定，回答
+// 落地时块恰好变一次 = 每轮一份快照（该机制下的理论最小值）。默认 false = 既有
+// 行为逐字节不变——后台渲染与直调方（含既有测试锁的「已完成日志渲染」形状）
+// 照旧拿到 pending 轮。
+export function roundsFromEvents(events, maxRounds, visibleSeqs = null, { omitPendingRound = false } = {}) {
+  const rounds = [];
+  let pendingQuery = null;
+  const textOf = (event) => {
+    // user/message 的正文就在 data 上，而 assistant/message（以及 tool/result）的消息体
+    // 嵌在 data.message 下 —— DSH 侧由 @deepseek-ai/dsh-session 的
+    // assertMessageEventShape 一行写死：const message = type === "user/message" ? record : record?.["message"]。
+    // 只读 data.content 会让每一轮的 response 恒为空（Issue #129）。
+    // 这里用 ?? 兜底而不是直接改成 data.message.content：user 消息与旧的扁平形状都照旧可用。
+    const parts = event?.data?.content ?? event?.data?.message?.content;
+    if (!Array.isArray(parts)) return "";
+    // 只取正文 part（type === "text" 或字符串），跳过 reasoning（issue #162）：
+    // reasoning 里出现 Go template / Vue / Handlebars / 正则 / 日志原文的概率远高于
+    // 正文，把它带进 hot memory 会让 `{{...}}` 模板片段注入 prompt。旧的扁平形状
+    // （字符串 part）照旧取用，无 type 字段的兜底视为正文。
+    //
+    // Issue #611：图片 part 原先在这里也落进空串分支，于是「用户发了截图」这件事
+    // 在 hot memory 里完全消失。改走 attachment-text 的占位口径：`[图: 名称 宽x高]`。
+    // hot memory 每轮都进 prompt，占位刻意保持短——它不是描述，只是「这里有过一张
+    // 图」的坐标。
+    return contentToText(parts).trim();
+  };
+  for (const event of events) {
+    // surface 投影：不在「模型可见面」上的事件（被 rewind 撤回、被 compact 替换）
+    // 不参与配对。
+    if (visibleSeqs && !visibleSeqs.has(event?.seq)) continue;
+    const kind = event?.data?.source?.kind;
+    const isUser = event?.type === "user/message" && (kind === undefined || kind === "user");
+    if (isUser) {
+      if (pendingQuery) rounds.push({ query: pendingQuery, response: "" });
+      pendingQuery = safeSlice(textOf(event), 500);
+      continue;
+    }
+    // Only assistant-originated events close a round; tool/system events
+    // carrying text must not be mistaken for the model's reply.
+    const isAssistant = typeof event?.type === "string" && event.type.includes("assistant")
+      || kind === "assistant";
+    const body = isAssistant ? textOf(event) : "";
+    if (!body || !pendingQuery) continue;
+    rounds.push({ query: pendingQuery, response: safeSlice(body, 800) });
+    pendingQuery = null;
+  }
+  if (pendingQuery && !omitPendingRound) rounds.push({ query: pendingQuery, response: "" });
+  return rounds.slice(-maxRounds);
+}