dsh-compact-relay 0.0.0-stage → 0.3.2

package/TUTORIAL.md

@@ -0,0 +1,65 @@
+# 压缩接力 · 3 分钟教程
+
+给 DeepSeek Harness 输入框加一个**上下文指示灯**：告诉你现在还剩多少容量、什么时候该压缩旧会话、什么时候该交接新会话，并帮你把重要消息锁住。
+
+> 这个文件预留给 GitHub 教程页；建好仓库后，设置页「帮助」区的「使用教程」会直接链到这里。
+
+## 1. 先看环怎么读
+
+指示灯在输入框底部工具行（「完全权限」右侧），外环是容量进度，内圆是交接信号：
+
+| 区域/颜色 | 意思 | 你该做什么 |
+|---|---|---|
+| 灰（默认色） | 正常区还没走满（没到第一个断点） | 继续聊 |
+| 蓝（填满色） | 正常区走满了（到了断点1） | 这里是「该压缩」的位置 |
+| 琥珀（调整色） | 压缩区（断点1 → 交接线） | 点指示灯 →「压缩旧会话」，或输入 `/bc` |
+| 红（上限色 / 内圆红点） | 交接区（交接线之后），或摘要太多 | 点指示灯 →「交接新会话」，或输入 `/handoff` |
+| 警示红（原生线） | 80% 处的 DSH 原生自动压缩线（紫色径向刻度）；越过 80% 后整环红色闪烁 | 再往前 DSH 会自己压历史，先压缩或交接 |
+| 品红（锁定色） | 这里锁了一条重要消息（按它在对话里的位置显示，可多个） | 知道「我锁的东西在哪」 |
+
+**断点**（环上的小缺口）=「我判断这里适合压缩」的位置：模型判断（上下文超过最小压缩线、还没到压缩线、正到自然节点）或到压缩线时自动出现；压缩后环变短，断点自然消失。
+
+把鼠标放到指示灯上，会显示具体数字：`会话容量已用 xx.x%（xxxK / 1.00M），已压缩 n 次｜建议压缩 / 建议交接 / 正常｜压缩判断点 x%｜原生自动压缩线 80%｜已锁定 n 条`。
+
+**第一次用**会看到一条提示：点指示灯能压缩旧会话、**锁定重要消息**、交接新会话；会顺带告诉你 DSH 原生自动压缩线是多少，以及环上的小缺口什么意思。重要的结论/路径先锁定，压缩时才不会被压掉。
+
+这条引导只自动出现一次。想再看：**设置 → 压缩接力 → 帮助 →「再看一次初次引导」**，点完关掉设置页就会重新播放（手动重播时长更长：光晕 9 秒 / 提示 20 秒）。
+
+## 2. 记住三条命令
+
+| 命令 | 作用 |
+|---|---|
+| `/bc` | 压缩旧会话：**先看压缩预估**（压哪段、多少条、多少容量），再 `/bc confirm` 才真正执行 |
+| `/handoff` | 交接新会话：生成九段交接单（先出预览卡）→ 建新会话 → 自动切过去，旧会话保留 |
+| `/pin` | 锁定重要消息，压缩时**不碰**它们；`/pin clear` 或 `/unpin` 解锁 |
+
+菜单里也有同名入口，效果一样。
+
+## 3. 设置在哪
+
+打开 DSH「设置」→ 左侧「压缩接力」。页面标题下有一句话说明这页做什么、边界在哪（只动本插件的压缩/交接历史，不改模型回复）；6 个区块：压缩提示 → 压缩行为 → DSH 原生自动压缩 → 颜色与外观 → 帮助 → 关于与危险操作。
+
+- **指示灯怎么看**：设置页「帮助」区顶部的教学卡片，5 个示意环（未满灰 / 走满蓝 / 压缩区琥珀 / 交接区红 / 原生线），随你的配色和阈值实时变
+- **再看一次初次引导**：「帮助」区的按钮，点了关掉设置页就会重播引导（手动重播时长更长）
+- **最小压缩线**：低于它压缩不划算（默认 5%，会随保留量和窗口自动抬高）
+- **压缩提醒线 / 交接提醒线**：按上下文窗口的百分比算（1M 窗口默认 40% / 60%），换小窗口模型自动缩放
+- **摘要份数上限**：压到几份摘要后建议交接（默认 6）
+- **保留近期原文**：压缩时这段 token 内的近期消息保持原文（默认 40K）
+- **DSH 原生自动压缩**：状态 + 一键关闭/恢复（会先确认，改 profile 配置前备份，重启生效）；原生开着时交接线最高只能设到「原生线 −1%」
+- **交接单目录**：九段交接单保存位置
+- **颜色**：选 5 个基准色（默认/填满/调整/上限/锁定），浅色/深色两套自动派生；每行都有「作用」和「调整后」两行说明
+
+改完点「保存」，**立即生效，不需要重启**。
+
+## 4. 常见问题
+
+- **指示灯显示「上下文未知」**：会话刚打开，等半秒到 1.5 秒会自己出数。
+- **没有「可压」内容**：会话太短，或近期内容需要保留原文，或锁定把范围挡住了（先 `/unpin`）。
+- **压缩到一半取消了**：历史不会变、锁会释放；已发出的模型请求可能仍计费。
+- **换模型后阈值变了**：阈值按窗口比例算，小窗口模型会自动变小，这是预期。
+- **设置保存了但没变**：设置栏保存即时生效；改代码或 profile 配置才需要重启 DSH。
+
+## 5. 更多
+
+- 安装、完整说明见仓库 `README.md`；设计文档见 `ARCHITECTURE.md`。
+- 遇到 bug / 想提改进：到仓库 Issues 提一条（设置页「帮助」区的「反馈」入口建好后会直接打开）。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# Bundle patch for dsh-compact-relay: inserts its plugin row into the profile
+# roster. Applied as a profile bundle layer (the `dsh.bundle.patch` manifest
+# field); installed via the profile package.json dependencies + dsh.profile.bundles.
+- insert:
+    - id: compact-relay
+      name: 'dsh-compact-relay'

package/lib/actions/better-compact.js

@@ -0,0 +1,326 @@
+/**
+ * 压缩旧会话（/bc，内部代号「精压」/BC）—— 唯一实现（M2 正式版 / M6 预览 + 确认 + 取消）。
+ *
+ * 不再包装原生 compactNow，走自建事务：
+ *   选段（跳过旧摘要 = 不二压）→ 摘要（结构化 prompt）→ 替换历史。
+ *
+ * 泄压阀：摘要份数到 thresholds.maxSummaries 后，选段不再受「最后 checkpoint 之后」
+ * 约束（core/policy.compactionPolicy → dsh/select-range 的 afterSeq=undefined），
+ * 旧摘要会被新摘要一并覆盖（合并），防止摘要无限堆积。
+ *
+ * M6 起分三步走：
+ *   1. previewBetterCompact —— 只算「能压多少」，不写任何东西（/bc 与菜单先走它）；
+ *   2. betterCompact —— 真正执行（/bc confirm 或确认卡按钮）；
+ *   3. cancelBetterCompact —— 执行中取消（HTTP cancel → deps.inflight 里的 AbortController）。
+ * 预览与执行共用 planCompact，保证两边口径一致。
+ */
+import { createHash } from 'node:crypto';
+import { actionError } from '../core/errors.js';
+import { livePinnedSeqs } from '../dsh/session-view.js';
+import { compactionPolicy } from '../core/policy.js';
+import { SUMMARY_INSTRUCTION } from '../core/prompts.js';
+import { selectCompactableRange } from '../dsh/select-range.js';
+import { replaceRangeWithSummary } from '../dsh/compact-transaction.js';
+import { runIdle } from '../dsh/idle.js';
+import { measurePressure } from '../dsh/pressure.js';
+import { countSummaries } from '../dsh/session-view.js';
+import { summarize } from '../dsh/summarizer.js';
+import { withLock } from './lock.js';
+
+/** 范围小于这个 token 数时，摘要大概率比原文大：预览阶段就提示、前端据此禁用确认（0.3.1）。 */
+const MIN_MEANINGFUL_TOKENS = 800;
+
+/** 容量数字的紧凑写法（与浏览器半 `20-format.js` 的 fmt 保持同一口径）。 */
+function fmtTokens(tokens) {
+  if (!Number.isFinite(tokens)) return '—';
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(2)}M`;
+  if (tokens >= 1000) return `${(tokens / 1000).toFixed(1)}K`;
+  return String(Math.round(tokens));
+}
+
+/**
+ * 预览计划缓存（架构 A3）。
+ *
+ * 「用户看到的范围」与「点确认后实际压的范围」必须是同一份数据：
+ * preview 记下 planId + 范围，confirm 带 planId 回来；宿主重算发现不一致就拒绝。
+ * 按会话存，5 分钟过期；`/bc confirm` 从这里取（HTTP 客户端则显式带 expected）。
+ */
+const PREVIEW_TTL_MS = 5 * 60_000;
+const previewPlans = new Map();
+
+function planIdOf(range) {
+  return createHash('sha256')
+    .update(`${range.startSeq}:${range.endSeq}:${range.shadowedSeqs.join(',')}`)
+    .digest('hex')
+    .slice(0, 16);
+}
+
+function rememberPreviewPlan(sessionId, plan) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return;
+  previewPlans.set(sessionId, { ...plan, expiresAt: Date.now() + PREVIEW_TTL_MS });
+}
+
+/**
+ * 取出并消费一次预览计划；过期/不存在返回 null。
+ * @param {string|undefined} sessionId
+ * @returns {{planId:string,startSeq:number,endSeq:number,shadowedSeqs:number[]}|null}
+ */
+export function takePreviewPlan(sessionId) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return null;
+  const entry = previewPlans.get(sessionId);
+  if (entry === undefined) return null;
+  if (entry.expiresAt < Date.now()) {
+    previewPlans.delete(sessionId);
+    return null;
+  }
+  return {
+    planId: entry.planId,
+    startSeq: entry.startSeq,
+    endSeq: entry.endSeq,
+    shadowedSeqs: [...entry.shadowedSeqs],
+  };
+}
+
+/** 测试用：清空预览缓存。 */
+export function clearPreviewPlans() {
+  previewPlans.clear();
+}
+
+function shadowedTokensOf(nodes, shadowedSeqs) {
+  const wanted = new Set(shadowedSeqs);
+  return nodes
+    .filter((node) => wanted.has(node.seq))
+    .reduce((sum, node) => sum + (node.heuristicTokens ?? node.tokens ?? 0), 0);
+}
+
+/**
+ * 算一遍「这次能压什么」—— 预览与正式执行共用，保证两边口径一致。
+ * @param {{ctx:object, cfg:object, engine:object}} deps
+ * @param {object} agent
+ */
+async function planCompact(deps, agent) {
+  const measured = await measurePressure(deps.ctx, agent, { windowFallback: deps.cfg.contextWindowFallback });
+  const nodes = measured.nodes.filter((node) => Number.isInteger(node?.seq));
+
+  const summaries = countSummaries(agent.session);
+  const { allowMergeOldSummaries } = compactionPolicy({ summaries, thresholds: deps.cfg.thresholds });
+  // 只把「当前 surface 上还在」的钉住消息算进去：过期 seq 不该再劝用户 /unpin。
+  const pinned = livePinnedSeqs(agent.session);
+
+  const range = selectCompactableRange({
+    session: agent.session,
+    nodes,
+    engine: deps.engine,
+    cfg: deps.cfg,
+    tokenOf: (node) => node.heuristicTokens ?? node.tokens ?? 0,
+  });
+
+  return { measured, nodes, summaries, allowMergeOldSummaries, range, pinned, planId: range === null ? null : planIdOf(range) };
+}
+
+/**
+ * 没有可压范围时给用户的解释——被钉住挡住时要指出来，否则用户不知道去 /unpin。
+ * @param {number[]|undefined} pinned
+ */
+function noRangeMessage(pinned) {
+  return pinned !== undefined && pinned.length > 0
+    ? `暂无可压缩内容：有 ${pinned.length} 条消息被「锁定」保护，请先解锁再试（/unpin）。`
+    : '暂无可压缩内容（当前会话太短，或近期会话需保留原文）。';
+}
+
+/**
+ * 压缩本体（不加锁、不登记）—— 交接要先压缩旧会话，复用这一份实现，不要各写一遍。
+ * @param {{ctx:object, cfg:object, lock:object, engine:object}} deps
+ * @param {{agent:object, signal?:AbortSignal, commandId?:string}} input
+ */
+export async function betterCompactLocked(deps, { agent, signal, commandId, expected }) {
+  if (agent === undefined || agent === null) throw actionError('nosession', '没有活动会话');
+  const session = agent.session;
+
+  const plan = await planCompact(deps, agent);
+  const { nodes, allowMergeOldSummaries, summaries, range, pinned, planId } = plan;
+
+  // 架构 A3：确认必须绑定同一段范围。重算后发现不是用户看过的那一段 → 拒绝，不写任何东西。
+  if (range !== null && expected !== undefined && expected !== null) {
+    if (typeof expected !== 'object' || typeof expected.planId !== 'string' || expected.planId !== planId) {
+      throw actionError('changed', '会话在确认期间又更新了，压缩范围已变；请重新预览后再确认。');
+    }
+  }
+
+  if (range === null) {
+    return {
+      ok: true,
+      compacted: false,
+      planId: null,
+      message: noRangeMessage(pinned),
+    };
+  }
+
+  const freshRange = { ...range, shadowedTokenCount: shadowedTokensOf(nodes, range.shadowedSeqs) };
+  const flush =
+    typeof deps.ctx.sessions?.flush === 'function' ? () => deps.ctx.sessions.flush(session) : undefined;
+  const estimateMessage =
+    typeof deps.ctx?.tokenMeter?.estimateMessage === 'function'
+      ? (message) => deps.ctx.tokenMeter.estimateMessage(message)
+      : undefined;
+
+  const outcome = await runIdle(agent, (idleSignal) => {
+    const combined = signal === undefined ? idleSignal : AbortSignal.any([signal, idleSignal]);
+    return replaceRangeWithSummary({
+      session,
+      range: freshRange,
+      engine: deps.engine,
+      signal: combined,
+      sourceCommandId: commandId,
+      estimateMessage,
+      summarize: ({ shadowedSeqs, signal: innerSignal }) =>
+        summarize({
+          ctx: deps.ctx,
+          engine: deps.engine,
+          agent,
+          shadowedSeqs,
+          endSeq: freshRange.endSeq,
+          instruction: SUMMARY_INSTRUCTION,
+          maxTokens: deps.cfg.summary.maxTokens,
+          inputTokens: plan.measured.tokens,
+          timeoutMs: deps.cfg.timeouts?.llmMs,
+          signal: innerSignal,
+        }),
+      flush,
+    });
+  });
+
+  const note = allowMergeOldSummaries
+    ? '，同时合并了旧摘要'
+    : summaries > 0
+      ? '，旧摘要保持原样'
+      : '';
+  const pinNote = range.pinnedCut === true ? `，已跳过 ${range.pinnedKept} 条锁定的消息` : '';
+  return {
+    ok: true,
+    compacted: true,
+    // A3/A5：把被批准的范围 id 带出动作层（交接链记录/0.4 diff 可引用）。
+    planId,
+    ...outcome,
+    message: `压缩完成：${outcome.shadowedSeqs.length} 条旧会话 → 1 条摘要（腾出约 ${outcome.shadowedTokenCount} 容量${note}${pinNote}）。`,
+  };
+}
+
+/**
+ * 压缩预览：只算范围与 token，不写会话日志。
+ * @param {{ctx:object, cfg:object, lock:object, engine:object}} deps
+ * @param {{agent:object}} input
+ */
+export async function previewBetterCompact(deps, { agent } = {}) {
+  if (agent === undefined || agent === null) throw actionError('nosession', '没有活动会话');
+  if (typeof deps.lock?.isBusy === 'function' && deps.lock.isBusy(agent.id)) {
+    throw actionError('busy', '当前会话正在压缩或交接，请等完成后再预览');
+  }
+
+  const { nodes, range, pinned, planId } = await planCompact(deps, agent);
+  if (range === null) {
+    return {
+      ok: true,
+      compacted: false,
+      preview: null,
+      message: noRangeMessage(pinned),
+    };
+  }
+
+  const shadowedTokenCount = shadowedTokensOf(nodes, range.shadowedSeqs);
+  rememberPreviewPlan(agent.id, {
+    planId,
+    startSeq: range.startSeq,
+    endSeq: range.endSeq,
+    shadowedSeqs: range.shadowedSeqs,
+  });
+  // 0.3.1：小范围压缩大概率「摘要比原文还大」被拒，预览阶段就提示并让前端禁用确认。
+  const tooSmall = shadowedTokenCount < MIN_MEANINGFUL_TOKENS;
+  return {
+    ok: true,
+    compacted: false,
+    planId,
+    preview: {
+      nodes: range.shadowedSeqs.length,
+      tokens: shadowedTokenCount,
+      startSeq: range.startSeq,
+      endSeq: range.endSeq,
+      planId,
+      tooSmall,
+      ...(range.pinnedCut === true ? { pinnedKept: range.pinnedKept } : {}),
+    },
+    message:
+      `压缩预估：将把 ${range.shadowedSeqs.length} 条旧会话压成 1 条摘要` +
+      `（腾出约 ${fmtTokens(shadowedTokenCount)} tokens${range.pinnedCut === true ? `，已跳过 ${range.pinnedKept} 条锁定的消息` : ''}）。` +
+      (tooSmall
+        ? `这段偏小，压了可能反而更大；建议再聊几轮或把「保留近期原文」调小后再压缩。`
+        : '只估算范围和容量，摘要内容确认后才生成。') +
+      (tooSmall ? '' : '确认执行：/bc confirm'),
+  };
+}
+
+/**
+ * 请求取消正在跑的压缩。
+ * @param {{inflight?:object}} deps
+ * @param {{agent?:object}} [input]
+ */
+export function cancelBetterCompact(deps, { agent } = {}) {
+  const kind = deps.inflight?.kindOf?.(agent?.id) ?? null;
+  const found =
+    deps.inflight !== undefined &&
+    typeof deps.inflight.cancel === 'function' &&
+    deps.inflight.cancel(agent?.id);
+  return found
+    ? {
+        ok: true,
+        cancelled: true,
+        kind,
+        message:
+          kind === 'handoff'
+            ? '已请求取消交接（已完成的压缩不会回滚）。'
+            : '已请求取消压缩（会话记录不会改动）。',
+      }
+    : { ok: false, cancelled: false, kind: null, message: '当前没有正在进行的压缩/交接任务。' };
+}
+
+function combinedSignal(a, b) {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  return AbortSignal.any([a, b]);
+}
+
+/**
+ * 压缩动作入口：带每会话单飞锁 + 可取消登记。
+ * @param {{ctx:object, cfg:object, lock:object, engine:object, inflight?:object}} deps
+ * @param {{agent:object, signal?:AbortSignal, commandId?:string}} input
+ */
+export async function betterCompact(deps, input) {
+  if (input?.agent === undefined || input?.agent === null) throw actionError('nosession', '没有活动会话');
+  const agent = input.agent;
+  const controller =
+    deps.inflight !== undefined && typeof deps.inflight.begin === 'function'
+      ? deps.inflight.begin(agent.id, 'compact')
+      : null;
+  const signal = combinedSignal(controller?.signal, input.signal);
+
+  try {
+    return await withLock(deps.lock, agent.id, () => betterCompactLocked(deps, { ...input, signal }));
+  } catch (error) {
+    // 取消 → 统一成 cancelled 文案（宿主 HTTP 层据此回「历史没改」）。
+    // P2-1：commit/persistence 表示历史可能已改或落盘状态不明，绝不能谎报「历史没改」。
+    if (
+      signal !== undefined &&
+      signal.aborted &&
+      error?.code !== 'cancelled' &&
+      error?.code !== 'commit' &&
+      error?.code !== 'persistence'
+    ) {
+      throw actionError('cancelled', '已取消，会话记录没有改动。', error);
+    }
+    throw error;
+  } finally {
+    if (controller !== null && typeof deps.inflight.finish === 'function') {
+      deps.inflight.finish(agent.id, controller);
+    }
+  }
+}

package/lib/actions/compact-diff.js

@@ -0,0 +1,30 @@
+/**
+ * 压缩历史（只读动作）—— 给 HTTP / 面板用。
+ *
+ * A6：不做回滚，只展示「压了哪些条、摘要预览、省了多少容量、是否已提交」。
+ */
+import { actionError } from '../core/errors.js';
+import { collectCompactions } from '../dsh/compaction-log.js';
+import { pickAgent } from '../dsh/session-view.js';
+
+/**
+ * @param {object} deps
+ * @param {{sessionId?:string, limit?:number}} [input]
+ */
+export function readCompactDiffs(deps, input = {}) {
+  const sessionId = typeof input.sessionId === 'string' && input.sessionId.length > 0 ? input.sessionId : undefined;
+  const agent = pickAgent(deps?.ctx, sessionId);
+  if (agent === null) throw actionError('nosession', '当前没有活动会话。');
+  const session = agent.session;
+  if (session === undefined || session === null) throw actionError('nosession', '当前没有活动会话。');
+
+  const limit = input.limit;
+  const items = collectCompactions(session, { limit });
+  return {
+    ok: true,
+    sessionId: typeof session.id === 'string' ? session.id : (sessionId ?? null),
+    items,
+    count: items.length,
+    latest: items[0] ?? null,
+  };
+}

package/lib/actions/compress-hint.js

@@ -0,0 +1,58 @@
+/**
+ * 「这里适合压缩」判断（0.3.1）。
+ *
+ * 模型工具 `mark_stage` 在这里落一条 plugin record；环上把它画成断点1。
+ * 用户手动入口已删除（作者 2026-10-20 拍板：判断由模型/阈值自动完成）。
+ */
+import { COMPRESS_HINT_RECORD_TYPE } from '../core/compress-hint.js';
+import { compressionMinRatio } from '../core/policy.js';
+import { measurePressure } from '../dsh/pressure.js';
+
+/**
+ * 记录一次「适合压缩」的判断。
+ * @param {object} deps
+ * @param {{agent: object}} input
+ * @returns {Promise<{ok:boolean, ratio:number, at:number, seq?:number, reason?:string, message:string}>}
+ */
+export async function markCompressHint(deps, { agent } = {}) {
+  const session = agent?.session;
+  if (session === null || session === undefined) {
+    return { ok: false, ratio: 0, at: 0, reason: 'no-session', message: '没有活动会话，无法记录判断' };
+  }
+  const measured = await measurePressure(deps.ctx, agent, { windowFallback: deps.cfg.contextWindowFallback }).catch(() => null);
+  if (measured === null || typeof measured.ratio !== 'number') {
+    return { ok: false, ratio: 0, at: 0, reason: 'no-pressure', message: '拿不到当前容量，先别记录' };
+  }
+  const ratio = measured.ratio;
+  const window = measured.window;
+  const minRatio = compressionMinRatio(deps.cfg.thresholds, deps.cfg.retention, window);
+  const compactRatio = deps.cfg.thresholds.compactRatio;
+  const percent = (value) => `${(value * 100).toFixed(1)}%`;
+  if (ratio < minRatio) {
+    return {
+      ok: false,
+      ratio,
+      at: Date.now(),
+      reason: 'below-min',
+      message: `当前容量 ${percent(ratio)} 还没到最小压缩线 ${percent(minRatio)}——这个位置压缩不划算，不用记录，继续做你的工作`,
+    };
+  }
+  if (ratio >= compactRatio) {
+    return {
+      ok: false,
+      ratio,
+      at: Date.now(),
+      reason: 'already-over',
+      message: `当前容量 ${percent(ratio)} 已经到压缩线了——直接建议用户压缩就行，不用再记录判断点`,
+    };
+  }
+  const at = Date.now();
+  const seq = deps.engine.appendPluginRecord(session, COMPRESS_HINT_RECORD_TYPE, { ratio, at });
+  return {
+    ok: true,
+    ratio,
+    at,
+    seq,
+    message: `已记录「适合压缩」判断：当前 ${percent(ratio)}（在最小线和压缩线之间）。用户会在环上看到一个断点`,
+  };
+}

package/lib/actions/handoff-docs.js

@@ -0,0 +1,27 @@
+/**
+ * 交接单读取动作（A9）—— 适配层不再直接 import dsh 能力层。
+ *
+ * HTTP 只关心「列最近 N 份 / 读一篇的 JSON」，目录白名单/防穿越/大小上限
+ * 全部留在 dsh/handoff-files.js。
+ */
+import { listHandoffFiles, readHandoffFile } from '../dsh/handoff-files.js';
+
+/**
+ * @param {{cfg:{handoffDir:string}}} deps
+ * @param {{limit?:number}} [options]
+ */
+export function listHandoffDocs(deps, { limit = 20 } = {}) {
+  return {
+    dir: deps.cfg.handoffDir,
+    items: listHandoffFiles(deps.cfg.handoffDir, { limit }),
+  };
+}
+
+/**
+ * 读一篇交接单；不存在/文件名非法返回 null。
+ * @param {{cfg:{handoffDir:string}}} deps
+ * @param {{file:string}} input
+ */
+export function readHandoffDoc(deps, { file } = {}) {
+  return readHandoffFile(deps.cfg.handoffDir, file);
+}