dsh-session-conductor 1.2.1 → 1.3.0

package/README.md

@@ -22,6 +22,7 @@
 | 模板注入 | 方案模板 / 收尾模板：本地设备上传 / 在线网址 / DSH 目录浏览三种导入，内容可再编辑，注入系统提示词（方案/收尾各一条上下文注入） | 设置 → 会话管理 → 模板注入 |
 | 自动重命名模型 | 指定便宜/专用模型做标题分析 | 设置 → 会话管理 |
 | 成员模型切换 | 给队友/子代理单独切模型（只动该成员会话，不影响其他成员）：先用 `list_models` 拿确切模型 id，再 `set_member_model` 按成员名/sessionId 切换（写 `model/selection` 事件交给官方投影接管，跨轮持久；未挂载成员也能切，运行中会先等它暂停） | AI 工具 `list_models` / `set_member_model` |
+| 记忆取回 | 检测到上下文用量**明显下降**（默认 ≥10%，可配）即判定「上下文疑似丢失」——压缩、截断、实例重启后快照未加载**都算**（比只盯压缩更全）。此时自动把最近 **3 轮（可配）** 的**用户原话 + 该轮 AI 的第一条回应**（优先取当时的 reasoning）重新注入，让 AI 立刻恢复状态。实现要点：按 zstd 帧**流式**读日志（常量内存）、**只认真实用户消息**（排除插件自身注入，防反馈环）、同回合连发**合并成一轮**、注入总长与单条都有上限。配置项 `retrieveMemory*`（默认开）。**另提供 AI 工具 `recall_memory`**（参数 `rounds` = 取几轮，默认取配置、上限 50）让 AI 自己按需回溯 | 每轮注入（`agent/pre-step`）+ AI 工具 `recall_memory` |
 | 上下文用量自查 | AI 按需查自己会话的上下文占用（百分比、已用/容量 tokens）与构成（系统提示词/工具定义/对话消息），占用达 85% 时附收敛建议。数据与界面圆环同源（官方 `contextPressure` / `contextBreakdown` 投影），只读、无参数。**另：每轮把实时用量注入消息尾部**（AI 每轮都能直接看到数字；注入在尾部而非系统提示词前缀 ⇒ 前缀稳定、prompt cache 仍命中；按 turn 门控，一回合只注一次；配置 `injectContextUsage` 可关） | AI 工具 `context_usage` + 每轮注入 |
 | 跨会话消息 | AI 直接给另一个会话发消息（不经过人转达）：先 `list_sessions` 挑目标，再 `send_to_session` 投递；目标空闲时**由本体自动唤醒**它跑一个回合，运行中则排到其下一回合边界（`mode:"steer"` 改为注入当前回合）。全部走本体官方 `prompt` API（幂等 `requestId`、不自己写会话日志）。**支持 `dryRun` 预览**（报告目标状态与限流余量，不投递、不消耗配额）。`list_sessions` 支持 **`query` 子串过滤 + `limit`/`offset` 分页**（默认只给 20 条，避免整表塞进调用方上下文）。硬约束：禁自投、协作链跳数 ≥3 拒绝、同一对会话 60s 内最多 5 条 | AI 工具 `list_sessions` / `send_to_session` |
 | 指定模型新建会话 | AI 新建会话并可**直接指定 provider/model**（建完即切到该模型），可选带一条初始消息让它立刻开始干活。**缺省工作目录 = 调用方会话自己的 cwd**（不落在 DSH 安装目录里）。本体 `create` 本身不带模型，所以是 `create` → `selectModel` 两步；任一步失败会如实回执（如「会话已建，但模型未设置」），不谎报成功。**支持 `dryRun` 预览**（含模型是否存在于目录的核对），不建会话 | AI 工具 `create_session` |

package/lib/apply.js

@@ -28,8 +28,10 @@ import {
   maybeScheduleContinue, runAutoContinueSession, runAutoScan, scheduleScan, AUTO_CONTINUE_SCAN_DELAY_MS,
 } from "./features/continue/scan.js";
 import { num } from "./shared/util.js";
-import { registerContextUsageTool, createContextUsageInjector } from "./features/context-usage/index.js";
+import { registerContextUsageTool, createContextUsageInjector, readContextUsage } from "./features/context-usage/index.js";
+import { buildMemoryRecall } from "./features/memory-recall/index.js";
 import { registerSessionMessagingTools } from "./features/session-messaging/index.js";
+import { registerMemoryRecallTool } from "./features/memory-recall/index.js";
 import { registerGroupRoutes } from "./group.js";
 import { saveTemplate, saveTemplateFromUrl, saveTemplateFromPath, listTemplateDir, removeTemplate, readTemplateSync, readCompletionConventionSync, collectTemplateSlotText, planGateAllows, planEnforceDenyMessage, TEMPLATE_DEFAULTS, TEMPLATE_SLOTS, TEMPLATE_MAX_BYTES, PLAN_ENFORCE_EDIT_TOOLS, PLAN_ENFORCE_BASH_WRITE_RE } from "./template-inject.js";
 import { name } from "./shared/constants.js";
@@ -1287,18 +1289,44 @@ export async function apply(ctx, config = {}) {
     //     多条重复的用量行（噪音 + 白烧 token）。
     //   · 默认开启（core/config.js 的 injectContextUsage）；关掉即退化为「按需调用 context_usage 工具」。
     //   · 读不到投影/服务未挂载时注入器返回空串 ⇒ 静默跳过，绝不影响正常回合。
-    const usageInjector = createContextUsageInjector({ enabled: cfg?.injectContextUsage !== false });
+    // 两个开关任一开启就需要本 hook（用量注入 / 记忆取回）；turn 门控保证一回合只注入一次。
+    const usageInjector = createContextUsageInjector({
+      enabled: cfg?.injectContextUsage !== false || cfg?.retrieveMemory !== false,
+    });
     ctx.on("agent/pre-step", async ({ agent, turn, signal }, next) => {
       const decision = await next();
       if (decision?.kind === "reject" || signal?.aborted) return decision;
       // 与模板注入同款守卫：工作区自测环境没有 @deepseek-ai/* 依赖，createUserMessage 会是 null
       if (typeof createUserMessage !== "function") return decision;
       if (!usageInjector.shouldInject(agent, turn)) return decision;
-      const usageText = usageInjector.textFor(ctx, agent);
-      if (!usageText) return decision;
+      const usageText = cfg?.injectContextUsage === false ? "" : usageInjector.textFor(ctx, agent);
+      // 记忆取回：本回合用量比上次明显下降 ⇒ 判定上下文疑似丢失，取回最近几轮消息文本 + AI 首条回应。
+      // 与用量注入**合并成同一条消息**（一回合只注入一条，避免叠加）；阈值/轮数/上限见 cfg。
+      let recallText = null;
+      if (cfg?.retrieveMemory !== false) {
+        try {
+          const snapshot = readContextUsage(ctx, agent);
+          recallText = await buildMemoryRecall(ctx, {
+            sessionKey: agent,
+            sessionId: agent?.session?.id,
+            current: snapshot?.ok ? snapshot.occupancy : null,
+            opts: {
+              rounds: cfg?.retrieveMemoryRounds,
+              minDropRatio: cfg?.retrieveMemoryMinDropRatio,
+              minDropTokens: cfg?.retrieveMemoryMinDropTokens,
+              maxTotalChars: cfg?.retrieveMemoryMaxChars,
+              maxCharsPerItem: cfg?.retrieveMemoryMaxCharsPerItem,
+            },
+          });
+        } catch (error) {
+          log(ctx, `记忆取回失败（跳过本次）: ${String(error?.message ?? error)}`);
+        }
+      }
+      const text = [usageText, recallText].filter(Boolean).join("\n\n");
+      if (!text) return decision;
       try {
         const injected = createUserMessage({
-          content: [{ type: "text", text: usageText }],
+          content: [{ type: "text", text }],
           source: { kind: "plugin:dsh-session-conductor", plugin: "dsh-session-conductor", form: "instructions" },
         });
         return { ...decision, messages: [...(decision.messages || []), injected] };
@@ -1394,6 +1422,14 @@ export async function apply(ctx, config = {}) {
     } catch (error) {
       log(ctx, `跨会话工具注册失败（不影响其它工具）: ${String(error?.message ?? error)}`);
     }
+    try {
+      // 记忆取回的手动通道：让 AI 自己按需回溯（自动注入之外的补充）
+      if (registerMemoryRecallTool(ctx, defineTool, tools)) {
+        log(ctx, "记忆取回工具已注册 (recall_memory)");
+      }
+    } catch (error) {
+      log(ctx, `记忆取回工具注册失败（不影响其它工具）: ${String(error?.message ?? error)}`);
+    }
     log(ctx, "成员模型工具已注册 (list_models / set_member_model)");
   });
 }

package/lib/core/config.js

@@ -24,6 +24,13 @@ export const DEFAULTS = {
   turnTimeoutMs: 20 * 60 * 1000, // 单回合续跑最长等待，超时取消
   scanIntervalMs: 5 * 60 * 1000, // 周期扫描间隔
   injectContextUsage: true, // 每轮把上下文用量注入消息尾部（默认开；关掉则只有 context_usage 工具按需查）
+  // ── 记忆取回（memory-recall）：检测到上下文疑似丢失时，把最近几轮的用户消息文本 + AI 首条回应重新注入 ──
+  retrieveMemory: true, // 总开关（默认开）
+  retrieveMemoryRounds: 3, // 取回最近几轮
+  retrieveMemoryMinDropRatio: 0.10, // 触发阈值：已用量下降比例（0.10 = 10%）
+  retrieveMemoryMinDropTokens: 0, // 触发阈值：下降绝对量（0 = 不限；两者满足其一即触发）
+  retrieveMemoryMaxChars: 4000, // 注入总长上限（字符）
+  retrieveMemoryMaxCharsPerItem: 800, // 单条（用户消息文本 / AI 首条回应）上限（字符）
 };
 
 /** 运行期配置（面板/测试可改）。外部只读引用；改整体请用 setConfig。 */

package/lib/features/memory-recall/index.js

@@ -0,0 +1,281 @@
+// dsh-session-conductor — 记忆取回（memory-recall）
+//
+// 【解决什么】DSH 上下文被压缩、或重启后快照尚未加载时，AI 会「失忆」：重复提问、
+// 重复劳动、误解需求。而用户消息文本在上下文里占比极小（1M 上下文里可能总共没超过 3 句），
+// 却恰恰是最不该丢的部分 —— 本模块把这些消息文本（连同 AI 当时的首个回应）重新注入。
+//
+// 【怎么判「失忆」】每回合比较上下文已用量：本次比上次**明显下降**（默认 ≥10%，可配）即判定。
+//   为什么不直接监测压缩：用量下降能覆盖所有「失去上下文」的形态 —— 压缩只是最常见一种；
+//   例如实例重启后快照未加载时用量会掉到 0，那同样该按失忆处理。
+//
+// 【取什么】最近 N 轮（默认 3）的**用户消息文本** + 该轮 **AI 的第一条回应**（优先 reasoning）。
+//   · 以用户消息为锚：消息文本占比小但信息密度最高，是恢复上下文的支点；
+//   · 要 AI 的第一条回应：那是「当时」对消息文本的理解，直接给出结论，省得 AI 重新推测。
+//   具体读取（按 zstd 帧流式、常量内存）在 sessions/events.js 的 readRecentUserTurns。
+//
+// 【怎么注入】走 apply.js 的 agent/pre-step + 官方 createUserMessage（logged 通道），
+//   放在消息**尾部**（前缀保持稳定 ⇒ prompt cache 仍命中），与每轮用量注入**合并成一条**。
+//
+// 【失败即静默】日志缺失/损坏、用量读不到、首回合无上次用量 —— 一律返回 null，绝不阻断回合。
+import { readRecentUserTurns } from "../../sessions/events.js";
+import { log } from "../../shared/log.js";
+import { cfg } from "../../core/config.js";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// ── 用量记忆的**持久化**（解决「重启后不触发」）──────────────────────────────
+// 只用内存 WeakMap 时实例一重启就清空 ⇒ 首个回合没有「上次用量」可比 ⇒
+// 而重启后用量恰好是 0（快照未加载）—— **最该触发的场景反而永不触发**。
+// 因此把每个会话的上次用量落盘（节流写），重启后读回来继续比较。
+const STATE_SUB = ["storages", "dsh-session-conductor"];
+const STATE_FILE = "recall-state.json";
+const STATE_WRITE_THROTTLE_MS = 30_000;
+let diskState = null; // { [sessionId]: { usedTokens, at } }
+let diskLoaded = false;
+let lastWriteAt = 0;
+let statePathOverride = null; // 测试注入：显式指定状态文件路径（不依赖 DSH_HOME 环境变量）
+
+/** 测试钩子：显式指定状态文件路径（传 null 恢复默认）。 */
+export function setStatePathForTest(path) {
+  statePathOverride = path ?? null;
+}
+
+/** 状态文件路径（随 DSH_HOME 走，不写死本机路径；拿不到 HOME 时返回空串 = 不落盘）。 */
+function stateFilePath() {
+  if (statePathOverride) return statePathOverride;
+  const home = process.env.DSH_HOME || (process.env.HOME ? join(process.env.HOME, ".dsh") : "");
+  return home ? join(home, ...STATE_SUB, STATE_FILE) : "";
+}
+
+/** 读落盘状态（进程内只读一次；任何异常都退化成空表，绝不向上抛）。 */
+function loadDiskState() {
+  if (diskLoaded) return diskState;
+  diskLoaded = true;
+  diskState = {};
+  const file = stateFilePath();
+  if (!file) return diskState;
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) diskState = parsed;
+  } catch {
+    // 首次运行 / 文件损坏：按空表继续
+  }
+  return diskState;
+}
+
+/** 节流落盘（每 STATE_WRITE_THROTTLE_MS 至多一次；失败只留痕，不影响回合）。 */
+function saveDiskStateThrottled(ctx) {
+  const now = Date.now();
+  if (now - lastWriteAt < STATE_WRITE_THROTTLE_MS) return;
+  lastWriteAt = now;
+  const file = stateFilePath();
+  if (!file) return;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(`${file}.tmp`, JSON.stringify(diskState), "utf8");
+    renameSync(`${file}.tmp`, file);
+  } catch (error) {
+    log(ctx, `记忆取回：用量状态落盘失败（不影响功能）: ${String(error?.message ?? error)}`);
+  }
+}
+
+/** 测试钩子：重置落盘状态缓存（配合把 DSH_HOME 指向临时目录用）。 */
+export function resetDiskStateForTest() {
+  diskState = null;
+  diskLoaded = false;
+  lastWriteAt = 0;
+}
+
+/** 每会话上一次的用量。WeakMap：键（会话/agent 对象）被回收即自动释放，不会泄漏。 */
+let lastUsageBySession = new WeakMap();
+
+/** 读取某会话上一次记录的用量（测试与诊断用）。 */
+export function takeLastUsage(key) {
+  return key ? lastUsageBySession.get(key) ?? null : null;
+}
+
+/** 记录本次用量（供下一回合比较）。 */
+export function noteUsage(key, usage) {
+  if (key && usage) lastUsageBySession.set(key, usage);
+}
+
+/** 测试钩子：清空用量记忆（WeakMap 无法逐项清，直接换新实例）。 */
+export function resetRecallStateForTest() {
+  lastUsageBySession = new WeakMap();
+}
+
+/**
+ * 判定「上下文疑似丢失」：本次已用量比上次明显下降。
+ *
+ * @param {{usedTokens:number, percent?:number}|null} prev 上次用量
+ * @param {{usedTokens:number, percent?:number}|null} current 本次用量
+ * @param {{minDropRatio?:number, minDropTokens?:number}} [opts] 阈值（默认比例 10%；绝对量 0=不限）
+ * @returns {{lost:boolean, prev:object|null, dropRatio:number, dropTokens:number, reason:string}}
+ *   `reason` 如实说明「为什么没触发」，便于诊断（也会写进注入文本的判定依据）
+ */
+export function detectContextLoss(prev, current, opts = {}) {
+  const minRatio = Number.isFinite(opts.minDropRatio) ? opts.minDropRatio : 0.10;
+  const minTokens = Number.isFinite(opts.minDropTokens) ? opts.minDropTokens : 0;
+  const base = { lost: false, prev: prev ?? null, dropRatio: 0, dropTokens: 0 };
+  if (!current || typeof current.usedTokens !== "number") return { ...base, reason: "本次用量不可用（投影未上报？）" };
+  if (!prev || typeof prev.usedTokens !== "number") return { ...base, prev: null, reason: "没有上次用量（首个回合）" };
+  const dropTokens = prev.usedTokens - current.usedTokens;
+  if (dropTokens <= 0) return { ...base, dropRatio: 0, dropTokens: 0, reason: "用量未下降" };
+  const dropRatio = prev.usedTokens > 0 ? dropTokens / prev.usedTokens : 0;
+  const hit = dropRatio >= minRatio || (minTokens > 0 && dropTokens >= minTokens);
+  return {
+    lost: hit,
+    prev,
+    dropRatio,
+    dropTokens,
+    reason: hit
+      ? `用量下降 ${(dropRatio * 100).toFixed(1)}%（达阈值 ${(minRatio * 100).toFixed(0)}%）`
+      : `用量下降 ${(dropRatio * 100).toFixed(1)}%，未达阈值 ${(minRatio * 100).toFixed(0)}%`,
+  };
+}
+
+/** 把毫秒时间戳格式化为 `MM-DD HH:mm`（取本地时区；无法解析时给空串）。 */
+function formatStamp(time) {
+  if (typeof time !== "number" || !Number.isFinite(time)) return "";
+  const d = new Date(time);
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+/**
+ * 组装注入文本：标题（说明为什么注入）+ 每轮「用户消息文本 / 你当时的第一反应」。
+ * 总长受 maxTotalChars 限制 —— 刚压缩完的上下文最不该再被塞满，超限的轮次从**最早**的丢弃。
+ *
+ * @param {Array<{time:number, userText:string, agentText:string}>} turns 按时间正序
+ * @param {{prevPercent?:number, currentPercent?:number, maxTotalChars?:number}} [opts]
+ * @returns {string} 注入文本；无可用轮次时返回空串
+ */
+export function formatRecallBlock(turns, opts = {}) {
+  const list = Array.isArray(turns) ? turns.filter((t) => t && t.userText) : [];
+  if (list.length === 0) return "";
+  const maxTotal = Number.isSafeInteger(opts.maxTotalChars) && opts.maxTotalChars > 0 ? opts.maxTotalChars : 4000;
+  const head = opts.manual
+    // 手动路径（AI 主动调用 recall_memory）：没有「检测」这回事，标题如实说「按请求取回」
+    ? `【记忆取回】按请求取回最近 ${list.length} 轮的消息文本与你的首个回应：`
+    : "【记忆取回】检测到上下文用量下降"
+      + (Number.isFinite(opts.prevPercent) && Number.isFinite(opts.currentPercent)
+        ? `（上次 ${opts.prevPercent}% → 本次 ${opts.currentPercent}%）`
+        : "")
+      + "，判断上下文可能已丢失（压缩，或实例重启后快照尚未加载）。"
+      + `以下是你最近 ${list.length} 轮的用户消息文本与你的首个回应，供你恢复上下文：`;
+
+  // 从最近的轮次往前拼，保证「最相关的留下」；最后再按时间正序输出
+  const kept = [];
+  let used = head.length;
+  for (let i = list.length - 1; i >= 0; i -= 1) {
+    const turn = list[i];
+    const stamp = formatStamp(turn.time);
+    const block = `\n\n— 第 ${i + 1} 轮${stamp ? `（${stamp}）` : ""} —\n用户消息：${turn.userText}`
+      + (turn.agentText ? `\n你（当时的第一反应）：${turn.agentText}` : "");
+    if (used + block.length > maxTotal && kept.length > 0) break;
+    kept.unshift(block);
+    used += block.length;
+  }
+  return head + kept.join("");
+}
+
+/**
+ * 主入口：检测 → 取回 → 组装。任何一步失败都返回 null（调用方据此跳过注入）。
+ *
+ * ⚠️ 无论是否触发，**都会记账**（`noteUsage`）：否则读取失败时会每个回合反复触发。
+ *
+ * @param {object} ctx 插件 context
+ * @param {object} args { sessionKey（会话/agent 对象，用作记忆键）, sessionId, current（本次用量）, opts }
+ * @returns {Promise<string|null>} 注入文本；不需要/拿不到时 null
+ */
+export async function buildMemoryRecall(ctx, { sessionKey, sessionId, current, opts = {} }) {
+  // 上次用量：优先内存（同进程最准），内存没有就读**落盘值** —— 重启后靠它才能比较出「掉到 0」。
+  const memory = takeLastUsage(sessionKey);
+  const disk = sessionId ? loadDiskState()[sessionId] : null;
+  const prev = memory ?? (disk && typeof disk.usedTokens === "number" ? disk : null);
+  noteUsage(sessionKey, current);
+  if (sessionId && current && typeof current.usedTokens === "number") {
+    loadDiskState()[sessionId] = { usedTokens: current.usedTokens, percent: current.percent, at: Date.now() };
+    saveDiskStateThrottled(ctx);
+  }
+  const verdict = detectContextLoss(prev, current, {
+    minDropRatio: opts.minDropRatio,
+    minDropTokens: opts.minDropTokens,
+  });
+  if (!verdict.lost) return null;
+  if (!sessionId) return null;
+  let turns = null;
+  try {
+    turns = await readRecentUserTurns(ctx, sessionId, {
+      rounds: opts.rounds,
+      maxCharsPerItem: opts.maxCharsPerItem,
+      root: opts.root,
+    });
+  } catch (error) {
+    log(ctx, `记忆取回：读会话日志失败（跳过本次注入）: ${String(error?.message ?? error)}`);
+    return null;
+  }
+  if (!turns || turns.length === 0) return null;
+  const text = formatRecallBlock(turns, {
+    prevPercent: verdict.prev?.percent,
+    currentPercent: current?.percent,
+    maxTotalChars: opts.maxTotalChars,
+  });
+  if (!text) return null;
+  log(ctx, `记忆取回：${verdict.reason} ⇒ 注入 ${turns.length} 轮（${text.length} 字符）`);
+  return text;
+}
+
+/** 工具输出形态（与其它工具一致：字符串 + text 渲染）。 */
+const TEXT_OUTPUT = {
+  schema: { type: "string" },
+  render(_args, value) {
+    return [{ type: "text", text: String(value) }];
+  },
+};
+
+/**
+ * 注册 `recall_memory` AI 工具：**让 AI 自己按需取回记忆**（自动注入之外的手动通道）。
+ *
+ * 用途：上下文被压缩后 AI 想主动回溯、或想翻更早的几轮时调用；参数 `rounds` = 取几轮
+ * （默认取配置 `retrieveMemoryRounds`，上限 50）。只读 —— 只返回文本给调用方，不改上下文。
+ *
+ * @returns {boolean} 是否成功注册
+ */
+export function registerMemoryRecallTool(ctx, defineTool, tools, deps = {}) {
+  if (typeof defineTool !== "function" || typeof tools?.register !== "function") return false;
+  const read = deps.readTurns ?? readRecentUserTurns;
+  const format = deps.format ?? formatRecallBlock;
+  const config = deps.cfg ?? cfg;
+  const maxRounds = 50;
+  tools.register(defineTool({
+    name: "recall_memory",
+    description:
+      "取回最近几轮的记忆：每轮的**用户消息文本** + 你当时的**首个回应**（优先取当时的 reasoning）。"
+      + "何时用：上下文被压缩/重启后想主动回溯，或想确认「用户最初是怎么说的」。"
+      + `参数 rounds = 取几轮（默认 ${config?.retrieveMemoryRounds ?? 3}，上限 ${maxRounds}）。`
+      + "只读：只把文本返回给你，不会自动改上下文。",
+    parameters: {
+      rounds: { type: "number", description: `取最近几轮（默认 ${config?.retrieveMemoryRounds ?? 3}，上限 ${maxRounds}）` },
+    },
+    output: TEXT_OUTPUT,
+    async execute(args, exec) {
+      const sessionId = exec?.agent?.session?.id;
+      if (!sessionId) return "拿不到当前会话 id，无法取回记忆。";
+      const asked = Number.isSafeInteger(args?.rounds) && args.rounds > 0 ? args.rounds : (config?.retrieveMemoryRounds ?? 3);
+      const rounds = Math.min(asked, maxRounds);
+      try {
+        const turns = await read(ctx, sessionId, {
+          rounds,
+          maxCharsPerItem: config?.retrieveMemoryMaxCharsPerItem,
+        });
+        if (!turns || turns.length === 0) return "没取到可用的记忆（日志缺失，或还没有用户消息）。";
+        const text = format(turns, { maxTotalChars: config?.retrieveMemoryMaxChars, manual: true });
+        return text || "没取到可用的记忆。";
+      } catch (error) {
+        return `取回记忆失败：${String(error?.message ?? error)}`;
+      }
+    },
+  }));
+  return true;
+}

package/lib/sessions/events.js

@@ -16,6 +16,13 @@
 // 宿主包**懒加载**：顶层 `import` 会让本文件在「工作区自测」环境直接解析失败
 // （仓库里踩过同类坑），而 events.js 是最需要被单测覆盖的模块之一（冷会话读法）。
 // 这里改成顶层 await import + 兜底：没有宿主依赖时退化为「不加闭合器」，其余逻辑照常可测。
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+
+import { streamDecodedFrames } from "../zstd-frames.js";
+import { findSessionLog } from "../session-log.js";
+
 let interruptedTurnClosers = null;
 try {
   const hostSession = await import("@deepseek-ai/dsh-session");
@@ -89,6 +96,8 @@ export async function sessionEventsOf(ctx, sessionId) {
  * 列表侧靠磁盘缓存（revision 命中即跳过）；不要为了「省内存」改成多次 read
  * （那只会变成 N 次全量解压，内存峰值不变、耗时变 O(n²)）。
  *
+ * 列表构建请优先用 `readColdSessionSummary`（按 zstd 帧流式读，常量内存）。
+ *
  * 读取失败**向上抛**（buildSessionList 用它带出 inspectError）；仅「无 open 能力」返回 null。
  * @returns {Promise<{events:Array, meta:object|null}|null>}
  */
@@ -106,3 +115,208 @@ export async function readColdSessionEvents(ctx, sessionId) {
   // 崩溃残留的开放回合补合成闭合器（与官方 cold-read 一致，列表中断判定需要）
   return { events: withInterruptedClosers(events), meta: handle?.header ?? null };
 }
+
+// ---------- 按 zstd 帧流式读（列表专用，常量内存）----------
+
+/** 会话日志根目录：`<DSH_HOME>/sessions`。 */
+function sessionsRootOf() {
+  const dshHome = process.env.DSH_HOME || join(process.env.HOME ?? "", ".dsh");
+  return join(dshHome, "sessions");
+}
+
+/**
+ * 由会话 id 定位其日志文件。布局：`<sessionsRoot>/<工作区编码目录>/<会话id>/session.v*.jsonl.zstd`。
+ * 只做两层 readdir（根目录下的工作区分组通常只有个位数），命中即返回。
+ * @returns {string|null} 日志文件绝对路径；找不到返回 null（调用方回退到 handle 读法）
+ */
+export function findSessionLogById(sessionId, root = sessionsRootOf()) {
+  if (!sessionId) return null;
+  try {
+    for (const group of readdirSync(root)) {
+      const dir = join(root, group, sessionId);
+      if (!existsSync(dir)) continue;
+      const file = findSessionLog(dir);
+      if (file) return file;
+    }
+  } catch {
+    // 根目录不可读 → 交给调用方回退
+  }
+  return null;
+}
+
+/**
+ * 冷会话「摘要读」：**直接按 zstd 帧读日志文件**，流式解压 + 逐行增量解析 ⇒ 常量内存。
+ *
+ * 【为什么需要它】宿主的 `handle.read()` 无法流式读（见文件头）：它每次都会把整份日志
+ * 解压成 events 数组，本机实测最大会话 49.2 MB 压缩 → **173.3 MB 解压**，再变成对象数组后
+ * 单会话峰值数百 MB；列表要遍历上百个冷会话 ⇒ 进程 OOM。
+ * 而列表真正需要的只有三个值，都能在「逐行流过」时用 O(1) 状态累加：
+ *   · title        —— 全日志**最后一条** `session/title`（`foldTitle` 是倒序找，等价）
+ *   · updatedAt    —— 全日志**最后一条**事件的 `time`（`lastEventTime` 只取末条）
+ *   · interruption —— 全日志**最后一个** `turn/end` 的 reason（`interruptionInfo` 倒序找）
+ * 因此：读压缩文件（≤ ~50 MB）→ 逐帧流式解压（`streamDecodedFrames`）→ 逐行 JSON.parse
+ * → 只更新上述标量 + 保留尾部若干条（供官方闭合器判定开放回合）→ 其余立即丢弃。
+ *
+ * @param {object} ctx 插件 context（本函数不用 ctx 的服务，保留是为了与其它读法同签名）
+ * @param {string} sessionId 会话 id
+ * @param {object} [opts] tailKeep（尾部保留条数，默认 2000）/ signal / root（测试用）
+ * @returns {Promise<{meta:object|null, events:Array, derived:object, scanned:number, frames:number}|null>}
+ *   返回 null 表示「文件没找到」——调用方应回退到 `readColdSessionEvents`
+ */
+export async function readColdSessionSummary(ctx, sessionId, opts = {}) {
+  const file = findSessionLogById(sessionId, opts.root ?? sessionsRootOf());
+  if (!file) return null;
+  const tailKeep = Number.isSafeInteger(opts.tailKeep) && opts.tailKeep >= 0 ? opts.tailKeep : 2000;
+  const buf = readFileSync(file); // 压缩态（最大 ~50 MB），不是解压态
+  const decoder = new StringDecoder("utf8");
+  let pending = "";
+  let meta = null;
+  let title;
+  let updatedAt;
+  let openTurn = false;
+  let lastSeq;
+  let lastTurnEnd = null;
+  let tail = [];
+  let scanned = 0;
+
+  const consumeLine = (line) => {
+    if (!line) return;
+    let event;
+    try { event = JSON.parse(line); } catch { return; } // 截断/损坏行跳过，不影响其余
+    if (event?.type === "session") { meta = meta ?? event; return; } // 首行是会话 header（含 cwd/createdAt）
+    scanned += 1;
+    if (event?.type === "session/title" && typeof event.data?.title === "string") title = event.data.title;
+    if (typeof event?.time === "number") updatedAt = event.time;
+    if (event?.type === "turn/end") { lastTurnEnd = event; openTurn = false; }
+    else if (event?.type === "turn/start") openTurn = true;
+    if (typeof event?.seq === "number") lastSeq = event.seq;
+    if (tailKeep > 0) {
+      tail.push(event);
+      if (tail.length > tailKeep) tail.splice(0, tail.length - tailKeep);
+    }
+  };
+
+  const stats = await streamDecodedFrames(buf, (chunk) => {
+    pending += decoder.write(chunk);
+    let idx;
+    while ((idx = pending.indexOf("\n")) >= 0) {
+      const line = pending.slice(0, idx);
+      pending = pending.slice(idx + 1);
+      consumeLine(line);
+    }
+  }, { signal: opts.signal });
+  pending += decoder.end();
+  consumeLine(pending);
+
+  return {
+    meta,
+    // 尾部 + 官方闭合器：列表沿用既有 interruptionInfo(events) 语义，行为不变
+    events: withInterruptedClosers(tail),
+    derived: { title, updatedAt, openTurn, lastSeq, lastTurnEnd },
+    scanned,
+    frames: stats.frames,
+  };
+}
+
+// ---------- 记忆取回：取最近 N 轮「用户消息文本 + AI 首条回应」----------
+
+/** 从 content 分块里取纯文本（跳过 reasoning 等非文本块）。 */
+function textPartsOf(content) {
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const part of content) {
+    if (typeof part?.text === "string" && part.text) parts.push(part.text);
+  }
+  return parts.join("\n");
+}
+
+/**
+ * 从 `assistant/message` 里取「该轮 AI 的第一条回应」文本。
+ * 优先 `reasoning`（当时的推理最能体现「我那时怎么理解你的话」），没有则取正文 `text`。
+ */
+function firstAgentTextOf(data) {
+  const content = data?.message?.content;
+  if (!Array.isArray(content)) return "";
+  const pick = (kind) => content.find((p) => p?.type === kind && typeof p.text === "string" && p.text)?.text ?? "";
+  return pick("reasoning") || pick("text") || "";
+}
+
+/** 截断到 maxChars（超出加省略号），并压缩连续空白行。 */
+function clipText(text, maxChars) {
+  const normalized = String(text ?? "").replace(/\n{3,}/g, "\n\n").trim();
+  if (maxChars > 0 && normalized.length > maxChars) return `${normalized.slice(0, maxChars)}…`;
+  return normalized;
+}
+
+/**
+ * 取最近 N 轮「用户消息文本 + 该轮 AI 的第一条回应」（**按 zstd 帧流式读，常量内存**）。
+ *
+ * 【锚点为什么是 user/message 而不是 agent/inbox/spliced】前者是「真正成为用户输入」的那条，
+ * 后者是同一句话的**投递副本**（实测同一句话会先出现在 spliced、后出现在 user/message），
+ * 用后者会把一轮数成两条。
+ * 【为什么只认 source.kind === "user"】插件自己注入的消息（`plugin:dsh-session-conductor`）
+ * 以及 runtime-context / user-approval / model-selection 都不是用户消息文本；若不排除，
+ * 「记忆取回」注入的块本身会被下一轮取回，形成越注越多的反馈环。
+ * 【连续多条用户消息算一轮】同一回合内（其间没有 turn/end）到达的多条用户消息合并成一条。
+ *
+ * @param {object} ctx 插件 context（本函数不取服务，保留同签名）
+ * @param {string} sessionId 会话 id
+ * @param {object} [opts] rounds（默认 3）/ maxCharsPerItem（默认 800）/ root（测试用）
+ * @returns {Promise<Array<{time:number, userText:string, agentText:string}>|null>} 按时间正序；null = 日志没找到
+ */
+export async function readRecentUserTurns(ctx, sessionId, opts = {}) {
+  const file = findSessionLogById(sessionId, opts.root ?? sessionsRootOf());
+  if (!file) return null;
+  const rounds = Number.isSafeInteger(opts.rounds) && opts.rounds > 0 ? opts.rounds : 3;
+  const perItem = Number.isSafeInteger(opts.maxCharsPerItem) && opts.maxCharsPerItem > 0 ? opts.maxCharsPerItem : 800;
+  const buf = readFileSync(file);
+  const decoder = new StringDecoder("utf8");
+  let pending = "";
+  const turns = [];
+  let current = null;
+
+  const consumeLine = (line) => {
+    if (!line) return;
+    let event;
+    try { event = JSON.parse(line); } catch { return; }
+    const type = event?.type;
+    if (type === "turn/end") {
+      // 回合结束：此后到来的用户消息算新的一轮
+      if (current) current.closed = true;
+      return;
+    }
+    if (type === "user/message") {
+      if (event?.data?.source?.kind !== "user") return; // 排除注入与运行期上下文
+      const text = clipText(textPartsOf(event?.data?.content), perItem);
+      if (!text) return;
+      if (current && !current.closed) {
+        // 同回合内的连续用户消息：合并（用空行分隔，保持消息文本可辨）
+        current.userText = current.userText ? `${current.userText}\n\n${text}` : text;
+        return;
+      }
+      current = { time: typeof event?.time === "number" ? event.time : null, userText: text, agentText: "", closed: false };
+      turns.push(current);
+      if (turns.length > rounds) turns.shift(); // 只留最近 rounds 轮（常量内存）
+      return;
+    }
+    if (type === "assistant/message") {
+      if (!current || current.agentText) return; // 只要该轮的第一条
+      const text = clipText(firstAgentTextOf(event?.data), perItem);
+      if (text) current.agentText = text;
+    }
+  };
+
+  await streamDecodedFrames(buf, (chunk) => {
+    pending += decoder.write(chunk);
+    let idx;
+    while ((idx = pending.indexOf("\n")) >= 0) {
+      const line = pending.slice(0, idx);
+      pending = pending.slice(idx + 1);
+      consumeLine(line);
+    }
+  });
+  pending += decoder.end();
+  consumeLine(pending);
+
+  return turns.map((t) => ({ time: t.time, userText: t.userText, agentText: t.agentText }));
+}

package/lib/sessions/list.js

@@ -8,7 +8,7 @@ import { log } from "../shared/log.js";
 import { cfg, DEFAULTS, autoRenameEnabled, effectiveAutoContinue } from "../core/config.js";
 import { pluginState } from "../core/domain.js";
 import { continueJobs } from "../core/state.js";
-import { sessionEventList, readColdSessionEvents } from "./events.js";
+import { sessionEventList, readColdSessionEvents, readColdSessionSummary } from "./events.js";
 import { hasOpenTurn, lastEventTime } from "./turn.js";
 import { interruptionInfo } from "./interruption.js";
 import { resolveSessionTitle, foldTitle, stripArchiveWsPrefix } from "../features/rename/title.js";
@@ -19,6 +19,23 @@ import {
 } from "./list-cache.js";
 import { isValidSessionId } from "./session-id.js";
 
+/**
+ * 开放回合兜底：摘要读只保留有界尾部，若「崩溃残留的开放回合」的 `turn/start` 落在尾部之外，
+ * 官方闭合器就不会出现 —— 此时合成一条 `turn/end`（reason.kind="interrupted"）再交给
+ * `interruptionInfo` 判定。这样中断的**结构与文案只在 interruption.js 维护一处**，
+ * 不在列表侧复制字面量（复制会漂移，也会被审计的注释规则拦下）。
+ *
+ * @returns {object|null} 与 interruptionInfo 同形的中断描述；非开放回合返回 null
+ */
+function openTurnInterruption(events, derived) {
+  if (!derived?.openTurn) return null;
+  const tail = Array.isArray(events) ? events : [];
+  return interruptionInfo([
+    ...tail,
+    { type: "turn/end", seq: derived.lastSeq, data: { reason: { kind: "interrupted" } } },
+  ]);
+}
+
 /**
  * 会话列表项 id 的唯一判据在 `./session-id.js`（零依赖叶子模块，便于单测直接覆盖）。
  * 本文件四处使用它：归档集合净化 / 补全守卫 / persistence.list 回退校验 / emit 兜底。
@@ -136,24 +153,39 @@ export async function buildSessionList(ctx, opts = {}) { // dsh-skip-func-length
       const batch = needInspect.slice(start, start + batchSize);
       const settled = await Promise.allSettled(batch.map(async (entry) => {
         let events = [];
+        let summaryDerived = null;
         let inspectError = null;
         let inspected = entry.meta;
         try {
-          // ⚠️ 0.1.6-alpha.1 起 persistence.inspect 已失效（返回空）→ 改用官方 handle 读法。
-          //    ⚠️ 这是**全量读**（宿主 API 的 read(offset,length) 只是内存切片，分块读不会省内存、
-          //    反而 N 次全量解压 ⇒ O(n²)）。所以内存控制的关键是**别重复解析**：
-          //    上面的 revision 命中判定 + 下面的落盘缓存就是为此存在。
-          const loaded = persistence?.open ? await readColdSessionEvents(ctx, entry.meta.id) : null;
-          events = loaded?.events ?? [];
-          if (loaded?.meta) inspected = loaded.meta;
+          // 优先「按 zstd 帧流式读」（readColdSessionSummary）：直接读日志文件、逐帧流式解压、
+          // 逐行增量解析 ⇒ 常量内存（实测大日志 heap 增量 ~24 MB、峰值 29 MB）。
+          // 对比：handle.read 每次都会把整份日志解压成 events 数组（同文件解压后 ~200 MB），
+          // 列表要遍历上百个冷会话 ⇒ 进程 OOM（线上实测 RSS 2.33 GB、/list >120s）。
+          const summary = await readColdSessionSummary(ctx, entry.meta.id);
+          if (summary) {
+            events = summary.events;
+            summaryDerived = summary.derived;
+            if (summary.meta) inspected = summary.meta;
+          } else if (persistence?.open) {
+            // 回退：日志文件没找到（布局/命名变化）时用官方 handle 读法，保证功能不退化
+            const loaded = await readColdSessionEvents(ctx, entry.meta.id);
+            events = loaded?.events ?? [];
+            if (loaded?.meta) inspected = loaded.meta;
+          }
         } catch (cause) {
           // 损坏/不可读的 artifact 以无标题呈现，不影响列表；错误信息带出便于诊断
           inspectError = cause instanceof Error ? cause.message : String(cause);
         }
         const derived = {
-          title: foldTitle(events) ?? null,
-          updatedAt: lastEventTime(events) ?? inspected.createdAt ?? entry.meta.createdAt,
-          interruption: interruptionInfo(events),
+          // 标题/时间由按帧读在流式过程中累加，与「全量读后 foldTitle/lastEventTime」等价
+          //（已用朴素全量计算对拍验证）；拿不到摘要时退回对尾部事件求值。
+          title: summaryDerived?.title ?? foldTitle(events) ?? null,
+          updatedAt: summaryDerived?.updatedAt ?? lastEventTime(events) ?? inspected.createdAt ?? entry.meta.createdAt,
+          // 中断：摘要读已把「尾部 + 官方闭合器」拼好喂给 interruptionInfo；
+          // 若尾部不足以覆盖开放回合（闭合器没出现），用累加出的 openTurn 兜底 ——
+          // 兜底同样**走 interruptionInfo**（合成一条 turn/end 交给它判定），
+          // 不在本文件复制中断文案（文案归 interruption.js 维护，避免两处漂移）。
+          interruption: interruptionInfo(events) ?? openTurnInterruption(events, summaryDerived),
           inspectError,
         };
         // 解析结果连同 revision 落盘：下次这条会话只要没被追加过就不再解析。

package/lib/zstd-frames.js

@@ -68,6 +68,41 @@ export async function decodeAllFrames(buf) {
   return Buffer.concat(parts).toString('utf8');
 }
 
+/**
+ * 多帧**流式**解码：逐帧解压，把每帧的解压分片**直接交给 onChunk**，不拼接、不驻留。
+ *
+ * 【为什么需要它】`decodeAllFrames` 会把所有帧的解压结果 `Buffer.concat` 成一个大字符串 ——
+ * 本机实测最大会话日志解压后 173 MB，逐帧拼接时内存峰值就是「整份文本 + 所有分片」；
+ * 若再 `JSON.parse` 成事件对象数组，峰值会到数百 MB（列表构建反复调用 ⇒ 进程 OOM）。
+ * 本函数把「解压」与「消费」解耦：调用方按分片增量处理（例如逐行 JSON.parse 后只留需要的字段），
+ * 内存峰值 = 单个分片 + 调用方自己的增量状态，与日志总大小无关。
+ *
+ * ⚠️ 仍必须**逐帧**喂给解压器：DSH 会话日志是多帧容器，整体流式解码会丢后续帧（见 decodeAllFrames 注释）。
+ *
+ * @param {Buffer} buf 整份（压缩的）日志文件内容
+ * @param {(chunk: Buffer) => void} onChunk 每个解压分片的消费者（同步；抛错会中止并向上传播）
+ * @param {{signal?: AbortSignal}} [opts]
+ * @returns {Promise<{frames:number, tornStart?:number}>} 帧数；`tornStart` 存在表示尾部有截断帧
+ */
+export async function streamDecodedFrames(buf, onChunk, opts = {}) {
+  if (typeof onChunk !== "function") throw new TypeError("streamDecodedFrames 需要 onChunk 回调");
+  const { frames, tornStart } = scanZstdFrames(buf);
+  for (const fr of frames) {
+    opts.signal?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+      const decompressor = createZstdDecompress();
+      decompressor.on("data", (chunk) => {
+        try { onChunk(chunk); } catch (error) { reject(error); }
+      });
+      decompressor.on("end", resolve);
+      decompressor.on("error", reject);
+      decompressor.write(buf.subarray(fr.start, fr.end));
+      decompressor.end();
+    });
+  }
+  return tornStart === undefined ? { frames: frames.length } : { frames: frames.length, tornStart };
+}
+
 /**
  * 校验第一帧是否恰好一行 header（DSH assertZstdHeaderFrame 语义）。
  * @returns {{ok:boolean, error?:string}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-session-conductor",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "DSH session management enhancement: archive/restore sessions, batch & conditional delete, AI auto-rename, interrupted-session auto-resume, release idle sessions, workspace grouping, undo last message, repair damaged session logs, value analysis, full-text search, per-member model switching (list_models / set_member_model), and plan/closing template injection (system-prompt + context).",
   "type": "module",
   "main": "lib/index.js",

package/skills/dsh-session-conductor-functions.md

@@ -188,10 +188,10 @@ whenToUse: 需要了解 dsh-session-conductor 某个功能怎么用/参数是什
 - **`create_session` 缺省工作目录 = 调用方会话自己的 cwd**（发起它的那个 AI 在哪干活，新会话就落在哪）。**不要**依赖本体默认：那是 DSH 安装目录（实测 `/volume1/@appstore/DeepSeekHarness-NAS`），新会话落在程序目录里对干活毫无意义。显式给 `cwd` 或 `workspaceId` 可覆盖（二者互斥）。
 - **dryRun（两个写操作工具都支持）**：只做校验与预览、**不产生任何副作用**。`create_session` 的 dryRun 还会**核对 provider/model 是否真在模型目录里**；`send_to_session` 的 dryRun 会**报告目标状态与限流余量**，且**不消耗限流配额**（可以先 dryRun 多次再真投）。dryRun 同样执行全部本地校验（自投/超长/跳数等照常被拒）。
 - **状态含义**（`list_sessions` 输出）：`running` = 正在跑回合；`idle` = 已挂载但空闲；`inactive` = 冷会话（未挂载，投递时会被唤醒）。缺 id 的脏条目会被跳过并如实标注（不会渲染成 `undefined`）。
-- **会话列表的内存边界（实测，别再踩）**：冷会话读日志走官方 `handle.read(0, undefined)`，**宿主 API 不能流式读** —— `read(offset, length)` 的 offset/length 只是**内存数组切片**，后端每次调用都会把整份日志读进来解压（`session-persistence-jsonl/src/storage.ts` 的 `readCurrent`）。实测单份日志 49.2 MB 压缩 → **173.3 MB 解压**（3.2~5.0×）。
-  - ⛔ **不要为了省内存改成分块读**：内存峰值不变（每次都全量物化），耗时变 O(n²)（曾导致 `/list` >120s 超时，已撤回）。
-  - ✅ 正确做法是**别重复解析**：靠列表磁盘缓存的 `revision` 命中跳过（1.2.0 修掉了「`list()` 返回快照却被当裸 header 用、`revision` 恒 null ⇒ 缓存永不生效」这个 bug）。
-  - 想把单会话内存压到 KB 级，只能绕过 handle：按 zstd 帧解码日志文件（多帧格式每帧可独立解压，`lib/zstd-frames.js` 已具备该能力）。
+- **会话列表的内存边界（实测，别再踩）**：宿主的 `handle.read(offset, length)` **不能流式读** —— offset/length 只是**内存数组切片**，后端每次调用都会把整份日志读进来解压（`session-persistence-jsonl/src/storage.ts` 的 `readCurrent`）。实测单份日志 49.2 MB 压缩 → **173.3 MB 解压**（3.2~5.0×）。
+  - ⛔ **不要为了省内存改成分块 read**：内存峰值不变（每次都全量物化），耗时变 O(n²)（曾导致 `/list` >120s 超时，已撤回）。
+  - ✅ **1.2.2 起的做法：绕开 handle，按 zstd 帧流式读日志文件** —— `lib/sessions/events.js` 的 `readColdSessionSummary()`：`findSessionLogById` 定位文件 → `streamDecodedFrames()`（`lib/zstd-frames.js`，逐帧解压、分片直接交给消费者不拼接）→ `StringDecoder` 增量切行 → 逐行 `JSON.parse`，只累加 `title`/`updatedAt`/`openTurn` 并保留有界尾部。**实测 heap 增量 24 MB、峰值 29 MB**（原路径数百 MB），且与「全量解码 + `lastEventTime`/`hasOpenTurn`/`interruptionInfo`」逐项对拍一致。
+  - 另靠列表磁盘缓存的 `revision` 命中跳过重复解析（1.2.0 修掉了「`list()` 返回快照却被当裸 header 用、`revision` 恒 null ⇒ 缓存永不生效」）。
 - **投递语义**：默认 `mode:"queue"` —— 目标空闲时**由本体自动唤醒**它跑一个回合；目标运行中则排到其下一回合边界。`mode:"steer"` 改为注入目标**正在跑**的那个回合。
 - **实现口径（重要）**：全部走本体官方 `sessionController` 的 `@Remote` 方法 —— `create` / `selectModel` / `prompt`。**不自己写会话日志**：inbox 家族只有 `agent/inbox/spliced` 落盘，其 fold 对非法 splice（id 重复、start 越界）**直接抛错**，自己写等于拿对方会话的完整性冒险。`prompt` 的受理流程会先 resume 目标会话，唤醒语义由本体保证；`requestId` 是幂等键（本体持久化在那条被接受的消息上），重试传同键不会重复投递。
 - **`create_session` 为什么是两步**：本体 `SessionCreateRequest` 只有 `workspaceId? / cwd? / sessionId? / agentPreset?`，**没有 model 字段**，所以必须 `create` → `selectModel`。任一步失败都如实回执（如「⚠️ 会话已建，但模型未设置」），**不谎报成功**。
@@ -227,6 +227,37 @@ whenToUse: 需要了解 dsh-session-conductor 某个功能怎么用/参数是什
 ### 节约模式（token-saving-mode）
 - 用户表达节约 token 意愿（"省点""节约"）时启用：直达答案不客套、结构优先、默认 ≤200 字或 10 行代码、禁冗余、复杂问题先结论后理由、高峰价格用户自己留意勿主动提醒。
 
+## 十三、记忆取回（memory-recall，1.3.0 起）
+
+**解决什么**：上下文被压缩、截断，或实例重启后快照未加载时，AI 会「失忆」——重复提问、重复劳动、
+误解需求。而用户消息在上下文里占比极小（1M 上下文可能总共没超过 3 句），却最不该丢。
+
+**两条通道**：
+
+| 通道 | 触发 | 参数 |
+|---|---|---|
+| **自动注入** | 每回合比较上下文已用量：本次比上次下降 ≥ `retrieveMemoryMinDropRatio`（默认 0.10）⇒ 判定「疑似丢失」，取回后与用量行**合并成一条**注入（消息尾部） | 无（走配置） |
+| **AI 工具 `recall_memory`** | AI 自己想回溯时主动调用 | `rounds` = 取几轮（默认取配置，上限 50） |
+
+**取什么**：最近 N 轮（默认 3）的**用户消息文本** + 该轮 **AI 的第一条回应**（优先 reasoning，缺失取正文）。
+
+- 以用户消息为锚：占比小但信息密度最高，是恢复上下文的支点；
+- 要 AI 的第一条回应：那是「当时」对消息的理解，直接给结论，省得重新推测。
+
+**实现要点（改这里前先读）**：
+
+- 读取走 `readRecentUserTurns`（`lib/sessions/events.js`）：按 zstd 帧**流式**读日志文件，
+  常量内存（实测 3 轮 27 ms / heap 6.1 MB）；
+- 锚点只认 `user/message` 且 `data.source.kind === "user"` —— **必须排除插件自身注入**
+  （`plugin:dsh-session-conductor`）与 `runtime-context`，否则注入块会被下一轮取回形成反馈环；
+- `agent/inbox/spliced` 是同一句话的投递副本，**忽略**（否则一轮会数成两条）；
+- 同回合内（其间无 `turn/end`）连续多条用户消息**合并成一轮**；
+- 无论是否触发都记账（`noteUsage`），否则读取失败会每回合反复触发；
+- 任何一步失败（日志缺失/损坏、用量读不到、首回合无上次用量）都静默返回 null，绝不阻断回合。
+
+**配置**：`retrieveMemory`（默认开）/ `retrieveMemoryRounds`(3) / `retrieveMemoryMinDropRatio`(0.10) /
+`retrieveMemoryMinDropTokens`(0) / `retrieveMemoryMaxChars`(4000) / `retrieveMemoryMaxCharsPerItem`(800)。
+
 ## 相关
 
 - dsh-session-conductor（使用手册，与本文档配套）