@modusensus/dsh-mneme 0.8.2 → 0.8.4

package/lib/summarize.js

@@ -1,449 +1,575 @@
-import { BlockAssembler, createUserMessage } from "@deepseek-ai/dsh-llm";
-import { STR, langOf } from "./lang.js";
-
-// 编码记忆蒸馏 prompt（codingRetrospect 开启时启用）：在通用记忆之外，额外提取
-// 三类编码专属记忆，专治重复踩坑 / 遗忘被否决方案 / 丢失工程约束。字段仍沿用
-// title/content 单列结构（store 无结构化字段），信息浓缩进 content。
-/** Extract a JSON array from LLM output that may contain prose around it. */
-export function parseSummaryJson(raw) {
-  const text = String(raw ?? "");
-  const start = text.indexOf("[");
-  const end = text.lastIndexOf("]");
-  if (start === -1 || end === -1 || end <= start) return [];
-  let arr;
-  try {
-    arr = JSON.parse(text.slice(start, end + 1));
-  } catch {
-    return [];
-  }
-  if (!Array.isArray(arr)) return [];
-  const VALID = new Set(["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"]);
-  return arr.filter(
-    (item) =>
-      item &&
-      typeof item === "object" &&
-      VALID.has(item.type) &&
-      typeof item.title === "string" &&
-      item.title.trim() &&
-      typeof item.content === "string" &&
-      item.content.trim()
-  ).map((item) => ({
-    type: item.type,
-    title: item.title.trim(),
-    content: item.content.trim(),
-    importance: Number.isInteger(item.importance) ? Math.min(5, Math.max(1, item.importance)) : 3
-  }));
-}
-
-// The dsh-llm StreamChunk protocol BlockAssembler.push() consumes:
-// block-start {index, blockType}, text-delta {index, text},
-// block-end {index, block}, finish {reason}. Some consumers observe a
-// looser shape ({block} / {delta} / {kind}); normalize before pushing so
-// both real adapter streams and shape-tolerant test doubles assemble.
-const STREAM_CHUNK_TYPES = new Set([
-  "block-start",
-  "text-delta",
-  "reasoning-delta",
-  "tool-call-delta",
-  "block-end",
-  "usage",
-  "finish"
-]);
-
-function toProtocolChunk(chunk) {
-  switch (chunk.type) {
-    case "block-start":
-      return { type: "block-start", index: chunk.index ?? 0, blockType: chunk.blockType ?? chunk.block?.type ?? "text" };
-    case "text-delta":
-      return { type: "text-delta", index: chunk.index ?? 0, text: chunk.text ?? chunk.delta ?? "" };
-    case "reasoning-delta":
-      return { type: "reasoning-delta", index: chunk.index ?? 0, text: chunk.text ?? chunk.delta ?? "" };
-    case "block-end":
-      return { type: "block-end", index: chunk.index ?? 0, block: chunk.block ?? { type: "text" } };
-    case "finish":
-      return {
-        type: "finish",
-        reason: chunk.reason ?? { kind: chunk.kind === "error" ? "error" : "stop" },
-        replayState: chunk.replayState
-      };
-    default:
-      return chunk;
-  }
-}
-
-// Only direct human prompts are summarized: plugin-injected context
-// (AGENTS.md, skill bodies, file-change notices) and other machine-originated
-// events must not leak into the memory store. Events without a data payload
-// (minimal test doubles) pass the kind check and are handled by the content
-// check below.
-//
-// codingRetrospect: the distill context is the FULL turn transcript —
-// user prompts plus assistant public replies, tool calls + results and code
-// dispatch output — so the summarizer can see tool errors and extract pitfall
-// root causes, not just what the user typed. The same filtering stays: only
-// source.kind === "user" prompts enter (plugin/machine content is excluded).
-// The result is a single text transcript passed to the LLM as one user message
-// (SUMMARY_PROMPT already says "根据下面的会话内容").
-//
-// Privacy: assistant `reasoning` (private thought) blocks are deliberately NOT
-// collected — distilled memories must never sink private reasoning chains.
-// Only public text blocks (type "text") reach the summarizer.
-function collectMessages(session, maxChars = 8000, language = "zh") {
-  // DSH 0.1.2-rc.1 起 Session 改用 snapshotEvents()，兼容旧版 .events
-  const events = session.snapshotEvents?.() ?? session.events ?? [];
-  const lines = [];
-  // 兼容严格形状 [{type:"text",text}] 与宽松形状 ["字符串", ...]（lib-smoke 用例
-  // 直接传字符串数组）。只取公开文本块；reasoning 私有推理块不进蒸馏上下文。
-  const textOf = (content) => {
-    if (typeof content === "string") return content;
-    if (!Array.isArray(content)) return "";
-    return content
-      .map((block) => (typeof block === "string" ? block : (block && block.type === "text" && typeof block.text === "string" ? block.text : "")))
-      .filter((s) => s)
-      .join("\n");
-  };
-  const trim = (s, n) => (typeof s === "string" && s.length > n ? `${s.slice(0, n)}…` : s);
-  for (const event of events) {
-    const data = event?.data ?? {};
-    const kind = data?.source?.kind;
-    switch (event.type) {
-      case "user/message": {
-        if (kind !== undefined && kind !== "user") break;
-        const text = textOf(data?.content);
-        if (text.trim()) lines.push(STR.transcriptUser[language](text));
-        break;
-      }
-      case "assistant/message": {
-        const msg = data?.message;
-        const blocks = Array.isArray(msg?.content) ? msg.content : [];
-        const text = textOf(blocks);
-        if (text.trim()) lines.push(STR.transcriptAssistant[language](text));
-        // 私有推理块（reasoning）刻意不采集：蒸馏记忆不得沉淀模型私有思考链。
-        break;
-      }
-      case "tool/call": {
-        const args = typeof data.arguments === "string"
-          ? data.arguments
-          : data.arguments ? JSON.stringify(data.arguments) : "";
-        lines.push(STR.transcriptToolCall[language](data.name ?? "?", trim(args, 300)));
-        break;
-      }
-      case "tool/result": {
-        const out = typeof data.output === "string" ? data.output : data.output ? JSON.stringify(data.output) : "";
-        const status = data.ok === false ? STR.statusFail[language] : STR.statusOk[language];
-        lines.push(STR.transcriptToolResult[language](status, trim(out, 500)));
-        break;
-      }
-      case "tool/code-dispatch": {
-        const out = typeof data.output === "string" ? data.output : data.output ? JSON.stringify(data.output) : "";
-        const status = data.ok === false ? STR.statusFail[language] : STR.statusOk[language];
-        lines.push(STR.transcriptCode[language](status, trim(out, 500)));
-        break;
-      }
-      default:
-        break;
-    }
-  }
-  return lines.length ? [createUserMessage({ content: [{ type: "text", text: trim(lines.join("\n"), maxChars) }], source: { kind: "plugin", plugin: "dsh-mneme" } })] : [];
-}
-
-// ── 智能调速器（429 保护）─────────────────────────────────────────────
-// 对话一多时 turn/end 会批量触发蒸馏，多个 LLM 请求"一拥而上"正是 429 的
-// 来源。这里借鉴机场安检的思路：所有蒸馏调用进同一个全局串行队列，按间隔
-// distillRateLimitIntervalMs 分批放行；命中 429 时按 distillRateLimitBaseDelayMs
-// 指数退避（1s→2s→4s…）自动重试 distillRateLimitRetries 次，全程对用户透明，
-// 不把 429 错误码直接抛出去。
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-function isRateLimited(error) {
-  const status = error?.status ?? error?.statusCode ?? error?.response?.status;
-  if (status === 429) return true;
-  const msg = String(error?.message ?? error ?? "");
-  return /429|rate.?limit|too many requests|请求过于频繁/i.test(msg);
-}
-
-// 全局串行链：每个蒸馏任务在前一个结束后才开始，单次失败不阻塞后续。
-// 相邻请求间隔按"距上一个结束不足 intervalMs 就补齐等待"实现——单次蒸馏
-// 零延迟（上次结束距今已超过间隔，直接放行），只有连续批量蒸馏才触发限速。
-let distillQueue = Promise.resolve();
-let lastDistillEnd = 0;
-function enqueueDistill(task, intervalMs = 0) {
-  const run = distillQueue.then(async () => {
-    if (intervalMs > 0) {
-      const wait = Math.max(0, intervalMs - (Date.now() - lastDistillEnd));
-      if (wait > 0) await sleep(wait);
-    }
-    lastDistillEnd = Date.now();
-    return task();
-  });
-  distillQueue = run.catch(() => {});
-  return run;
-}
-
-export function createSummarizer(ctx, service, config) {
-  if (!config.autoSummarize) return { dispose: () => {} };
-
-  const inFlight = new Map();
-  // Issue #127：per-session 上一次实际开跑时刻（最小间隔闸门用）。与 inFlight
-  // 同生命周期，dispose 时一并清空。
-  const lastRunAt = new Map();
-  let disposed = false;
-
-  /** 写一条 autoSummarize 的 LLM 审计行（审计失败绝不阻塞蒸馏本身）。 */
-  function writeAudit(entry) {
-    if (config?.llmAudit?.enabled === false || typeof service.saveLlmAudit !== "function") return;
-    try {
-      service.saveLlmAudit({
-        trigger_source: "autoSummarize",
-        operation_type: "summarize_compress",
-        related_memory_ids: [],
-        ...entry
-      });
-    } catch (auditError) {
-      ctx.logger?.warn?.(`dsh-mneme: llm audit write failed: ${String(auditError)}`);
-    }
-  }
-
-  async function summarize(session) {
-    if (disposed || inFlight.has(session.id)) return;
-
-    const header = session.requestHeader?.()?.config;
-    // Config override takes priority, then session header, then nothing.
-    const route = (config.summarizeProvider && config.summarizeModel)
-      ? { provider: config.summarizeProvider, model: config.summarizeModel }
-      : (header?.provider && header?.model)
-        ? { provider: header.provider, model: header.model }
-        : undefined;
-
-    // Issue #127 间隔门：同一会话两次蒸馏之间的最小间隔（0 = 现状，不限）。进入
-    // 即打点——失败/degraded 的 run 也占用间隔，与 dreamMinIntervalMinutes 语义
-    // 一致，防止失败连发。被挡下的 turn/end 静默跳过，但留一行 status='skipped'
-    // 审计，否则「这一轮为什么没蒸馏」对用户完全不可观测。
-    const gapMs = (config.summarizeMinIntervalMinutes ?? 0) * 60000;
-    const prevClaim = lastRunAt.get(session.id);
-    if (gapMs > 0 && Date.now() - (prevClaim ?? 0) < gapMs) {
-      writeAudit({
-        timestamp: new Date().toISOString(),
-        model_id: route ? `${route.provider}:${route.model}` : "unknown",
-        status: "skipped",
-        error_message: "min-interval"
-      });
-      return;
-    }
-    lastRunAt.set(session.id, Date.now());
-
-    const controller = new AbortController();
-    inFlight.set(session.id, controller);
-    // audit state for the compression call. null = no audit for this run
-    // (disabled, or no LLM call was actually made). The audit row is written in
-    // the finally below — once, regardless of which exit path the call took —
-    // so a failed/aborted stream still leaves a status='error' trail without
-    // ever blocking the summarization itself.
-    let audit = null;
-    let abortedRun = false;
-    try {
-      if (!route) return;
-      // 完整转录（Codex 式）：蒸馏把整轮对话交给 LLM 提炼原子记忆，不再硬裁
-      // 8000 字截断语义；上限由 distillMaxChars 控制（默认 24000，可调大）。
-      const messages = collectMessages(session, config.distillMaxChars ?? 24000, langOf(config));
-      if (!messages.length) return;
-
-      if (config?.llmAudit?.enabled !== false && typeof service.saveLlmAudit === "function") {
-        audit = {
-          route,
-          timestamp: new Date().toISOString(),
-          startedAt: Date.now(),
-          inputTokens: 0,
-          outputTokens: 0,
-          status: "success",
-          errorMessage: null
-        };
-      }
-
-      const options = {
-        provider: route.provider,
-        model: route.model,
-        purpose: "summarization",
-        messages: [
-          { role: "system", content: [{ type: "text", text: config.codingRetrospect ? STR.prompts.codingSummary[langOf(config)] : STR.prompts.summary[langOf(config)] }], source: { kind: "plugin", plugin: "dsh-mneme" } },
-          ...messages
-        ],
-        signal: controller.signal
-      };
-      // 智能调速器：整段蒸馏 LLM 调用进全局串行队列，按间隔分批放行；429 时
-      // 指数退避自动重试，全程对用户透明，不把 429 错误码直接抛出去。
-      const intervalMs = config.distillRateLimitIntervalMs ?? 1000;
-      const { text, assembledText, aborted } = await enqueueDistill(async () => {
-        const retries = config.distillRateLimitRetries ?? 3;
-        const baseDelayMs = config.distillRateLimitBaseDelayMs ?? 1000;
-        for (let attempt = 0; ; attempt++) {
-          const assembler = new BlockAssembler();
-          let text = "";
-          let aborted = false;
-          try {
-            for await (const chunk of ctx.llm.stream(options)) {
-              if (STREAM_CHUNK_TYPES.has(chunk.type)) assembler.push(toProtocolChunk(chunk));
-              if (chunk.type === "text-delta") {
-                text += chunk.text ?? chunk.delta ?? "";
-              }
-              if (chunk.type === "usage" && audit) {
-                const i = chunk.input_tokens ?? chunk.inputTokens ?? chunk.prompt_tokens ?? chunk.promptTokens;
-                const o = chunk.output_tokens ?? chunk.outputTokens ?? chunk.completion_tokens ?? chunk.completionTokens;
-                if (Number.isFinite(i)) audit.inputTokens = i;
-                if (Number.isFinite(o)) audit.outputTokens = o;
-              }
-              if (chunk.type === "finish") {
-                const reasonKind = chunk.reason?.kind ?? chunk.kind;
-                if (reasonKind === "error" || reasonKind === "aborted") {
-                  // 429 也可能以 finish reason error 携带 rate-limit 信息，统一
-                  // 转抛错走指数退避重试。
-                  if (isRateLimited(chunk.reason ?? chunk)) {
-                    throw Object.assign(new Error("rate limited"), { status: 429 });
-                  }
-                  if (audit) {
-                    audit.status = "error";
-                    audit.errorMessage = `llm stream ${reasonKind}`;
-                  }
-                  aborted = true;
-                  break;
-                }
-              }
-            }
-            // Direct delta accumulation is the primary extraction path (it works
-            // for real protocol chunks {index,text} and looser {delta} shapes
-            // alike); the assembler blocks are a fallback for streams that only
-            // deliver text inside block-end. This dsh-llm exposes no public
-            // no-arg assemble() — blocks() is the message-level API.
-            const blocks = assembler.blocks();
-            const assembledText = blocks
-              .filter((b) => b.type === "text")
-              .map((b) => b.text ?? "")
-              .join("");
-            return { text, assembledText, aborted };
-          } catch (error) {
-            if (error?.name === "AbortError" || controller.signal.aborted) throw error; // dispose 中止直接放行
-            if (isRateLimited(error) && attempt < retries) {
-              const delay = baseDelayMs * 2 ** attempt;
-              ctx.logger?.warn?.(
-                `dsh-mneme: 蒸馏请求过于频繁(429)，为避免限流等待 ${delay}ms 后自动重试（第 ${attempt + 1}/${retries} 次）`
-              );
-              await sleep(delay);
-              continue;
-            }
-            // 429 重试耗尽或非 429 错误：记 audit 后抛出，保持原失败路径。
-            if (audit) {
-              audit.status = "error";
-              audit.errorMessage = String(error?.message ?? error);
-            }
-            throw error;
-          }
-        }
-      }, intervalMs);
-      if (aborted) {
-        abortedRun = true;
-        return;
-      }
-      const parsed = parseSummaryJson(text || assembledText);
-      // Issue #127 条数上限：0 = 不限（现状）。被截断的条数与去重命中数一并进
-      // 审计 metadata——此前产出条数完全由模型输出决定，用户无从自查。
-      const cap = config.summarizeMaxEntriesPerRun ?? 0;
-      const entries = cap > 0 ? parsed.slice(0, cap) : parsed;
-      const capped = parsed.length - entries.length;
-      const dedupeMode = config.summarizeDedupeMode ?? "off";
-      let deduped = 0;
-      let dedupeMaxSim = 0;
-      for (const entry of entries) {
-        // Provenance: the summarizer runs on a real session (turn/end hook), so
-        // session.id is always available here — it rides the human-readable
-        // source label.
-        // 编码记忆类型（codingRetrospect）不带 tag：读取侧门控/加权靠 m.type
-        // （rejected_solution/pitfall/constraint）区分即可，tag 体系
-        // sanitizeTags 不认 `type:` 前缀反而会清空 tags 列（额外一次 UPDATE）。
-        const source = `session:${session.id}`;
-        // Issue #127 落库前去重（opt-in，默认 off = 现状）：命中则并入既有条目
-        // （saveWithDedupe 的 _mergeInto 分支），不再新造一行。作用域 = 同会话 +
-        // 时间窗；跨会话的同类事实仍交给 autoDream / sleep 的批量裁决。
-        const dup = (dedupeMode !== "off" && typeof service.findSessionDuplicate === "function")
-          ? await service.findSessionDuplicate(
-            { ...entry, source },
-            {
-              mode: dedupeMode,
-              minSim: config.summarizeDedupeMinSim ?? 0.92,
-              windowHours: config.summarizeDedupeWindowHours ?? 24,
-              source
-            }
-          )
-          : undefined;
-        if (dup) {
-          deduped++;
-          dedupeMaxSim = Math.max(dedupeMaxSim, dup.sim ?? 0);
-        }
-        service.saveWithDedupe({
-          ...entry,
-          source,
-          ...(dup ? { _mergeInto: dup.memory.id } : {})
-        });
-      }
-      if (audit && (capped > 0 || deduped > 0)) {
-        audit.metadata = {
-          parsed: parsed.length,
-          ...(capped > 0 ? { capped } : {}),
-          ...(deduped > 0 ? { deduped, mode: dedupeMode, maxSim: Number(dedupeMaxSim.toFixed(4)) } : {})
-        };
-      }
-    } finally {
-      // Issue #127：aborted（会话关闭 / 插件 dispose）不占间隔，避免误伤该会话的
-      // 下一次蒸馏；其余情况（含失败）的打点保留，与 dreamMinIntervalMinutes 一致。
-      if (abortedRun || controller.signal.aborted) {
-        if (prevClaim === undefined) lastRunAt.delete(session.id);
-        else lastRunAt.set(session.id, prevClaim);
-      }
-      if (audit) {
-        try {
-          service.saveLlmAudit({
-            timestamp: audit.timestamp,
-            trigger_source: "autoSummarize",
-            operation_type: "summarize_compress",
-            model_id: `${audit.route.provider}:${audit.route.model}`,
-            input_tokens: audit.inputTokens,
-            output_tokens: audit.outputTokens,
-            total_tokens: audit.inputTokens + audit.outputTokens,
-            cost_usd: 0,
-            duration_ms: Date.now() - audit.startedAt,
-            status: audit.status,
-            error_message: audit.errorMessage,
-            related_memory_ids: [],
-            // Issue #127：parsed / capped / deduped 的观测数据。零 schema 变更
-            // （llm_audit_logs.metadata 已存在），一条 SQL 即可验证节流是否生效。
-            metadata: audit.metadata
-          });
-        } catch (auditError) {
-          ctx.logger?.warn?.(`dsh-mneme: llm audit write failed: ${String(auditError)}`);
-        }
-      }
-      inFlight.delete(session.id);
-    }
-  }
-
-  const unsubscribe = ctx.on("session/event", (session, event) => {
-    if (disposed || event.type !== "turn/end") return;
-    // Return the summarization promise so awaiters observe the writes; the
-    // catch keeps listener dispatch from rejecting. Dispose-initiated aborts
-    // and external AbortErrors are silent.
-    return summarize(session).catch((error) => {
-      if (disposed || error?.name === "AbortError") return;
-      ctx.logger?.warn?.(`dsh-mneme: summarization failed: ${String(error)}`);
-    });
-  });
-
-  return {
-    dispose() {
-      if (disposed) return;
-      disposed = true;
-      unsubscribe?.();
-      for (const controller of inFlight.values()) controller.abort();
-      inFlight.clear();
-      lastRunAt.clear();
-    }
-  };
-}
+import { BlockAssembler, createUserMessage } from "@deepseek-ai/dsh-llm";
+import { STR, langOf } from "./lang.js";
+
+// 编码记忆蒸馏 prompt（codingRetrospect 开启时启用）：在通用记忆之外，额外提取
+// 三类编码专属记忆，专治重复踩坑 / 遗忘被否决方案 / 丢失工程约束。字段仍沿用
+// title/content 单列结构（store 无结构化字段），信息浓缩进 content。
+/** 解析 LLM 输出中的 JSON 数组，并保留数组是否有效的结果。 */
+function parseSummaryJsonResult(raw) {
+  const text = String(raw ?? "");
+  const start = text.indexOf("[");
+  const end = text.lastIndexOf("]");
+  if (start === -1 || end === -1 || end <= start) return { ok: false, entries: [] };
+  let arr;
+  try {
+    arr = JSON.parse(text.slice(start, end + 1));
+  } catch {
+    return { ok: false, entries: [] };
+  }
+  if (!Array.isArray(arr)) return { ok: false, entries: [] };
+  const VALID = new Set(["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"]);
+  const entries = arr.filter(
+    (item) =>
+      item &&
+      typeof item === "object" &&
+      VALID.has(item.type) &&
+      typeof item.title === "string" &&
+      item.title.trim() &&
+      typeof item.content === "string" &&
+      item.content.trim()
+  ).map((item) => ({
+    type: item.type,
+    title: item.title.trim(),
+    content: item.content.trim(),
+    importance: Number.isInteger(item.importance) ? Math.min(5, Math.max(1, item.importance)) : 3
+  }));
+  // 空数组表示模型明确判断本轮没有可沉淀内容；非空数组若全部无效，
+  // 则不能消费窗口，否则无效输出会永久推进 seq 游标。
+  return { ok: arr.length === 0 || entries.length > 0, entries };
+}
+
+/** Extract a JSON array from LLM output that may contain prose around it. */
+export function parseSummaryJson(raw) {
+  return parseSummaryJsonResult(raw).entries;
+}
+
+// The dsh-llm StreamChunk protocol BlockAssembler.push() consumes:
+// block-start {index, blockType}, text-delta {index, text},
+// block-end {index, block}, finish {reason}. Some consumers observe a
+// looser shape ({block} / {delta} / {kind}); normalize before pushing so
+// both real adapter streams and shape-tolerant test doubles assemble.
+const STREAM_CHUNK_TYPES = new Set([
+  "block-start",
+  "text-delta",
+  "reasoning-delta",
+  "tool-call-delta",
+  "block-end",
+  "usage",
+  "finish"
+]);
+
+function toProtocolChunk(chunk) {
+  switch (chunk.type) {
+    case "block-start":
+      return { type: "block-start", index: chunk.index ?? 0, blockType: chunk.blockType ?? chunk.block?.type ?? "text" };
+    case "text-delta":
+      return { type: "text-delta", index: chunk.index ?? 0, text: chunk.text ?? chunk.delta ?? "" };
+    case "reasoning-delta":
+      return { type: "reasoning-delta", index: chunk.index ?? 0, text: chunk.text ?? chunk.delta ?? "" };
+    case "block-end":
+      return { type: "block-end", index: chunk.index ?? 0, block: chunk.block ?? { type: "text" } };
+    case "finish":
+      return {
+        type: "finish",
+        reason: chunk.reason ?? { kind: chunk.kind === "error" ? "error" : "stop" },
+        replayState: chunk.replayState
+      };
+    default:
+      return chunk;
+  }
+}
+
+// Only direct human prompts are summarized: plugin-injected context
+// (AGENTS.md, skill bodies, file-change notices) and other machine-originated
+// events must not leak into the memory store. Events without a data payload
+// (minimal test doubles) pass the kind check and are handled by the content
+// check below.
+//
+// codingRetrospect: each new distill window contains the complete available
+// transcript for that window — user prompts plus assistant public replies, tool
+// calls + results and code dispatch output — so the summarizer can see tool
+// errors and extract pitfall root causes, not just what the user typed. The same
+// filtering stays: only source.kind === "user" prompts enter (plugin/machine
+// content is excluded). The result is a single text transcript passed to the
+// LLM as one user message (SUMMARY_PROMPT already says "根据下面的会话内容").
+//
+// Privacy: assistant `reasoning` (private thought) blocks are deliberately NOT
+// collected — distilled memories must never sink private reasoning chains.
+// Only public text blocks (type "text") reach the summarizer.
+function eventSeq(event) {
+  return Number.isSafeInteger(event?.seq) ? event.seq : undefined;
+}
+
+const SUBAGENT_MESSAGE_KINDS = new Set(["agent-message", "subagent-settled"]);
+
+// DSH 0.1.2-rc.1 起 Session 改用 snapshotEvents()，兼容旧版 .events。
+// snapshotEvents 的范围参数按 seq 传入；再做一次事件级过滤，是为了兼容
+// 旧实现忽略参数、或把边界解释为闭区间的情况，同时避免用数组下标充当游标。
+function snapshotSessionEvents(session, afterSeq, throughSeq) {
+  let events;
+  if (typeof session?.snapshotEvents === "function") {
+    events = afterSeq === undefined && throughSeq === undefined
+      ? session.snapshotEvents()
+      : session.snapshotEvents(afterSeq, throughSeq);
+  } else {
+    events = session?.events ?? [];
+  }
+  if (!Array.isArray(events)) events = session?.events ?? [];
+  if (!Array.isArray(events)) return [];
+  return events.filter((event) => {
+    const seq = eventSeq(event);
+    // 一旦已有 seq 游标，没有 seq 的事件就无法证明是新增事件，不能重新打开
+    // 已经成功消费过的窗口。
+    if (afterSeq !== undefined && (seq === undefined || seq <= afterSeq)) return false;
+    if (throughSeq !== undefined && seq !== undefined && seq > throughSeq) return false;
+    return true;
+  });
+}
+
+function collectMessages(session, maxChars = 8000, language = "zh", afterSeq, throughSeq) {
+  const events = snapshotSessionEvents(session, afterSeq, throughSeq);
+  const lines = [];
+  const seenSubagentMessages = new Set();
+  // 兼容严格形状 [{type:"text",text}] 与宽松形状 ["字符串", ...]（lib-smoke 用例
+  // 直接传字符串数组）。只取公开文本块；reasoning 私有推理块不进蒸馏上下文。
+  const textOf = (content) => {
+    if (typeof content === "string") return content;
+    if (!Array.isArray(content)) return "";
+    return content
+      .map((block) => (typeof block === "string" ? block : (block && block.type === "text" && typeof block.text === "string" ? block.text : "")))
+      .filter((s) => s)
+      .join("\n");
+  };
+  const trim = (s, n) => (typeof s === "string" && s.length > n ? `${s.slice(0, n)}…` : s);
+  const trimTranscript = (s, n) => {
+    if (typeof s !== "string" || s.length <= n) return s;
+    if (n <= 1) return "…".slice(0, n);
+    return `…${s.slice(-(n - 1))}`;
+  };
+  const appendSubagentMessage = (message) => {
+    const kind = message?.source?.kind;
+    if (!SUBAGENT_MESSAGE_KINDS.has(kind)) return;
+    const text = textOf(message?.content);
+    if (!text.trim()) return;
+    const key = typeof message?.id === "string" && message.id
+      ? `id:${message.id}`
+      : `content:${kind}:${text}`;
+    if (seenSubagentMessages.has(key)) return;
+    seenSubagentMessages.add(key);
+    lines.push(STR.transcriptAgent[language](text));
+  };
+  for (const event of events) {
+    const data = event?.data ?? {};
+    const kind = data?.source?.kind;
+    switch (event.type) {
+      case "user/message": {
+        if (kind !== undefined && kind !== "user" && !SUBAGENT_MESSAGE_KINDS.has(kind)) break;
+        const text = textOf(data?.content);
+        if (!text.trim()) break;
+        if (SUBAGENT_MESSAGE_KINDS.has(kind)) appendSubagentMessage(data);
+        else lines.push(STR.transcriptUser[language](text));
+        break;
+      }
+      case "agent/inbox/spliced": {
+        const inserted = Array.isArray(data?.inserted) ? data.inserted : [];
+        for (const message of inserted) appendSubagentMessage(message);
+        break;
+      }
+      case "assistant/message": {
+        const msg = data?.message;
+        const blocks = Array.isArray(msg?.content) ? msg.content : [];
+        const text = textOf(blocks);
+        if (text.trim()) lines.push(STR.transcriptAssistant[language](text));
+        // 私有推理块（reasoning）刻意不采集：蒸馏记忆不得沉淀模型私有思考链。
+        break;
+      }
+      case "tool/call": {
+        const args = typeof data.arguments === "string"
+          ? data.arguments
+          : data.arguments ? JSON.stringify(data.arguments) : "";
+        lines.push(STR.transcriptToolCall[language](data.name ?? "?", trim(args, 300)));
+        break;
+      }
+      case "tool/result": {
+        const result = Array.isArray(data?.message?.content)
+          ? data.message.content.find((block) => block?.type === "tool-result")
+          : undefined;
+        const out = textOf(result?.content);
+        const status = result?.isError === true ? STR.statusFail[language] : STR.statusOk[language];
+        lines.push(STR.transcriptToolResult[language](status, trim(out, 500)));
+        break;
+      }
+      case "tool/code-dispatch": {
+        const out = textOf(data.content);
+        const status = data.isError === true ? STR.statusFail[language] : STR.statusOk[language];
+        lines.push(STR.transcriptCode[language](status, trim(out, 500)));
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  const lastSeq = events.reduce((max, event) => {
+    const seq = eventSeq(event);
+    if (seq === undefined) return max;
+    return max === undefined ? seq : Math.max(max, seq);
+  }, undefined);
+  return {
+    messages: lines.length
+      ? [createUserMessage({ content: [{ type: "text", text: trimTranscript(lines.join("\n"), maxChars) }], source: { kind: "plugin", plugin: "dsh-mneme" } })]
+      : [],
+    hasEvents: events.length > 0,
+    lastSeq
+  };
+}
+
+// ── 智能调速器（429 保护）─────────────────────────────────────────────
+// 对话一多时 turn/end 会批量触发蒸馏，多个 LLM 请求"一拥而上"正是 429 的
+// 来源。这里借鉴机场安检的思路：所有蒸馏调用进同一个全局串行队列，按间隔
+// distillRateLimitIntervalMs 分批放行；命中 429 时按 distillRateLimitBaseDelayMs
+// 指数退避（1s→2s→4s…）自动重试 distillRateLimitRetries 次，全程对用户透明，
+// 不把 429 错误码直接抛出去。
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function isRateLimited(error) {
+  const status = error?.status ?? error?.statusCode ?? error?.response?.status;
+  if (status === 429) return true;
+  const msg = String(error?.message ?? error ?? "");
+  return /429|rate.?limit|too many requests|请求过于频繁/i.test(msg);
+}
+
+// 全局串行链：每个蒸馏任务在前一个结束后才开始，单次失败不阻塞后续。
+// 相邻请求间隔按"距上一个结束不足 intervalMs 就补齐等待"实现——单次蒸馏
+// 零延迟（上次结束距今已超过间隔，直接放行），只有连续批量蒸馏才触发限速。
+let distillQueue = Promise.resolve();
+let lastDistillEnd = 0;
+function enqueueDistill(task, intervalMs = 0) {
+  const run = distillQueue.then(async () => {
+    if (intervalMs > 0) {
+      const wait = Math.max(0, intervalMs - (Date.now() - lastDistillEnd));
+      if (wait > 0) await sleep(wait);
+    }
+    lastDistillEnd = Date.now();
+    return task();
+  });
+  distillQueue = run.catch(() => {});
+  return run;
+}
+
+export function createSummarizer(ctx, service, config) {
+  if (!config.autoSummarize) return { dispose: () => {} };
+
+  const inFlight = new Map();
+  // Issue #127：per-session 上一次实际开跑时刻（最小间隔闸门用）。与 inFlight
+  // 同生命周期，dispose 时一并清空。
+  const lastRunAt = new Map();
+  // Issue #210：只在一次蒸馏完整成功后记录已消费的最后事件 seq。
+  const lastDistilledSeq = new Map();
+  let disposed = false;
+
+  /** 写一条 autoSummarize 的 LLM 审计行（审计失败绝不阻塞蒸馏本身）。 */
+  function writeAudit(entry) {
+    if (config?.llmAudit?.enabled === false || typeof service.saveLlmAudit !== "function") return;
+    try {
+      service.saveLlmAudit({
+        trigger_source: "autoSummarize",
+        operation_type: "summarize_compress",
+        related_memory_ids: [],
+        ...entry
+      });
+    } catch (auditError) {
+      ctx.logger?.warn?.(`dsh-mneme: llm audit write failed: ${String(auditError)}`);
+    }
+  }
+
+  async function summarize(session, triggerEvent) {
+    if (disposed || inFlight.has(session.id)) return;
+
+    const header = session.requestHeader?.()?.config;
+    // Config override takes priority, then session header, then nothing.
+    const route = (config.summarizeProvider && config.summarizeModel)
+      ? { provider: config.summarizeProvider, model: config.summarizeModel }
+      : (header?.provider && header?.model)
+        ? { provider: header.provider, model: header.model }
+        : undefined;
+
+    // Issue #127 间隔门：同一会话两次蒸馏之间的最小间隔（0 = 现状，不限）。进入
+    // 即打点——失败/degraded 的 run 也占用间隔，与 dreamMinIntervalMinutes 语义
+    // 一致，防止失败连发。被挡下的 turn/end 静默跳过，但留一行 status='skipped'
+    // 审计，否则「这一轮为什么没蒸馏」对用户完全不可观测。
+    const gapMs = (config.summarizeMinIntervalMinutes ?? 0) * 60000;
+    const prevClaim = lastRunAt.get(session.id);
+    if (gapMs > 0 && Date.now() - (prevClaim ?? 0) < gapMs) {
+      writeAudit({
+        timestamp: new Date().toISOString(),
+        model_id: route ? `${route.provider}:${route.model}` : "unknown",
+        status: "skipped",
+        error_message: "min-interval"
+      });
+      return;
+    }
+    const controller = new AbortController();
+    inFlight.set(session.id, controller);
+    // audit state for the compression call. null = no audit for this run
+    // (disabled, or no LLM call was actually made). The audit row is written in
+    // the finally below — once, regardless of which exit path the call took —
+    // so a failed/aborted stream still leaves a status='error' trail without
+    // ever blocking the summarization itself.
+    let audit = null;
+    let abortedRun = false;
+    try {
+      if (!route) return;
+      const previousSeq = lastDistilledSeq.get(session.id);
+      const triggerSeq = eventSeq(triggerEvent);
+      // 只读取上次成功游标之后、当前 turn/end 之前的事件。旧版 snapshotEvents
+      // 即使忽略范围参数，collectMessages 仍会按事件 seq 二次过滤。
+      const collected = collectMessages(
+        session,
+        config.distillMaxChars ?? 24000,
+        langOf(config),
+        previousSeq,
+        triggerSeq
+      );
+      const hasNewEvents = collected.hasEvents
+        || (triggerSeq !== undefined && (previousSeq === undefined || triggerSeq > previousSeq));
+      if (!hasNewEvents) return;
+
+      const nextSeq = Math.max(collected.lastSeq ?? Number.NEGATIVE_INFINITY, triggerSeq ?? Number.NEGATIVE_INFINITY);
+      if (!collected.messages.length) {
+        // 没有可蒸馏的公开文本也算成功消费当前事件窗口，避免每个 turn/end
+        // 都重新扫描同一批无内容事件；没有 seq 时则不提交不可验证的游标。
+        if (Number.isFinite(nextSeq)) lastDistilledSeq.set(session.id, nextSeq);
+        return;
+      }
+      const messages = collected.messages;
+      // 只有真正准备发起一次 LLM 蒸馏时才占用最小间隔；失败路径仍按原语义
+      // 占用，aborted 则由 finally 回滚。
+      lastRunAt.set(session.id, Date.now());
+
+      if (config?.llmAudit?.enabled !== false && typeof service.saveLlmAudit === "function") {
+        audit = {
+          route,
+          timestamp: new Date().toISOString(),
+          startedAt: Date.now(),
+          inputTokens: 0,
+          outputTokens: 0,
+          status: "success",
+          errorMessage: null
+        };
+      }
+
+      const options = {
+        provider: route.provider,
+        model: route.model,
+        purpose: "summarization",
+        messages: [
+          { role: "system", content: [{ type: "text", text: config.codingRetrospect ? STR.prompts.codingSummary[langOf(config)] : STR.prompts.summary[langOf(config)] }], source: { kind: "plugin", plugin: "dsh-mneme" } },
+          ...messages
+        ],
+        signal: controller.signal
+      };
+      // 智能调速器：整段蒸馏 LLM 调用进全局串行队列，按间隔分批放行；429 时
+      // 指数退避自动重试，全程对用户透明，不把 429 错误码直接抛出去。
+      const intervalMs = config.distillRateLimitIntervalMs ?? 1000;
+      const { text, assembledText, aborted } = await enqueueDistill(async () => {
+        const retries = config.distillRateLimitRetries ?? 3;
+        const baseDelayMs = config.distillRateLimitBaseDelayMs ?? 1000;
+        for (let attempt = 0; ; attempt++) {
+          const assembler = new BlockAssembler();
+          let text = "";
+          let aborted = false;
+          try {
+            for await (const chunk of ctx.llm.stream(options)) {
+              if (STREAM_CHUNK_TYPES.has(chunk.type)) assembler.push(toProtocolChunk(chunk));
+              if (chunk.type === "text-delta") {
+                text += chunk.text ?? chunk.delta ?? "";
+              }
+              if (chunk.type === "usage" && audit) {
+                const i = chunk.input_tokens ?? chunk.inputTokens ?? chunk.prompt_tokens ?? chunk.promptTokens;
+                const o = chunk.output_tokens ?? chunk.outputTokens ?? chunk.completion_tokens ?? chunk.completionTokens;
+                if (Number.isFinite(i)) audit.inputTokens = i;
+                if (Number.isFinite(o)) audit.outputTokens = o;
+              }
+              if (chunk.type === "finish") {
+                const reasonKind = chunk.reason?.kind ?? chunk.kind;
+                if (reasonKind === "error" || reasonKind === "aborted") {
+                  // 429 也可能以 finish reason error 携带 rate-limit 信息，统一
+                  // 转抛错走指数退避重试。
+                  if (isRateLimited(chunk.reason ?? chunk)) {
+                    throw Object.assign(new Error("rate limited"), { status: 429 });
+                  }
+                  if (audit) {
+                    audit.status = "error";
+                    audit.errorMessage = `llm stream ${reasonKind}`;
+                  }
+                  aborted = true;
+                  break;
+                }
+              }
+            }
+            // Direct delta accumulation is the primary extraction path (it works
+            // for real protocol chunks {index,text} and looser {delta} shapes
+            // alike); the assembler blocks are a fallback for streams that only
+            // deliver text inside block-end. This dsh-llm exposes no public
+            // no-arg assemble() — blocks() is the message-level API.
+            const blocks = assembler.blocks();
+            const assembledText = blocks
+              .filter((b) => b.type === "text")
+              .map((b) => b.text ?? "")
+              .join("");
+            return { text, assembledText, aborted };
+          } catch (error) {
+            if (error?.name === "AbortError" || controller.signal.aborted) throw error; // dispose 中止直接放行
+            if (isRateLimited(error) && attempt < retries) {
+              const delay = baseDelayMs * 2 ** attempt;
+              ctx.logger?.warn?.(
+                `dsh-mneme: 蒸馏请求过于频繁(429)，为避免限流等待 ${delay}ms 后自动重试（第 ${attempt + 1}/${retries} 次）`
+              );
+              await sleep(delay);
+              continue;
+            }
+            // 429 重试耗尽或非 429 错误：记 audit 后抛出，保持原失败路径。
+            if (audit) {
+              audit.status = "error";
+              audit.errorMessage = String(error?.message ?? error);
+            }
+            throw error;
+          }
+        }
+      }, intervalMs);
+      if (aborted) {
+        abortedRun = true;
+        return;
+      }
+      const parsedResult = parseSummaryJsonResult(text || assembledText);
+      // 解析失败不推进 seq 游标，下一次 turn/end 仍会重试同一窗口。
+      if (!parsedResult.ok) {
+        if (audit) {
+          audit.status = "error";
+          audit.errorMessage = "invalid summary JSON";
+        }
+        return;
+      }
+      const parsed = parsedResult.entries;
+      // Issue #127 条数上限：0 = 不限（现状）。被截断的条数与去重命中数一并进
+      // 审计 metadata——此前产出条数完全由模型输出决定，用户无从自查。
+      const cap = config.summarizeMaxEntriesPerRun ?? 0;
+      const entries = cap > 0 ? parsed.slice(0, cap) : parsed;
+      const capped = parsed.length - entries.length;
+      const dedupeMode = config.summarizeDedupeMode ?? "off";
+      let deduped = 0;
+      let dedupeMaxSim = 0;
+      const writes = [];
+      for (const entry of entries) {
+        // Provenance: the summarizer runs on a real session (turn/end hook), so
+        // session.id is always available here — it rides the human-readable
+        // source label.
+        // 编码记忆类型（codingRetrospect）不带 tag：读取侧门控/加权靠 m.type
+        // （rejected_solution/pitfall/constraint）区分即可，tag 体系
+        // sanitizeTags 不认 `type:` 前缀反而会清空 tags 列（额外一次 UPDATE）。
+        const source = `session:${session.id}`;
+        // Issue #127 落库前去重（opt-in，默认 off = 现状）：命中则并入既有条目
+        // （saveWithDedupe 的 _mergeInto 分支），不再新造一行。作用域 = 同会话 +
+        // 时间窗；跨会话的同类事实仍交给 autoDream / sleep 的批量裁决。
+        const dup = (dedupeMode !== "off" && typeof service.findSessionDuplicate === "function")
+          ? await service.findSessionDuplicate(
+            { ...entry, source },
+            {
+              mode: dedupeMode,
+              minSim: config.summarizeDedupeMinSim ?? 0.92,
+              windowHours: config.summarizeDedupeWindowHours ?? 24,
+              source
+            }
+          )
+          : undefined;
+        if (dup) {
+          deduped++;
+          dedupeMaxSim = Math.max(dedupeMaxSim, dup.sim ?? 0);
+        }
+        writes.push({ entry, source, dup });
+      }
+      if (writes.length) {
+        // 查询去重目标可以异步执行，但记忆写入必须在同一个事务中完成。
+        // 否则第 N 条写入失败时，前 N-1 条会残留，而重试同一 seq 窗口会重复
+        // 追加它们。createService 始终提供 transaction；缺失时直接失败并保留
+        // 游标窗口，避免退回到不具备原子性的部分写入。
+        if (typeof service.transaction !== "function") {
+          throw new Error("dsh-mneme: atomic summarization writes require service.transaction");
+        }
+        service.transaction(() => {
+          for (const { entry, source, dup } of writes) {
+            service.saveWithDedupe({
+              ...entry,
+              source,
+              ...(dup ? { _mergeInto: dup.memory.id } : {})
+            });
+          }
+        });
+      }
+      if (audit && (capped > 0 || deduped > 0)) {
+        audit.metadata = {
+          parsed: parsed.length,
+          ...(capped > 0 ? { capped } : {}),
+          ...(deduped > 0 ? { deduped, mode: dedupeMode, maxSim: Number(dedupeMaxSim.toFixed(4)) } : {})
+        };
+      }
+      // 记忆写入和解析都成功后才提交窗口；流失败、中止、解析失败或写入异常
+      // 都会在此之前退出，从而保留窗口供下一次重试。
+      if (Number.isFinite(nextSeq)) lastDistilledSeq.set(session.id, nextSeq);
+    } finally {
+      // Issue #127：aborted（会话关闭 / 插件 dispose）不占间隔，避免误伤该会话的
+      // 下一次蒸馏；其余情况（含失败）的打点保留，与 dreamMinIntervalMinutes 一致。
+      if (abortedRun || controller.signal.aborted) {
+        if (prevClaim === undefined) lastRunAt.delete(session.id);
+        else lastRunAt.set(session.id, prevClaim);
+      }
+      if (audit) {
+        try {
+          service.saveLlmAudit({
+            timestamp: audit.timestamp,
+            trigger_source: "autoSummarize",
+            operation_type: "summarize_compress",
+            model_id: `${audit.route.provider}:${audit.route.model}`,
+            input_tokens: audit.inputTokens,
+            output_tokens: audit.outputTokens,
+            total_tokens: audit.inputTokens + audit.outputTokens,
+            cost_usd: 0,
+            duration_ms: Date.now() - audit.startedAt,
+            status: audit.status,
+            error_message: audit.errorMessage,
+            related_memory_ids: [],
+            // Issue #127：parsed / capped / deduped 的观测数据。零 schema 变更
+            // （llm_audit_logs.metadata 已存在），一条 SQL 即可验证节流是否生效。
+            metadata: audit.metadata
+          });
+        } catch (auditError) {
+          ctx.logger?.warn?.(`dsh-mneme: llm audit write failed: ${String(auditError)}`);
+        }
+      }
+      inFlight.delete(session.id);
+    }
+  }
+
+  const unsubscribe = ctx.on("session/event", (session, event) => {
+    if (disposed || event.type !== "turn/end") return;
+    // Return the summarization promise so awaiters observe the writes; the
+    // catch keeps listener dispatch from rejecting. Dispose-initiated aborts
+    // and external AbortErrors are silent.
+    return summarize(session, event).catch((error) => {
+      if (disposed || error?.name === "AbortError") return;
+      ctx.logger?.warn?.(`dsh-mneme: summarization failed: ${String(error)}`);
+    });
+  });
+
+  return {
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      unsubscribe?.();
+      for (const controller of inFlight.values()) controller.abort();
+      inFlight.clear();
+      lastRunAt.clear();
+      lastDistilledSeq.clear();
+    }
+  };
+}