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

package/src/content-hash.js

@@ -1,54 +1,54 @@
-// #254 写入准入的确定性计量锚：内容归一化哈希（exact duplicate 判定）。
-//
-// 为什么用哈希而不是相似度：计量阶段要的是一个零成本、可复算、不留争议的判据。
-// 相似度阈值两边都是误判——同一件事换个说法就掉到线下，不同的事共享话题词又顶到
-// 线上，阈值往哪边挪都只是换一种错法（#254 拍板：计量信号用内容哈希）。哈希只认
-// 「归一化后逐字节相同」，算不出来就只有一种解释。
-//
-// 但它不等于「原文逐字节相同」：归一化会折掉格式，也会折掉标点，于是 `版本 3.5` 与
-// `版本 35`、`a-b` 与 `ab` 落同一个键。折叠范围（大小写 / 空白 / 标点）是口径本身
-// 定的，#254 已拍板——误报面在计量阶段可接受（只标记、不拦截），但「命中即精确重复」
-// 这句话别升级成「命中即内容相同」。要更窄的判据就得改归一化口径，而那要带存量重算。
-//
-// 归一化口径一次定死（NFKC → 小写 → 去标点 → 空白折叠 → trim），动机是让「只差
-// 格式」的两次写入落在同一个键上：全角/半角、大小写、行内换行与缩进、句末标点都
-// 不该让同一件事变成两条。反过来它不折叠同义词、不排序词序——那些只能靠相似度，
-// 而相似度已判定不可用于本信号。
-//
-// 改口径必须带存量重算策略：memories.content_hash 是派生列，口径一变，库里已有的
-// 值全部按旧口径算——补 NULL 修不好，只能整列重算（UPDATE 全表 + 重建索引）。
-// 所以口径只能在这里改，且改要单独成批，不要混进别的改动里。
-//
-// 空内容（标题与正文归一后都为空）返回 null：这类写入没有可比内容，落 NULL 让它们
-// 不互相匹配成「全是重复」。
-//
-// 另有一处形状相近、口径不同的哈希：service.js 里镜像人工编辑的 digest 校验（两处）
-// 用 sha256(title\0content)，那里**不**归一化（要逐字节保真）。两把哈希用途不同，别互换。
-import { createHash } from "node:crypto";
-
-/**
- * 归一化一段文本用于内容比对（口径见文件头）。
- * @param {unknown} value
- * @returns {string}
- */
-export function normalizeForHash(value) {
-  return String(value ?? "")
-    .normalize("NFKC")
-    .toLowerCase()
-    .replace(/\p{P}/gu, "")
-    .replace(/\s+/g, " ")
-    .trim();
-}
-
-/**
- * 一行记忆的内容锚：标题与正文分别归一后用 NUL 拼接再取 sha256（十六进制全串）。
- * NUL 分隔是防拼接歧义——('ab','c') 与 ('a','bc') 不能落到同一个键上。
- * @param {{title?: string, content?: string}|null|undefined} memory
- * @returns {string|null} 归一后无内容时返回 null
- */
-export function contentHashOf(memory) {
-  const title = normalizeForHash(memory?.title);
-  const content = normalizeForHash(memory?.content);
-  if (!title && !content) return null;
-  return createHash("sha256").update(`${title}\u0000${content}`).digest("hex");
-}
+// #254 写入准入的确定性计量锚：内容归一化哈希（exact duplicate 判定）。
+//
+// 为什么用哈希而不是相似度：计量阶段要的是一个零成本、可复算、不留争议的判据。
+// 相似度阈值两边都是误判——同一件事换个说法就掉到线下，不同的事共享话题词又顶到
+// 线上，阈值往哪边挪都只是换一种错法（#254 拍板：计量信号用内容哈希）。哈希只认
+// 「归一化后逐字节相同」，算不出来就只有一种解释。
+//
+// 但它不等于「原文逐字节相同」：归一化会折掉格式，也会折掉标点，于是 `版本 3.5` 与
+// `版本 35`、`a-b` 与 `ab` 落同一个键。折叠范围（大小写 / 空白 / 标点）是口径本身
+// 定的，#254 已拍板——误报面在计量阶段可接受（只标记、不拦截），但「命中即精确重复」
+// 这句话别升级成「命中即内容相同」。要更窄的判据就得改归一化口径，而那要带存量重算。
+//
+// 归一化口径一次定死（NFKC → 小写 → 去标点 → 空白折叠 → trim），动机是让「只差
+// 格式」的两次写入落在同一个键上：全角/半角、大小写、行内换行与缩进、句末标点都
+// 不该让同一件事变成两条。反过来它不折叠同义词、不排序词序——那些只能靠相似度，
+// 而相似度已判定不可用于本信号。
+//
+// 改口径必须带存量重算策略：memories.content_hash 是派生列，口径一变，库里已有的
+// 值全部按旧口径算——补 NULL 修不好，只能整列重算（UPDATE 全表 + 重建索引）。
+// 所以口径只能在这里改，且改要单独成批，不要混进别的改动里。
+//
+// 空内容（标题与正文归一后都为空）返回 null：这类写入没有可比内容，落 NULL 让它们
+// 不互相匹配成「全是重复」。
+//
+// 另有一处形状相近、口径不同的哈希：service.js 里镜像人工编辑的 digest 校验（两处）
+// 用 sha256(title\0content)，那里**不**归一化（要逐字节保真）。两把哈希用途不同，别互换。
+import { createHash } from "node:crypto";
+
+/**
+ * 归一化一段文本用于内容比对（口径见文件头）。
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeForHash(value) {
+  return String(value ?? "")
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/\p{P}/gu, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * 一行记忆的内容锚：标题与正文分别归一后用 NUL 拼接再取 sha256（十六进制全串）。
+ * NUL 分隔是防拼接歧义——('ab','c') 与 ('a','bc') 不能落到同一个键上。
+ * @param {{title?: string, content?: string}|null|undefined} memory
+ * @returns {string|null} 归一后无内容时返回 null
+ */
+export function contentHashOf(memory) {
+  const title = normalizeForHash(memory?.title);
+  const content = normalizeForHash(memory?.content);
+  if (!title && !content) return null;
+  return createHash("sha256").update(`${title}\u0000${content}`).digest("hex");
+}

package/src/continuity.js

@@ -1,258 +1,258 @@
-import { createUserMessage } from "@deepseek-ai/dsh-llm";
-// Issue #611：图片块的文本口径（占位，不是空串），与 summarize.js 共用一份。
-import { contentToText } from "./attachment-text.js";
-
-// #249 N3（压缩边缘双落点）：上下文即将大幅精简前，抢救「正在做什么」。
-//
-// 为什么是这个形状（#249 §4.4 / §6.2 / §11；维护者 2026-09-24 拍板「都同意，开工」）：
-//
-// 1. **必须双落点**。宿主的压缩摘要器只看对话里的内容：压缩时宿主按固定字段模板
-//    重建对话，只放系统提示段的东西不进这次重建，等于白写。所以除了落库，还要把同
-//    一条连续性快照追加成靠近序列末尾的消息。DSH 没有 in-memory 消息改写钩子
-//    （§7 已核），因此这是「注入 + 序号引用寻址」，不是改写历史。
-// 2. **落库落成提案，不落成记忆行**。边缘产出直接进 memories，长会话会攒出第 N 条
-//    同主题条目（#275 记的失败形态）；转正通道与 #254 的二次确认共用一套、阶段二才
-//    打开，本批只写 pending 行。
-// 3. **全程不调模型**。三个字段是确定性抽取 + 截断（口径见 deriveContinuity），判定
-//    也只用本地字符串比较；门控成本为零。
-// 4. **触发器就是宿主真的压缩**，不自定一套阈值。宿主在 `agent/pre-step`（压力）与
-//    `agent/request-error`（溢出）两处触发压缩，我们只订阅压缩事件
-//    （`compaction/*` 一族，都在 @deepseek-ai/dsh-session 的事件白名单里
-//     `lib/types/known-event-types.js:31-34`）。自定阈值会与宿主口径漂移，还多一份没
-//    人校准的参数；「压缩边缘」本来就有宿主自己下的定义。
-//    **但发过压缩事件不等于这段历史真的被折叠了** —— 压缩插件在每一步都会试一次，
-//    失败时没有任何东西需要抢救。记账口径见 isCompactionEdge。
-//
-// 落点顺序（为什么 pre-step 里挂得住）：宿主的压缩插件在它自己的 pre-step 监听器里先
-// `await compactIfNeeded(...)` 再 `return next()`，所以我们的监听器拿到 `next()` 结果
-// 时压缩事件已经落库；而我们返回的 `decision.messages` 由宿主在本步末尾以
-// `surfaceOp: "append"` 追加（`@deepseek-ai/dsh-agent-loop/lib/index.js:1046`），晚于
-// 压缩的 `surfaceOp: "replace"`（`dsh-compaction-basic/lib/index.js:649`）——落点天然
-// 在压缩之后、靠近序列末尾。两条注册顺序都成立（谁先谁后，我们的 `await next()` 都在
-// 压缩工作之后返回）。
-
-/** 提案的 kind（唯一键的一半）：一次会话里"压缩边缘"这一类只留一条。 */
-export const CONTINUITY_KIND = "compaction-edge";
-/** 注入消息的统一前缀：机械校验与「不变不重复」判重都靠它（#249 §6.3）。 */
-export const CONTINUITY_NOTICE_PREFIX = "[dsh-mneme continuity]";
-/** 单字段字符上限：抽取是截断，不是摘要（改口径不需要动调用方）。 */
-export const CONTINUITY_FIELD_MAX = 200;
-/** 整条注入消息的字符上限。比 §6.3 的 160B 单行提醒宽：它是结构化快照，不是一句话提醒。 */
-export const CONTINUITY_NOTICE_MAX = 900;
-/** 边缘表的兜底上限：只留序号、且有界——压缩完就没有下一次 pre-step 的会话不走消费路径。 */
-const MAX_TRACKED_EDGES = 50;
-
-/**
- * 什么算「一个真的边缘」= 这段历史**真的被折叠了**。
- *
- * 这跟「有人发过压缩事件」不是同一个问题。压缩插件在**每一步**都会试一次压缩
- * （`agent/pre-step` 里的 `compactIfNeeded`），所以 `compaction/start` 只在说
- * 「有人试过」；尝试失败时没有任何东西需要抢救。按「试过就救」记账会得到一个
- * **每步都触发**的触发器 —— 实测（2026-10-14，本机两个长会话、12,000+ 事件，
- * 代理层把 dsh 原生压缩 100% 拒掉）：
- *
- *   · 按 `start|summary|end` 记账：1,287 次置位 / 359 次注入（4c28eaaa：2,895 / 625）
- *   · 按「真落地」记账：  39 次置位 /  32 次注入（4c28eaaa：  161 /  74）→ 降 91% / 88%
- *
- * 三种「真落地」：
- * - `compaction/summary`：宿主压缩成功才落（dsh-compaction-basic 的
- *   `commitCompactionBody`，与成功路同步提交；失败路不落）。
- * - `compaction/prune`：宿主把旧事件折叠出表面（dsh-compaction-tool-result-pruner），
- *   是「表面真的变短了」最直接的证据。
- * - `compaction/end`：**成败两条路都发**（同一份源码：失败路
- *   `append("compaction/end", { ...lifecycle, error: errorChain(error) })`），
- *   所以只有**不带 error** 的那条才算落地。
- */
-function isCompactionEdge(event) {
-  const type = event?.type;
-  if (type === "compaction/summary" || type === "compaction/prune") return true;
-  if (type !== "compaction/end") return false;
-  const error = event?.data?.error;
-  return error === undefined || error === null || error === "";
-}
-
-// 与 summarize.js 的 collectMessages 同一个口径：只取公开文本块，reasoning 私有推理
-// 不进快照（快照可能被宿主重建进摘要）。刻意副本而不是导出——那边是会话蒸馏的内部
-// 细节，两边取文本的理由不同。
-//
-// Issue #611：图片块不再返回空串，改走 attachment-text 的占位口径。快照的全部意义
-// 就是「压缩后还能看出刚才在干什么」，而一张没被记下的截图恰恰是最容易丢的那部分
-// 上下文——用户在等你看图，压缩后却只剩一句「看这个」，这种快照比没有更误导。
-function textOf(content) {
-  return contentToText(content);
-}
-
-// DSH 0.1.2-rc.1 起 Session 用 snapshotEvents()，兼容旧版 .events。这是**全量日志**
-// （append-only，含已被 surfaceOp:"replace" 折叠出表面的旧事件）——抽取要的正是全量：
-// 被压缩折叠掉的最后一条真实用户消息，也曾是"正在做什么"。
-function sessionEvents(session) {
-  let events = typeof session?.snapshotEvents === "function" ? session.snapshotEvents() : session?.events;
-  // 与 summarize.js 的同名兼容层同形：snapshotEvents 不可用或返回非数组时退回 .events。
-  if (!Array.isArray(events)) events = session?.events;
-  return Array.isArray(events) ? events : [];
-}
-
-// 「当前表面」= `session.surface.nodes`（只存活节点的 seq，事件体在上面那份日志里）。
-// 判重必须按表面而不是全量日志：旧注入还在日志里、但已被折叠出表面，照日志判重会让
-// 这一次压缩后该补的注入被静默跳过——双落点的 ② 就空了一次，而日志里看不出发生过。
-// 宿主没有表面投影（旧版）时退回全量：宁可少追加一次，也不在表面里重复追加同一份文本。
-function surfaceEvents(session) {
-  const events = sessionEvents(session);
-  let nodes;
-  // 宿主的 `surface.nodes` 是会抛的 getter（它自己用过、之后又被移除或替换的 message
-  // projection 会让宿主内部的 `_assertProjections` 抛）。判重是锦上添花的一步：读不到就
-  // 退回全量，别让一个可选的抢救功能因为读宿主状态失败而把 agent 的这一步变失败。
-  try {
-    nodes = session?.surface?.nodes;
-  } catch {
-    return events;
-  }
-  if (!Array.isArray(nodes)) return events;
-  const inSurface = new Set(nodes);
-  return events.filter((event) => inSurface.has(event?.seq));
-}
-
-/**
- * 抽取连续性三字段（纯函数、无 LLM、无副作用，供测试直接钉住口径）：
- * - `currentWork`：最近一条**真实** user/message（插件注入与子代理上报不算用户指令），
- *   取头部 CONTINUITY_FIELD_MAX 字符——"正在做什么"就是最后那条指令。
- * - `nextStep`：最近一条 assistant/message 的**尾部**同长度——"下一步"活在末尾那
- *   一段/最后一句里，取头会把开场白带进来。
- * - `openQuestions`：恒 null。确定性抽取判不出「哪些问题还没解决」，硬用反引号/问号
- *   猜会给出似是而非的字段；这个字段留给转正通道与人工补（不是所有字段都必须自动
- *   填满——宁可空着，也不编造）。空字段在注入文本里如实标 (none)。
- */
-export function deriveContinuity(session, fieldMax = CONTINUITY_FIELD_MAX) {
-  let currentWork = null;
-  let nextStep = null;
-  for (const event of sessionEvents(session)) {
-    const data = event?.data ?? {};
-    if (event?.type === "user/message") {
-      // 只认用户自己写的：source.kind 缺省（旧事件）或 "user"。插件消息（我们自己的
-      // 注入、其它插件）与子代理上报都不是"当前指令"。
-      const kind = data?.source?.kind;
-      if (kind !== undefined && kind !== "user") continue;
-      const text = textOf(data.content).trim();
-      if (text) currentWork = text.slice(0, fieldMax);
-    } else if (event?.type === "assistant/message") {
-      const text = textOf(data?.message?.content).trim();
-      if (text) nextStep = text.slice(-fieldMax);
-    }
-  }
-  return { currentWork, nextStep, openQuestions: null };
-}
-
-/** 单行化：字段里的换行会把「靠近末尾的一条消息」摊成多行，也破坏 §6.3 的单行约定。 */
-function oneLine(text) {
-  return typeof text === "string" ? text.replace(/\s*\n\s*/g, " ").trim() : "";
-}
-
-/** 渲染注入文本（纯函数）：统一前缀 + 三个固定字段（#249 §6.2）。 */
-export function renderContinuityNotice(fields, noticeMax = CONTINUITY_NOTICE_MAX) {
-  const body = [
-    `${CONTINUITY_NOTICE_PREFIX} Context compaction happened in this session; here is the continuity snapshot ` +
-      "recorded so it survives outside the transcript (a proposal — not yet in the memory store):",
-    `current_work: ${oneLine(fields?.currentWork) || "(none)"}`,
-    `next_step: ${oneLine(fields?.nextStep) || "(none)"}`,
-    `open_questions: ${oneLine(fields?.openQuestions) || "(none)"}`
-  ].join("\n");
-  return body.length > noticeMax ? body.slice(0, noticeMax) : body;
-}
-
-/** 表面上是否已经有同一条注入（「不变不重复」，#249 §6.5）：按前缀 + 全文比较，
- *  不做语义判定——没有改写钩子，能做的只有"同一份文本不追加第二次"。 */
-function noticeAlreadyInSurface(session, text) {
-  return surfaceEvents(session).some((event) => {
-    if (event?.type !== "user/message") return false;
-    if (event?.data?.source?.plugin !== "dsh-mneme") return false;
-    const content = textOf(event?.data?.content);
-    return content === text;
-  });
-}
-
-/**
- * 挂两条监听（#249 §7 的 `agent/pre-step` 触发位 + 压缩事件面），返回 { dispose }。
- *
- * `store` 直接注入：本模块只写提案表、不碰检索/嵌入，没有用到 service 的任何能力。
- * 调用方负责父／子开关（`autoInject` + `continuityRescueEnabled`），本函数另检查逐会话
- * 无痕闸门；保持"挂上就是开、命中会话就不处理"的单一口径。
- */
-export function createContinuityRescue(ctx, store, sessionGate = null) {
-  // 待处理的边缘：sessionId → 压缩事件序号。**真落地**的压缩事件到达时置位，下一次 pre-step 消费后
-  // 删除（同一个边缘绝不注入第二次）。只留序号、不留 Session：插件在宿主进程里只 apply
-  // 一次、服务所有会话，握着 Session 就是握着它的全量日志不放——压缩完就收工、不再有
-  // pre-step 是常见路径，这些条目永远走不到消费路径上。
-  const edge = new Map();
-
-  const unsubscribe = ctx.on("session/event", (session, event) => {
-    if (sessionGate?.isOff(session)) {
-      if (session?.id) edge.delete(session.id);
-      return;
-    }
-    if (!isCompactionEdge(event)) return;
-    if (!session?.id) return;
-    if (!edge.has(session.id) && edge.size >= MAX_TRACKED_EDGES) {
-      // 兜底淘汰最旧的（Map 是插入序）：这里漏掉最坏也只少一次注入，不会无界增长。
-      edge.delete(edge.keys().next().value);
-    }
-    // 同一轮可能出现多条落地事件（prune 与 end 并存），后到的覆盖前一个：留着最后一个，
-    // 序号即触发证据。
-    edge.set(session.id, typeof event.seq === "number" ? event.seq : null);
-  });
-
-  const offStep = ctx.on("agent/pre-step", async (payload, next) => {
-    const decision = await next();
-    // reject 是"这一步不该发生"，往里面塞消息没有意义；未知形状原样放行。
-    if (decision?.kind !== "enter") return decision;
-    const session = payload?.agent?.session;
-    if (sessionGate?.isOff(session)) {
-      if (session?.id) edge.delete(session.id);
-      return decision;
-    }
-    const sessionId = session?.id;
-    if (!sessionId) return decision;
-    if (!edge.has(sessionId)) return decision;
-    const edgeSeq = edge.get(sessionId);
-    edge.delete(sessionId);
-
-    // 抽取就地用 payload 上的这个 session（与置位时同一个 id），不从边缘表里握对象引用。
-    const fields = deriveContinuity(session);
-    // 落库先于注入：提案是"脱离对话独立存活"的那一半。写不进去不算宿主这一步的失败——
-    // 可选插件的可选能力把 agent 的一步带崩，比丢一次抢救严重得多（本函数的不变量）。
-    try {
-      const saved = store.saveContinuityProposal({
-        sessionId,
-        kind: CONTINUITY_KIND,
-        currentWork: fields.currentWork,
-        nextStep: fields.nextStep,
-        openQuestions: fields.openQuestions,
-        edgeSeq
-      });
-      // 弃新是"静默失效"的那一类：不报出来，运维与 §8 的触发率口径都会把它当成没触发。
-      if (saved?.dropped) {
-        ctx.logger?.warn?.(`[dsh-mneme] continuity: pending queue full, dropped the edge for session ${sessionId}`);
-      }
-    } catch (error) {
-      ctx.logger?.warn?.(`[dsh-mneme] continuity proposal not recorded: ${String(error)}`);
-    }
-
-    const text = renderContinuityNotice(fields);
-    if (noticeAlreadyInSurface(session, text)) return decision;
-    const messages = Array.isArray(decision.messages) ? decision.messages : [];
-    return {
-      ...decision,
-      messages: [
-        ...messages,
-        createUserMessage({ content: [{ type: "text", text }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } })
-      ]
-    };
-  });
-
-  return {
-    dispose() {
-      unsubscribe?.();
-      offStep?.();
-      edge.clear();
-    }
-  };
-}
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+// Issue #611：图片块的文本口径（占位，不是空串），与 summarize.js 共用一份。
+import { contentToText } from "./attachment-text.js";
+
+// #249 N3（压缩边缘双落点）：上下文即将大幅精简前，抢救「正在做什么」。
+//
+// 为什么是这个形状（#249 §4.4 / §6.2 / §11；维护者 2026-09-24 拍板「都同意，开工」）：
+//
+// 1. **必须双落点**。宿主的压缩摘要器只看对话里的内容：压缩时宿主按固定字段模板
+//    重建对话，只放系统提示段的东西不进这次重建，等于白写。所以除了落库，还要把同
+//    一条连续性快照追加成靠近序列末尾的消息。DSH 没有 in-memory 消息改写钩子
+//    （§7 已核），因此这是「注入 + 序号引用寻址」，不是改写历史。
+// 2. **落库落成提案，不落成记忆行**。边缘产出直接进 memories，长会话会攒出第 N 条
+//    同主题条目（#275 记的失败形态）；转正通道与 #254 的二次确认共用一套、阶段二才
+//    打开，本批只写 pending 行。
+// 3. **全程不调模型**。三个字段是确定性抽取 + 截断（口径见 deriveContinuity），判定
+//    也只用本地字符串比较；门控成本为零。
+// 4. **触发器就是宿主真的压缩**，不自定一套阈值。宿主在 `agent/pre-step`（压力）与
+//    `agent/request-error`（溢出）两处触发压缩，我们只订阅压缩事件
+//    （`compaction/*` 一族，都在 @deepseek-ai/dsh-session 的事件白名单里
+//     `lib/types/known-event-types.js:31-34`）。自定阈值会与宿主口径漂移，还多一份没
+//    人校准的参数；「压缩边缘」本来就有宿主自己下的定义。
+//    **但发过压缩事件不等于这段历史真的被折叠了** —— 压缩插件在每一步都会试一次，
+//    失败时没有任何东西需要抢救。记账口径见 isCompactionEdge。
+//
+// 落点顺序（为什么 pre-step 里挂得住）：宿主的压缩插件在它自己的 pre-step 监听器里先
+// `await compactIfNeeded(...)` 再 `return next()`，所以我们的监听器拿到 `next()` 结果
+// 时压缩事件已经落库；而我们返回的 `decision.messages` 由宿主在本步末尾以
+// `surfaceOp: "append"` 追加（`@deepseek-ai/dsh-agent-loop/lib/index.js:1046`），晚于
+// 压缩的 `surfaceOp: "replace"`（`dsh-compaction-basic/lib/index.js:649`）——落点天然
+// 在压缩之后、靠近序列末尾。两条注册顺序都成立（谁先谁后，我们的 `await next()` 都在
+// 压缩工作之后返回）。
+
+/** 提案的 kind（唯一键的一半）：一次会话里"压缩边缘"这一类只留一条。 */
+export const CONTINUITY_KIND = "compaction-edge";
+/** 注入消息的统一前缀：机械校验与「不变不重复」判重都靠它（#249 §6.3）。 */
+export const CONTINUITY_NOTICE_PREFIX = "[dsh-mneme continuity]";
+/** 单字段字符上限：抽取是截断，不是摘要（改口径不需要动调用方）。 */
+export const CONTINUITY_FIELD_MAX = 200;
+/** 整条注入消息的字符上限。比 §6.3 的 160B 单行提醒宽：它是结构化快照，不是一句话提醒。 */
+export const CONTINUITY_NOTICE_MAX = 900;
+/** 边缘表的兜底上限：只留序号、且有界——压缩完就没有下一次 pre-step 的会话不走消费路径。 */
+const MAX_TRACKED_EDGES = 50;
+
+/**
+ * 什么算「一个真的边缘」= 这段历史**真的被折叠了**。
+ *
+ * 这跟「有人发过压缩事件」不是同一个问题。压缩插件在**每一步**都会试一次压缩
+ * （`agent/pre-step` 里的 `compactIfNeeded`），所以 `compaction/start` 只在说
+ * 「有人试过」；尝试失败时没有任何东西需要抢救。按「试过就救」记账会得到一个
+ * **每步都触发**的触发器 —— 实测（2026-10-14，本机两个长会话、12,000+ 事件，
+ * 代理层把 dsh 原生压缩 100% 拒掉）：
+ *
+ *   · 按 `start|summary|end` 记账：1,287 次置位 / 359 次注入（4c28eaaa：2,895 / 625）
+ *   · 按「真落地」记账：  39 次置位 /  32 次注入（4c28eaaa：  161 /  74）→ 降 91% / 88%
+ *
+ * 三种「真落地」：
+ * - `compaction/summary`：宿主压缩成功才落（dsh-compaction-basic 的
+ *   `commitCompactionBody`，与成功路同步提交；失败路不落）。
+ * - `compaction/prune`：宿主把旧事件折叠出表面（dsh-compaction-tool-result-pruner），
+ *   是「表面真的变短了」最直接的证据。
+ * - `compaction/end`：**成败两条路都发**（同一份源码：失败路
+ *   `append("compaction/end", { ...lifecycle, error: errorChain(error) })`），
+ *   所以只有**不带 error** 的那条才算落地。
+ */
+function isCompactionEdge(event) {
+  const type = event?.type;
+  if (type === "compaction/summary" || type === "compaction/prune") return true;
+  if (type !== "compaction/end") return false;
+  const error = event?.data?.error;
+  return error === undefined || error === null || error === "";
+}
+
+// 与 summarize.js 的 collectMessages 同一个口径：只取公开文本块，reasoning 私有推理
+// 不进快照（快照可能被宿主重建进摘要）。刻意副本而不是导出——那边是会话蒸馏的内部
+// 细节，两边取文本的理由不同。
+//
+// Issue #611：图片块不再返回空串，改走 attachment-text 的占位口径。快照的全部意义
+// 就是「压缩后还能看出刚才在干什么」，而一张没被记下的截图恰恰是最容易丢的那部分
+// 上下文——用户在等你看图，压缩后却只剩一句「看这个」，这种快照比没有更误导。
+function textOf(content) {
+  return contentToText(content);
+}
+
+// DSH 0.1.2-rc.1 起 Session 用 snapshotEvents()，兼容旧版 .events。这是**全量日志**
+// （append-only，含已被 surfaceOp:"replace" 折叠出表面的旧事件）——抽取要的正是全量：
+// 被压缩折叠掉的最后一条真实用户消息，也曾是"正在做什么"。
+function sessionEvents(session) {
+  let events = typeof session?.snapshotEvents === "function" ? session.snapshotEvents() : session?.events;
+  // 与 summarize.js 的同名兼容层同形：snapshotEvents 不可用或返回非数组时退回 .events。
+  if (!Array.isArray(events)) events = session?.events;
+  return Array.isArray(events) ? events : [];
+}
+
+// 「当前表面」= `session.surface.nodes`（只存活节点的 seq，事件体在上面那份日志里）。
+// 判重必须按表面而不是全量日志：旧注入还在日志里、但已被折叠出表面，照日志判重会让
+// 这一次压缩后该补的注入被静默跳过——双落点的 ② 就空了一次，而日志里看不出发生过。
+// 宿主没有表面投影（旧版）时退回全量：宁可少追加一次，也不在表面里重复追加同一份文本。
+function surfaceEvents(session) {
+  const events = sessionEvents(session);
+  let nodes;
+  // 宿主的 `surface.nodes` 是会抛的 getter（它自己用过、之后又被移除或替换的 message
+  // projection 会让宿主内部的 `_assertProjections` 抛）。判重是锦上添花的一步：读不到就
+  // 退回全量，别让一个可选的抢救功能因为读宿主状态失败而把 agent 的这一步变失败。
+  try {
+    nodes = session?.surface?.nodes;
+  } catch {
+    return events;
+  }
+  if (!Array.isArray(nodes)) return events;
+  const inSurface = new Set(nodes);
+  return events.filter((event) => inSurface.has(event?.seq));
+}
+
+/**
+ * 抽取连续性三字段（纯函数、无 LLM、无副作用，供测试直接钉住口径）：
+ * - `currentWork`：最近一条**真实** user/message（插件注入与子代理上报不算用户指令），
+ *   取头部 CONTINUITY_FIELD_MAX 字符——"正在做什么"就是最后那条指令。
+ * - `nextStep`：最近一条 assistant/message 的**尾部**同长度——"下一步"活在末尾那
+ *   一段/最后一句里，取头会把开场白带进来。
+ * - `openQuestions`：恒 null。确定性抽取判不出「哪些问题还没解决」，硬用反引号/问号
+ *   猜会给出似是而非的字段；这个字段留给转正通道与人工补（不是所有字段都必须自动
+ *   填满——宁可空着，也不编造）。空字段在注入文本里如实标 (none)。
+ */
+export function deriveContinuity(session, fieldMax = CONTINUITY_FIELD_MAX) {
+  let currentWork = null;
+  let nextStep = null;
+  for (const event of sessionEvents(session)) {
+    const data = event?.data ?? {};
+    if (event?.type === "user/message") {
+      // 只认用户自己写的：source.kind 缺省（旧事件）或 "user"。插件消息（我们自己的
+      // 注入、其它插件）与子代理上报都不是"当前指令"。
+      const kind = data?.source?.kind;
+      if (kind !== undefined && kind !== "user") continue;
+      const text = textOf(data.content).trim();
+      if (text) currentWork = text.slice(0, fieldMax);
+    } else if (event?.type === "assistant/message") {
+      const text = textOf(data?.message?.content).trim();
+      if (text) nextStep = text.slice(-fieldMax);
+    }
+  }
+  return { currentWork, nextStep, openQuestions: null };
+}
+
+/** 单行化：字段里的换行会把「靠近末尾的一条消息」摊成多行，也破坏 §6.3 的单行约定。 */
+function oneLine(text) {
+  return typeof text === "string" ? text.replace(/\s*\n\s*/g, " ").trim() : "";
+}
+
+/** 渲染注入文本（纯函数）：统一前缀 + 三个固定字段（#249 §6.2）。 */
+export function renderContinuityNotice(fields, noticeMax = CONTINUITY_NOTICE_MAX) {
+  const body = [
+    `${CONTINUITY_NOTICE_PREFIX} Context compaction happened in this session; here is the continuity snapshot ` +
+      "recorded so it survives outside the transcript (a proposal — not yet in the memory store):",
+    `current_work: ${oneLine(fields?.currentWork) || "(none)"}`,
+    `next_step: ${oneLine(fields?.nextStep) || "(none)"}`,
+    `open_questions: ${oneLine(fields?.openQuestions) || "(none)"}`
+  ].join("\n");
+  return body.length > noticeMax ? body.slice(0, noticeMax) : body;
+}
+
+/** 表面上是否已经有同一条注入（「不变不重复」，#249 §6.5）：按前缀 + 全文比较，
+ *  不做语义判定——没有改写钩子，能做的只有"同一份文本不追加第二次"。 */
+function noticeAlreadyInSurface(session, text) {
+  return surfaceEvents(session).some((event) => {
+    if (event?.type !== "user/message") return false;
+    if (event?.data?.source?.plugin !== "dsh-mneme") return false;
+    const content = textOf(event?.data?.content);
+    return content === text;
+  });
+}
+
+/**
+ * 挂两条监听（#249 §7 的 `agent/pre-step` 触发位 + 压缩事件面），返回 { dispose }。
+ *
+ * `store` 直接注入：本模块只写提案表、不碰检索/嵌入，没有用到 service 的任何能力。
+ * 调用方负责父／子开关（`autoInject` + `continuityRescueEnabled`），本函数另检查逐会话
+ * 无痕闸门；保持"挂上就是开、命中会话就不处理"的单一口径。
+ */
+export function createContinuityRescue(ctx, store, sessionGate = null) {
+  // 待处理的边缘：sessionId → 压缩事件序号。**真落地**的压缩事件到达时置位，下一次 pre-step 消费后
+  // 删除（同一个边缘绝不注入第二次）。只留序号、不留 Session：插件在宿主进程里只 apply
+  // 一次、服务所有会话，握着 Session 就是握着它的全量日志不放——压缩完就收工、不再有
+  // pre-step 是常见路径，这些条目永远走不到消费路径上。
+  const edge = new Map();
+
+  const unsubscribe = ctx.on("session/event", (session, event) => {
+    if (sessionGate?.isOff(session)) {
+      if (session?.id) edge.delete(session.id);
+      return;
+    }
+    if (!isCompactionEdge(event)) return;
+    if (!session?.id) return;
+    if (!edge.has(session.id) && edge.size >= MAX_TRACKED_EDGES) {
+      // 兜底淘汰最旧的（Map 是插入序）：这里漏掉最坏也只少一次注入，不会无界增长。
+      edge.delete(edge.keys().next().value);
+    }
+    // 同一轮可能出现多条落地事件（prune 与 end 并存），后到的覆盖前一个：留着最后一个，
+    // 序号即触发证据。
+    edge.set(session.id, typeof event.seq === "number" ? event.seq : null);
+  });
+
+  const offStep = ctx.on("agent/pre-step", async (payload, next) => {
+    const decision = await next();
+    // reject 是"这一步不该发生"，往里面塞消息没有意义；未知形状原样放行。
+    if (decision?.kind !== "enter") return decision;
+    const session = payload?.agent?.session;
+    if (sessionGate?.isOff(session)) {
+      if (session?.id) edge.delete(session.id);
+      return decision;
+    }
+    const sessionId = session?.id;
+    if (!sessionId) return decision;
+    if (!edge.has(sessionId)) return decision;
+    const edgeSeq = edge.get(sessionId);
+    edge.delete(sessionId);
+
+    // 抽取就地用 payload 上的这个 session（与置位时同一个 id），不从边缘表里握对象引用。
+    const fields = deriveContinuity(session);
+    // 落库先于注入：提案是"脱离对话独立存活"的那一半。写不进去不算宿主这一步的失败——
+    // 可选插件的可选能力把 agent 的一步带崩，比丢一次抢救严重得多（本函数的不变量）。
+    try {
+      const saved = store.saveContinuityProposal({
+        sessionId,
+        kind: CONTINUITY_KIND,
+        currentWork: fields.currentWork,
+        nextStep: fields.nextStep,
+        openQuestions: fields.openQuestions,
+        edgeSeq
+      });
+      // 弃新是"静默失效"的那一类：不报出来，运维与 §8 的触发率口径都会把它当成没触发。
+      if (saved?.dropped) {
+        ctx.logger?.warn?.(`[dsh-mneme] continuity: pending queue full, dropped the edge for session ${sessionId}`);
+      }
+    } catch (error) {
+      ctx.logger?.warn?.(`[dsh-mneme] continuity proposal not recorded: ${String(error)}`);
+    }
+
+    const text = renderContinuityNotice(fields);
+    if (noticeAlreadyInSurface(session, text)) return decision;
+    const messages = Array.isArray(decision.messages) ? decision.messages : [];
+    return {
+      ...decision,
+      messages: [
+        ...messages,
+        createUserMessage({ content: [{ type: "text", text }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } })
+      ]
+    };
+  });
+
+  return {
+    dispose() {
+      unsubscribe?.();
+      offStep?.();
+      edge.clear();
+    }
+  };
+}