dsh-compact-relay 0.5.1 → 0.5.3

package/lib/dsh/favorite-scorer.js

@@ -0,0 +1,91 @@
+/**
+ * 推荐收藏 · 模型打分调用（0.5.3 P1-6）。
+ *
+ * 位置：`dsh/favorite-watch.js` 在助手消息落地后异步调这里，只判**最后一条**回复。
+ * 口径（2026-10-28 验证脚本 v3 定稿）：flash 档、关思考、temperature 0、只回 JSON 分数。
+ *
+ * 红线：这里只返回分数，**绝不写收藏**；失败一律返回 null（调用方按「不亮」处理，
+ * 不抛错、不重试——推荐只是锦上添花，不能因为模型抖动影响主流程）。
+ *
+ * 与摘要/交接的区别：那两个任务失败要让用户知道（有明确错误码）；推荐失败是静默降级，
+ * 所以不套 model-task 的重试/预算循环，只借 callStream 的超时与取消。
+ */
+import { buildFavoriteScoreSystemPrompt, buildFavoriteScoreUserText, parseFavoriteScore } from '../core/favorite-score.js';
+import { callStream } from './llm-call.js';
+import { routeOf } from './route.js';
+
+/** 打分输出极短，给 160 token 足够（提示词要求只回一个 JSON）。 */
+export const FAVORITE_SCORE_MAX_TOKENS = 160;
+
+/** 单条打分超时；超过就不亮（比主对话慢太多就失去「即时提示」的意义）。 */
+export const FAVORITE_SCORE_TIMEOUT_MS = 8_000;
+
+/**
+ * 从 BlockAssembler 里取纯文本（只拼 text block；忽略 reason/tool）。
+ * @param {object} assembler
+ * @returns {string}
+ */
+function textOfAssembler(assembler) {
+  if (assembler === null || typeof assembler !== 'object') return '';
+  const blocks = typeof assembler.blocks === 'function' ? assembler.blocks() : [];
+  if (!Array.isArray(blocks)) return '';
+  const parts = [];
+  for (const block of blocks) {
+    if (block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string') {
+      parts.push(block.text);
+    }
+  }
+  return parts.join('\n').trim();
+}
+
+/**
+ * 给一条助手回复打分（0-100）。任何失败返回 null（不亮），不抛错。
+ *
+ * @param {{ctx:object, engine:object, log?:object}} deps
+ * @param {{agent?:object, text?:string}} input
+ * @returns {Promise<{score:number, reason:string, provider:string, model:string}|null>}
+ */
+export async function scoreFavoriteMessage(deps, { agent, text } = {}) {
+  const body = typeof text === 'string' ? text.trim() : '';
+  if (body.length === 0) return null;
+  const session = agent !== null && typeof agent === 'object' ? agent.session : undefined;
+  if (session === undefined || session === null) return null;
+  const target = routeOf(deps.ctx, session, agent);
+  if (target === null) return null;
+
+  const options = {
+    provider: target.provider,
+    model: target.model,
+    reasoningEffort: 'off',
+    temperature: 0,
+    maxTokens: FAVORITE_SCORE_MAX_TOKENS,
+    messages: [
+      { role: 'system', content: [{ type: 'text', text: buildFavoriteScoreSystemPrompt() }] },
+      { role: 'user', content: [{ type: 'text', text: buildFavoriteScoreUserText(body) }] },
+    ],
+  };
+
+  let assembler;
+  try {
+    assembler = await callStream({
+      ctx: deps.ctx,
+      engine: deps.engine,
+      options,
+      timeoutMs: FAVORITE_SCORE_TIMEOUT_MS,
+      label: '推荐收藏打分',
+      retry: false,
+    });
+  } catch (error) {
+    deps.log?.warn?.(`推荐收藏打分失败（忽略，不亮）：${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+
+  const parsed = parseFavoriteScore(textOfAssembler(assembler));
+  if (parsed === null) {
+    deps.log?.warn?.('推荐收藏打分：模型输出解析失败（忽略，不亮）');
+    return null;
+  }
+  return { score: parsed.score, reason: parsed.reason, provider: target.provider, model: target.model };
+}
+
+export default scoreFavoriteMessage;

package/lib/dsh/favorite-watch.js

@@ -0,0 +1,201 @@
+/**
+ * 推荐收藏 · 事件钩子（0.5.3 P1-6）。
+ *
+ * 职责：监听 `session/event`，在**每轮最后一条助手回复**落地约 1.2s 后异步打分，
+ * 保存「建议点亮」投影（≤3 条 / 会话），由 readState 下发、客户端星标高亮。
+ *
+ * 三个约束（定稿）：
+ *   1. **只判最后一条**：助手消息可能分步到达（工具调用中间态），用去抖把同一轮的
+ *      多次 assistant/message 收成一次，只对最后一条打分；
+ *   2. **每回合最多一次**：同一会话同时只有一个打分在跑；
+ *   3. **红线：绝不收藏**。这里只写内存建议，不碰 `dcr-favorites` 文件。
+ *
+ * 失败静默降级（不亮），不重试、不阻塞事件处理。
+ */
+import { decideFavoriteSuggest, FAVORITE_SCORE_MIN_CHARS } from '../core/favorite-score.js';
+import { favoriteSeqsOf } from '../core/favorites.js';
+import { favoriteMapOf } from './favorites-file.js';
+import { scoreFavoriteMessage } from './favorite-scorer.js';
+
+/** 同一轮内多条助手消息的合并窗口：在这之后还没新消息才算「这一轮的最后一条」。 */
+const WATCH_DEBOUNCE_MS = 1_200;
+
+/** 每个会话最多保留几条建议（readState 帧预算）。 */
+export const FAVORITE_SUGGEST_MAX = 3;
+
+/**
+ * 从一个事件里抠助手消息纯文本。
+ * @param {object|undefined} event
+ * @returns {string}
+ */
+export function assistantTextOf(event) {
+  const data = event !== null && typeof event === 'object' ? event.data : undefined;
+  const message = data?.message;
+  const content = message?.content ?? data?.content;
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  const parts = [];
+  for (const block of content) {
+    if (block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string') {
+      parts.push(block.text);
+    }
+  }
+  return parts.join('\n');
+}
+
+/**
+ * @param {{ctx:object, engine:object, cfg:object, log?:object}} deps
+ */
+export function createFavoriteWatcher(deps) {
+  /** @type {Map<string, ReturnType<typeof setTimeout>>} sessionId → 去抖定时器 */
+  const timers = new Map();
+  /** @type {Set<string>} 正在打分的会话（每回合最多一次） */
+  const inflight = new Set();
+  /** @type {Map<string, object[]>} sessionId → 建议列表（新的在前） */
+  const suggestions = new Map();
+  /** @type {{refreshAll:Function}|null} */
+  let hub = null;
+
+  const favoriteConfig = () => {
+    const cfg = deps.cfg?.favorite;
+    return cfg !== null && typeof cfg === 'object' ? cfg : {};
+  };
+
+  /** 当前会话已收藏的 seq 集合（判断「已收藏的不再推荐」）。 */
+  const favoritedSeqsOf = (session) => {
+    try {
+      return favoriteSeqsOf(favoriteMapOf(deps.ctx, session), session.id);
+    } catch {
+      return [];
+    }
+  };
+
+  const pushSuggestion = (sessionId, item) => {
+    const list = suggestions.get(sessionId) ?? [];
+    const next = [item, ...list.filter((entry) => entry.seq !== item.seq)];
+    suggestions.set(sessionId, next.slice(0, FAVORITE_SUGGEST_MAX));
+    hub?.refreshAll?.();
+  };
+
+  const scoreLater = (session, event) => {
+    const sessionId = session?.id;
+    if (typeof sessionId !== 'string' || sessionId.length === 0) return;
+    const existing = timers.get(sessionId);
+    if (existing !== undefined) clearTimeout(existing);
+    const timer = setTimeout(() => {
+      timers.delete(sessionId);
+      void runScore(session, event);
+    }, WATCH_DEBOUNCE_MS);
+    if (typeof timer.unref === 'function') timer.unref();
+    timers.set(sessionId, timer);
+  };
+
+  const runScore = async (session, event) => {
+    const sessionId = session?.id;
+    if (typeof sessionId !== 'string' || sessionId.length === 0) return;
+    if (inflight.has(sessionId)) return;
+    const cfg = favoriteConfig();
+    if (cfg.enabled === false) return;
+
+    const text = assistantTextOf(event);
+    if ([...text.trim()].length < FAVORITE_SCORE_MIN_CHARS) return;
+    const seq = Number.isFinite(event?.seq) ? event.seq : null;
+    const messageId = typeof event?.data?.message?.id === 'string' ? event.data.message.id : null;
+    if (seq === null || messageId === null) return;
+    if (favoritedSeqsOf(session).includes(seq)) return; // 已收藏：不再推荐
+
+    const level = cfg.level;
+    const mustWords = cfg.mustWords;
+    const muteWords = cfg.muteWords;
+
+    // 先做不花钱的判定：太短/屏蔽词/必亮词都不需要模型。
+    const cheap = decideFavoriteSuggest({ text, score: null, level, mustWords, muteWords });
+    if (cheap.reason === 'mute-word' || cheap.reason === 'too-short') return;
+    if (cheap.reason === 'must-word') {
+      pushSuggestion(sessionId, {
+        seq,
+        messageId,
+        score: null,
+        reason: 'must-word',
+        matched: cheap.matched,
+        at: Date.now(),
+      });
+      return;
+    }
+
+    inflight.add(sessionId);
+    try {
+      const scored = await scoreFavoriteMessage(deps, { agent: { id: sessionId, session }, text });
+      if (scored === null) return; // 模型失败：不亮（fail closed）
+      const decision = decideFavoriteSuggest({
+        text,
+        score: scored.score,
+        level,
+        mustWords,
+        muteWords,
+      });
+      if (decision.suggest !== true) return;
+      pushSuggestion(sessionId, {
+        seq,
+        messageId,
+        score: decision.score,
+        reason: decision.reason,
+        matched: decision.matched,
+        at: Date.now(),
+      });
+    } finally {
+      inflight.delete(sessionId);
+    }
+  };
+
+  /**
+   * 会话事件入口。只关心助手消息；其它事件直接返回。
+   * @param {object} session
+   * @param {object} event
+   */
+  const onEvent = (session, event) => {
+    if (event === null || typeof event !== 'object') return;
+    if (event.type !== 'assistant/message') return;
+    scoreLater(session, event);
+  };
+
+  /**
+   * readState 用的建议投影（只下发 seq/messageId/分数/原因，守帧预算）。
+   * @param {string|null|undefined} sessionId
+   * @returns {{seq:number, messageId:string, score:number|null, reason:string, matched:string|null}[]}
+   */
+  const suggestionOf = (sessionId) => {
+    if (typeof sessionId !== 'string' || sessionId.length === 0) return [];
+    const list = suggestions.get(sessionId) ?? [];
+    return list.map((item) => ({
+      seq: item.seq,
+      messageId: item.messageId,
+      score: item.score,
+      reason: item.reason,
+      matched: item.matched,
+    }));
+  };
+
+  const setHub = (nextHub) => {
+    hub = nextHub ?? null;
+  };
+
+  const clear = (sessionId) => {
+    if (typeof sessionId === 'string' && sessionId.length > 0) {
+      suggestions.delete(sessionId);
+      return;
+    }
+    suggestions.clear();
+  };
+
+  const close = () => {
+    for (const timer of timers.values()) clearTimeout(timer);
+    timers.clear();
+    inflight.clear();
+    suggestions.clear();
+  };
+
+  return { onEvent, suggestionOf, setHub, clear, close };
+}
+
+export default createFavoriteWatcher;

package/lib/dsh/favorites-file.js

@@ -0,0 +1,349 @@
+/**
+ * 收藏的文件层 —— **一条交接链一个 JSONL**（照 dsh/ledger.js 的范式写）。
+ *
+ * 红线（与轻账本一致）：
+ *  - **不影响本体**：所有 IO 都 try/catch 吞掉，写失败只返回 {ok:false}；
+ *  - **损坏静默降级**：读侧跳过坏行，不让一行坏数据毁掉全部收藏；
+ *  - **有界**：超过 FAVORITE_MAX 时整文件重写保留最近 N 条（先写 tmp 再 rename）。
+ *
+ * 文件按「工作」分（一项工作 = 一条交接链；交接不换文件）：
+ * `$DSH_HOME/dcr-favorites/<工作名>-<根会话短id>.jsonl`。
+ * 链根 = 入站 relay 记录的 rootId → 老链的 header.parentSession → 自己。
+ * 交接产生新会话时 rootId 不变 → 天然同一个文件（转交不换文件、继承上一个）。
+ *
+ * 快照：每次压缩把「本段被压掉且被收藏」的消息原文追加到
+ * `$DSH_HOME/dcr-favorites/snapshots/<根会话短id>.md`——日志被清理后仍可读回。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { defaultDshHome } from '../core/config-schema.js';
+import { FAVORITE_MAX, applyFavoriteOps, countFavorites, favoriteSeqsOf } from '../core/favorites.js';
+import { legacyChainParentIdOf, relayInboundRecordOf } from './relay.js';
+import { sourceTitleOf } from './sessions.js';
+
+/** 收藏文件目录名（放 DSH_HOME 下，与 compact-relay.json 同级）。 */
+export const FAVORITES_DIRNAME = 'dcr-favorites';
+
+/** 压缩快照子目录。 */
+export const SNAPSHOT_DIRNAME = 'snapshots';
+
+/**
+ * 一条交接链的根会话 id（同步可算）。
+ * @param {object} session
+ * @returns {string|null}
+ */
+export function rootSessionIdOf(session) {
+  if (session === null || session === undefined) return null;
+  const inbound = relayInboundRecordOf(session);
+  if (inbound !== null && typeof inbound.rootId === 'string' && inbound.rootId.length > 0) return inbound.rootId;
+  const legacyParent = legacyChainParentIdOf(session);
+  if (legacyParent !== null) return legacyParent;
+  const id = session.id;
+  return typeof id === 'string' && id.length > 0 ? id : null;
+}
+
+function titleOf(ctx, session) {
+  try {
+    const title = sourceTitleOf(ctx, session);
+    if (typeof title === 'string' && title.trim().length > 0) return title.trim();
+  } catch {
+    /* 标题服务不可用就用兜底 */
+  }
+  return null;
+}
+
+/** 会话 id 的短形式：去掉 `session-` 前缀再取 8 位（否则所有文件都叫 `...-session-.jsonl`）。 */
+function shortIdOf(id) {
+  const text = typeof id === 'string' && id.length > 0 ? id : 'unknown';
+  return text.replace(/^session-/, '').slice(0, 8) || 'unknown';
+}
+
+/** 文件名安全化：去路径分隔符与控制字符，折叠空白，截断。 */
+function slugOf(text, max = 40) {
+  if (typeof text !== 'string' || text.length === 0) return 'session';
+  const cleaned = text
+    .replace(/[\\/:*?"<>|\u0000-\u001f]/gu, ' ')
+    .replace(/\s+/gu, ' ')
+    .trim();
+  if (cleaned.length === 0) return 'session';
+  return cleaned.length > max ? cleaned.slice(0, max) : cleaned;
+}
+
+/** 目录：`$DSH_HOME/dcr-favorites`（缺省 ~/.dsh）。 */
+export function favoritesDirOf(dshHome = defaultDshHome()) {
+  return path.join(dshHome, FAVORITES_DIRNAME);
+}
+
+/**
+ * 新规范文件名：`<根会话短id>.jsonl`——**只按链根定位，不含标题**。
+ * （旧命名带「工作名」，标题一改就换文件；无活会话时也拿不到标题。）
+ */
+export function canonicalFavoritesFileOf(rootId, dshHome = defaultDshHome()) {
+  return path.join(favoritesDirOf(dshHome), `${shortIdOf(rootId)}.jsonl`);
+}
+
+/** 旧文件名（0.5.x 及之前）：`<工作名>-<根会话短id>.jsonl`；返回全部匹配（升序）。 */
+export function legacyFavoritesFilesOf(rootId, dshHome = defaultDshHome()) {
+  const dir = favoritesDirOf(dshHome);
+  const suffix = `-${shortIdOf(rootId)}.jsonl`;
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((name) => name.endsWith(suffix))
+      .sort()
+      .map((name) => path.join(dir, name));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 读/写用的收藏文件：新名优先；只有旧名就用旧名（**不迁移、不拆文件**）。
+ * @param {string} rootId 链根会话 id
+ * @param {string} [dshHome]
+ * @returns {string}
+ */
+export function favoritesFileForRoot(rootId, dshHome = defaultDshHome()) {
+  const canonical = canonicalFavoritesFileOf(rootId, dshHome);
+  if (fs.existsSync(canonical)) return canonical;
+  const legacy = legacyFavoritesFilesOf(rootId, dshHome);
+  return legacy.length > 0 ? legacy[legacy.length - 1] : canonical;
+}
+
+/**
+ * 无活会话时按会话 id 解析链根：`workspaceRegistry.readSessionHeader(id)` 沿 parentSession 往上游。
+ *
+ * 宿主实证（0.2.1 app.asar `dsh-workspace/lib/index.js`）：registry 公开
+ * `readSessionHeader(id)`，对**没有活 agent 的已存会话**也能读（走 sessionPersistence 索引）；
+ * header 里 `parentSession` 是 fork/交接来源。读不到就退回 sessionId 本身（不猜、不抛）。
+ * @param {object} ctx
+ * @param {string} sessionId
+ * @returns {Promise<string|null>}
+ */
+export async function rootSessionIdOfId(ctx, sessionId) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return null;
+  let current = sessionId;
+  const seen = new Set();
+  try {
+    const registry = ctx?.get?.('workspaceRegistry');
+    if (registry === null || registry === undefined || typeof registry.readSessionHeader !== 'function') return current;
+    for (let depth = 0; depth < 64; depth += 1) {
+      if (seen.has(current)) return current;
+      seen.add(current);
+      const header = await registry.readSessionHeader(current);
+      const parent =
+        header !== null && typeof header === 'object' && typeof header.parentSession === 'string' && header.parentSession.length > 0
+          ? header.parentSession
+          : null;
+      if (parent === null) return current;
+      current = parent;
+    }
+  } catch {
+    return current;
+  }
+  return current;
+}
+
+/**
+ * 某会话所属交接链的收藏文件路径。
+ * @param {object} ctx
+ * @param {object} session
+ * @param {string} [dshHome]
+ * @returns {string}
+ */
+export function favoritesFileOf(ctx, session, dshHome = defaultDshHome()) {
+  const rootId = rootSessionIdOf(session);
+  if (rootId !== null) return favoritesFileForRoot(rootId, dshHome);
+  const title = slugOf(titleOf(ctx, session) ?? 'session');
+  return path.join(favoritesDirOf(dshHome), `${title}-unknown.jsonl`);
+}
+
+/**
+ * 读文件里的全部记录（只做 JSON.parse，坏行由 core 的 normalize 过滤）。
+ * @param {string} file
+ * @returns {object[]}
+ */
+export function readFavoritesFile(file) {
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    const records = [];
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) continue;
+      try {
+        records.push(JSON.parse(trimmed));
+      } catch {
+        continue;
+      }
+    }
+    return records;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 追加一条收藏记录；超过上限时重写保留最近 FAVORITE_MAX 条。永不抛。
+ * @param {object} record normalizeFavoriteRecord 的产物
+ * @param {string} file
+ * @returns {{ok:boolean}}
+ */
+export function appendFavoriteRecord(record, file) {
+  try {
+    if (record === null || typeof record !== 'object') return { ok: false };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(record)}\n`, 'utf8');
+    const lines = fs.readFileSync(file, 'utf8').split('\n').filter((line) => line.trim().length > 0);
+    if (lines.length > FAVORITE_MAX * 2) {
+      const kept = lines.slice(-FAVORITE_MAX).join('\n');
+      const tmp = `${file}.tmp`;
+      fs.writeFileSync(tmp, `${kept}\n`, 'utf8');
+      fs.renameSync(tmp, file);
+    }
+    return { ok: true };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * 某会话所在交接链的收藏集合。
+ * @param {object} ctx
+ * @param {object} session
+ * @param {string} [dshHome]
+ * @returns {Map<string, Set<number>>}
+ */
+export function favoriteMapOf(ctx, session, dshHome = defaultDshHome()) {
+  if (ctx === undefined || session === null || session === undefined) return new Map();
+  return applyFavoriteOps(readFavoritesFile(favoritesFileOf(ctx, session, dshHome)));
+}
+
+/**
+ * 按链根 id 读收藏集合（无活会话的标记路径用；不依赖 session 对象）。
+ * @param {string} rootId
+ * @param {string} [dshHome]
+ * @returns {Map<string, Set<number>>}
+ */
+export function favoriteMapForRoot(rootId, dshHome = defaultDshHome()) {
+  if (typeof rootId !== 'string' || rootId.length === 0) return new Map();
+  return applyFavoriteOps(readFavoritesFile(favoritesFileForRoot(rootId, dshHome)));
+}
+
+/**
+ * readState 用的收藏投影：当前会话的 seq + messageId（只下发数字/短串，守 32KB 帧）。
+ * @param {object} ctx
+ * @param {object|null|undefined} session
+ * @param {{max?:number}} [options]
+ */
+export function favoriteStateOf(ctx, session, { max = 200 } = {}) {
+  if (ctx === undefined || session === null || session === undefined) {
+    return { count: 0, seqs: [], messageIds: [], truncated: false };
+  }
+  const map = favoriteMapOf(ctx, session);
+  const seqs = favoriteSeqsOf(map, session.id);
+  const cap = Number.isInteger(max) && max > 0 ? max : 200;
+  const messageIds = [];
+  const wanted = new Set(seqs.slice(-100));
+  const log = Array.isArray(session.log) ? session.log : [];
+  for (const event of log) {
+    if (wanted.size === 0) break;
+    const seq = event !== null && typeof event === 'object' ? event.seq : undefined;
+    if (!wanted.has(seq)) continue;
+    const id = event.type === 'assistant/message' ? event.data?.message?.id : event.data?.id;
+    if (typeof id === 'string' && id.length > 0) {
+      messageIds.push(id);
+      wanted.delete(seq);
+    }
+  }
+  return {
+    count: seqs.length,
+    seqs: seqs.slice(-cap),
+    messageIds,
+    truncated: seqs.length > cap,
+  };
+}
+
+/** 链总数（列表头部用）。 */
+export function chainFavoriteTotal(ctx, session, dshHome = defaultDshHome()) {
+  return countFavorites(favoriteMapOf(ctx, session, dshHome));
+}
+
+/** 快照文件：`dcr-favorites/snapshots/<根会话短id>.md`。 */
+export function snapshotFileOf(ctx, session, dshHome = defaultDshHome()) {
+  const rootId = rootSessionIdOf(session) ?? 'unknown';
+  return path.join(favoritesDirOf(dshHome), SNAPSHOT_DIRNAME, `${shortIdOf(rootId)}.md`);
+}
+
+const SNAPSHOT_MARKER = (seq) => `<!-- dcr-fav seq:${seq} -->`;
+
+/**
+ * 把一批收藏原文追加进快照（按 seq 去重；已存在同 seq 标记则跳过）。永不抛。
+ * @param {string} file
+ * @param {{seq:number, role:string, title:string, text:string, at?:number}[]} entries
+ * @returns {{ok:boolean, written:number}}
+ */
+export function appendSnapshotEntries(file, entries) {
+  try {
+    if (!Array.isArray(entries) || entries.length === 0) return { ok: true, written: 0 };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    let existing = '';
+    try {
+      existing = fs.readFileSync(file, 'utf8');
+    } catch {
+      existing = '';
+    }
+    const parts = [];
+    let written = 0;
+    for (const entry of entries) {
+      if (existing.includes(SNAPSHOT_MARKER(entry.seq))) continue;
+      const iso = new Date(Number.isFinite(entry.at) ? entry.at : Date.now()).toISOString();
+      parts.push(
+        `${SNAPSHOT_MARKER(entry.seq)}\n#### 收藏 · seq ${entry.seq} · ${entry.role} · ${iso}\n\n- 标题：${entry.title}\n\n${entry.text}\n\n---\n`,
+      );
+      written += 1;
+    }
+    if (written === 0) return { ok: true, written: 0 };
+    const header =
+      existing.length === 0
+        ? '# 收藏快照\n\n> 每次压缩把「本段被压掉、且被收藏」的消息原文落到这里；原件日志被清理后仍可读回。\n\n'
+        : '';
+    fs.appendFileSync(file, header + parts.join('\n'), 'utf8');
+    return { ok: true, written };
+  } catch {
+    return { ok: false, written: 0 };
+  }
+}
+
+/**
+ * 从快照里取某条 seq 的原文（没有返回 null）。
+ * @param {string} file
+ * @param {number} seq
+ * @returns {string|null}
+ */
+export function snapshotTextFor(file, seq) {
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    const marker = SNAPSHOT_MARKER(seq);
+    const start = text.indexOf(marker);
+    if (start === -1) return null;
+    const rest = text.slice(start + marker.length);
+    // 去掉本段头（#### 行 + 标题行 + 空行），截到下一个标记或结尾
+    const nextMarker = rest.indexOf('<!-- dcr-fav seq:');
+    const body = nextMarker === -1 ? rest : rest.slice(0, nextMarker);
+    const lines = body.split('\n');
+    const content = [];
+    let skipping = true;
+    for (const line of lines) {
+      if (skipping) {
+        if (line.startsWith('####') || line.startsWith('- 标题：') || line.trim().length === 0) continue;
+        skipping = false;
+      }
+      if (line.trim() === '---') break;
+      content.push(line);
+    }
+    const joined = content.join('\n').trim();
+    return joined.length > 0 ? joined : null;
+  } catch {
+    return null;
+  }
+}

package/lib/dsh/handoff-writer.js

@@ -49,7 +49,7 @@ export async function generateHandoffDoc({ ctx, engine, agent, maxTokens, inputT
   const prefix = surfaceMessages(session);
   if (prefix.length === 0) throw actionError('handoff', '这个会话还没有可交接的内容（没有模型可见的消息）');
 
-  // 同摘要器：不继承 reasoningEffort（max 思考会把输出上限吃光）；是否传 off 由模型能力决定。
+  // reasoningEffort 由 prepareModelCall 决定：优先沿用主请求档位（cache 对齐）；拿不到 header 才回退「支持 off 就 off」。
   const controls = cacheAlignedControls(session, target);
   let lastProblems = [];