dsh-compact-relay 0.3.2 → 0.3.4

package/lib/config.js

@@ -13,6 +13,7 @@ import {
   fieldAt,
   validateConfig,
 } from './core/config-schema.js';
+import { isPlainObject } from './core/object.js';
 
 // 兼容旧导入：其它模块/文档仍可从 config.js 拿默认配置与路径工具。
 export { CONFIG_FIELDS, DEFAULT_CONFIG, defaultDshHome, expandHome } from './core/config-schema.js';
@@ -27,8 +28,6 @@ const BASE_COLOR_DEFAULTS = {
   handoff: fieldAt(['colors', 'base', 'handoff']).default,
 };
 
-const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
-
 function objectOf(raw, key) {
   return isPlainObject(raw[key]) ? raw[key] : {};
 }

package/lib/core/compress-cue.js

@@ -0,0 +1,96 @@
+/**
+ * 0.3.4：「可以记一个压缩节点」的动态提示 —— 纯函数，零依赖。
+ *
+ * 背景（BUG-010）：0.3.1 的 `mark_stage` 工具只告诉模型「条件合适时调用」，
+ * 但模型根本看不到当前容量，两条条件无法判断 → 427 个真实会话里 0 次调用。
+ * 现在由宿主在 system prompt 的动态 context 里给出「当前处于可压缩区间」的提示，
+ * 模型才具备可执行判断；`mark_compress_point` 工具再自己复核一次（服务端仍校验）。
+ *
+ * 这段输出会被塞进**每一轮**的 system prompt，所以两件事很重要：
+ *  1. 尽量稳定：容量按 5% 桶取整，避免每个 token 变化都让提示重发；
+ *  2. 尽量安静：刚记过 hint（差 10 个百分点内）就不再重复提醒。
+ *
+ * 只做纯计算：入参都是数字/小对象，不 import 任何 DSH 模块，可裸跑单测。
+ */
+
+/** 动态 context 的名称（宿主按 name 去重/覆盖）。 */
+export const COMPRESS_CUE_NAME = 'compact-relay:compress-cue';
+
+/** 动态 context 的排序位置：排在宿主内置 context（100–210）之后。 */
+export const COMPRESS_CUE_ORDER = 300;
+
+/** 容量百分比取整桶：5%（0.05）。 */
+export const BUCKET_RATIO = 0.05;
+
+/** 已记 hint 后，容量再涨这么多（10 个百分点）才重新提示。 */
+export const HINT_SUPPRESS_RATIO = 0.1;
+
+/**
+ * 把 0–1 的比例向下取整到 5% 桶（避免 system-prompt 每轮都变）。
+ * 0.32 → 0.30，0.39 → 0.35，1 → 1（压缩线在 1 之前，正常到不了 100%）。
+ * @param {number} ratio
+ * @param {number} [step]
+ * @returns {number}
+ */
+export function bucketRatio(ratio, step = BUCKET_RATIO) {
+  if (!Number.isFinite(ratio) || !Number.isFinite(step) || step <= 0) return 0;
+  const clamped = Math.min(1, Math.max(0, ratio));
+  const bucketed = Math.floor(clamped / step + 1e-9) * step;
+  // 浮点累加（0.05*7=0.35000000000000003）会有尾数，四舍五入回两位小数。
+  return Math.round(bucketed * 100) / 100;
+}
+
+/**
+ * 比例 → 百分比文本：0.05 → '5'，0.325 → '32.5'。
+ *
+ * 保留一位小数时**向上取整**：动态最小线可能是 33.569%（128K 窗口 + 40K 保留），
+ * 若四舍五入成 33.6/33.5 会出现「提示值低于同一句的区间下限」的自相矛盾；
+ * 向上取整保证展示值不小于真实值（宁可说大 0.1 个百分点）。
+ * @param {number} ratio
+ * @returns {string}
+ */
+export function formatPercent(ratio) {
+  if (!Number.isFinite(ratio)) return '?';
+  const percent = Math.ceil(Math.min(100, Math.max(0, ratio * 100)) * 10 - 1e-9) / 10;
+  return Number.isInteger(percent) ? String(percent) : percent.toFixed(1);
+}
+
+/**
+ * 是否处于「可以记压缩节点」的区间：最小压缩线 ≤ 当前 < 压缩线。
+ * @param {{ratio:number, minRatio:number, compactRatio:number}} input
+ * @returns {boolean}
+ */
+export function inCompressCueBand({ ratio, minRatio, compactRatio }) {
+  if (!Number.isFinite(ratio) || !Number.isFinite(minRatio) || !Number.isFinite(compactRatio)) return false;
+  return ratio >= minRatio && ratio < compactRatio;
+}
+
+/**
+ * 生成动态提示；不满足条件返回空串（宿主不会展示空 context）。
+ *
+ * @param {object} input
+ * @param {number} input.ratio 当前上下文占用比例（0–1）
+ * @param {number} input.minRatio 最小压缩线（compressionMinRatio 的结果）
+ * @param {number} input.compactRatio 压缩提醒线（cfg.thresholds.compactRatio）
+ * @param {{ratio:number}|null} [input.compressHint] 当前有效的「适合压缩」记录（没有为 null）
+ * @returns {string}
+ */
+export function compressCueText({ ratio, minRatio, compactRatio, compressHint = null }) {
+  if (!inCompressCueBand({ ratio, minRatio, compactRatio })) return '';
+  // 刚记过断点：容量只涨了不到 10 个百分点 → 不重复提醒（模型已经判断过一次）。
+  if (
+    compressHint !== null &&
+    compressHint !== undefined &&
+    Number.isFinite(compressHint.ratio) &&
+    ratio - compressHint.ratio < HINT_SUPPRESS_RATIO
+  ) {
+    return '';
+  }
+  // 显示值不能低于同一句里的区间下限：5% 桶可能把 33.7% 取整成 30%，而 128K 窗口
+  // 的动态最小线是 33.569% —— 那样提示会自相矛盾（「约 30%（可压缩区间 33.6%–40%）」）。
+  const shownRatio = Math.max(bucketRatio(ratio), minRatio);
+  return (
+    `上下文容量约 ${formatPercent(shownRatio)}%（可压缩区间 ${formatPercent(minRatio)}%–${formatPercent(compactRatio)}%）。` +
+    '如果刚刚完成一个明确的任务/阶段（自然节点），调用 mark_compress_point 记录一个压缩节点；不确定就不用调。'
+  );
+}

package/lib/core/compress-hint.js

@@ -5,7 +5,7 @@
  *   plugin:compact-relay/compress-hint   data: { ratio, at }
  *
  * 环上把它画成「断点1」（正常区/压缩区的分界）；压缩或交接改变历史后自动失效
- * （和 checkpoint 比较 seq，跟旧阶段标记一个套路）。
+ * （和 checkpoint 比较 seq，同一套新鲜度判定）。
  */
 
 /** 记录类型（DSH 语法：`plugin:` + 小写段；只认精确匹配）。 */

package/lib/core/errors.js

@@ -17,7 +17,6 @@ const MESSAGES = Object.freeze({
   nosession: '当前没有活动会话。',
   pairing: '压缩范围会切断配对的工具调用，本次未执行（换一段或稍后重试）。',
   shrink: '摘要比被替换的内容还大，本次未提交；先继续聊几轮，或把「保留近期原文」调小一点，再来压缩。',
-  stage: '没法标记进度：当前没有打开的会话。',
 });
 
 /**

package/lib/core/handoff-spec.js

@@ -35,7 +35,7 @@ export const HANDOFF_SPEC = Object.freeze([
     title: '当前进度',
     owner: 'program',
     required: true,
-    hint: '程序收集：阶段标记、已压缩次数、已用容量、锁定消息、后台任务',
+    hint: '程序收集：压缩判断点、已压缩次数、已用容量、锁定消息、后台任务',
   },
   {
     key: 'files',

package/lib/core/markdown-lite.js

@@ -0,0 +1,178 @@
+/**
+ * 轻量 Markdown 解析（0.3.4 BUG-005）—— 纯函数，零依赖。
+ *
+ * 为什么自己写：交接单详情面板以前把 markdown 原样塞进 `<pre>`，用户在面板里看到的是
+ * `## 目标`/`- xxx`/`**粗体**` 源码。引第三方 markdown 渲染器会增加运行时依赖
+ * （插件只有 peerDependencies、零运行时依赖是硬约束），而 `dangerouslySetInnerHTML`
+ * 又引入 XSS 面。所以这里只解析交接单实际用到的子集，产出**结构化数据**，由客户端
+ * 用 React 文本节点渲染 —— 从不生成 HTML，任何 `<script>` 都只会显示成文字。
+ *
+ * 支持（够用即可，不做完整 CommonMark）：
+ *   - 标题 `#`–`######`（段落里的行首）
+ *   - 段落（连续非空行；保留原始换行）
+ *   - 无序列表 `-` / `*` / `+`
+ *   - 有序列表 `1.` / `1)`（保留起始编号）
+ *   - 围栏代码块 ```（保留语言标记；块内不做行内解析）
+ *   - 分隔线 `---` / `***` / `___`
+ *   - 行内：`**粗体**`、`` `行内代码` ``、反斜杠转义
+ *
+ * 返回值约定（客户端渲染器按此映射 React 节点）：
+ *   blocks: Array<
+ *     | {type:'heading', level:number, segments:Segment[]}
+ *     | {type:'paragraph', segments:Segment[]}
+ *     | {type:'list', ordered:boolean, start:number, items:Segment[][]}
+ *     | {type:'code', lang:string, text:string}
+ *     | {type:'hr'}
+ *   >
+ *   Segment = {type:'text'|'strong'|'code', text:string}
+ */
+
+const FENCE_RE = /^\s*```\s*([^\s`]*)\s*$/;
+const HEADING_RE = /^(#{1,6})\s+(.*)$/;
+const HR_RE = /^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/;
+const UL_RE = /^\s*[-*+]\s+(.*)$/;
+const OL_RE = /^\s*(\d+)[.)]\s+(.*)$/;
+
+/**
+ * 解析行内标记：`**粗体**`、`` `代码` ``、反斜杠转义。
+ * 未闭合的标记按普通文本处理（不吞字符）。
+ * @param {string} text
+ * @returns {{type:'text'|'strong'|'code', text:string}[]}
+ */
+export function parseInlineLite(text) {
+  const source = typeof text === 'string' ? text : String(text ?? '');
+  const segments = [];
+  let buffer = '';
+  const flush = () => {
+    if (buffer.length > 0) {
+      segments.push({ type: 'text', text: buffer });
+      buffer = '';
+    }
+  };
+  let index = 0;
+  while (index < source.length) {
+    const char = source[index];
+    // 反斜杠转义：下一个字符按字面量处理（\* 不开启粗体）。
+    if (char === '\\' && index + 1 < source.length) {
+      buffer += source[index + 1];
+      index += 2;
+      continue;
+    }
+    if (char === '`') {
+      const end = source.indexOf('`', index + 1);
+      if (end === -1) {
+        buffer += char;
+        index += 1;
+        continue;
+      }
+      flush();
+      segments.push({ type: 'code', text: source.slice(index + 1, end) });
+      index = end + 1;
+      continue;
+    }
+    if (char === '*' && source[index + 1] === '*') {
+      const end = source.indexOf('**', index + 2);
+      if (end === -1) {
+        buffer += '**';
+        index += 2;
+        continue;
+      }
+      flush();
+      segments.push({ type: 'strong', text: source.slice(index + 2, end) });
+      index = end + 2;
+      continue;
+    }
+    buffer += char;
+    index += 1;
+  }
+  flush();
+  return segments;
+}
+
+/**
+ * 把 markdown 文本解析成块数组；空文本返回 []。
+ * @param {string} text
+ * @returns {object[]}
+ */
+export function parseMarkdownLite(text) {
+  const source = typeof text === 'string' ? text : String(text ?? '');
+  const lines = source.replace(/\r\n?/g, '\n').split('\n');
+  const blocks = [];
+  let index = 0;
+
+  // 连续非空行攒成段落；遇到块级语法先 flush。
+  let paragraph = [];
+  const flushParagraph = () => {
+    if (paragraph.length === 0) return;
+    blocks.push({ type: 'paragraph', segments: parseInlineLite(paragraph.join('\n')) });
+    paragraph = [];
+  };
+
+  while (index < lines.length) {
+    const line = lines[index];
+
+    // 围栏代码块
+    const fence = FENCE_RE.exec(line);
+    if (fence !== null) {
+      flushParagraph();
+      const codeLines = [];
+      index += 1;
+      while (index < lines.length && FENCE_RE.exec(lines[index]) === null) {
+        codeLines.push(lines[index]);
+        index += 1;
+      }
+      // 吃掉收尾围栏（未闭合时到文件尾）
+      if (index < lines.length) index += 1;
+      blocks.push({ type: 'code', lang: fence[1] ?? '', text: codeLines.join('\n') });
+      continue;
+    }
+
+    // 空行：结束段落
+    if (line.trim().length === 0) {
+      flushParagraph();
+      index += 1;
+      continue;
+    }
+
+    // 标题
+    const heading = HEADING_RE.exec(line);
+    if (heading !== null) {
+      flushParagraph();
+      blocks.push({ type: 'heading', level: heading[1].length, segments: parseInlineLite(heading[2]) });
+      index += 1;
+      continue;
+    }
+
+    // 分隔线（注意：`---` 也匹配无序列表语法，必须先判 hr）
+    if (HR_RE.test(line)) {
+      flushParagraph();
+      blocks.push({ type: 'hr' });
+      index += 1;
+      continue;
+    }
+
+    const unordered = UL_RE.exec(line);
+    const ordered = unordered === null ? OL_RE.exec(line) : null;
+    if (unordered !== null || ordered !== null) {
+      flushParagraph();
+      const isOrdered = ordered !== null;
+      const start = isOrdered ? Number(ordered[1]) : 1;
+      const items = [];
+      const itemRe = isOrdered ? OL_RE : UL_RE;
+      while (index < lines.length) {
+        const matched = itemRe.exec(lines[index]);
+        if (matched === null) break;
+        items.push(parseInlineLite(isOrdered ? matched[2] : matched[1]));
+        index += 1;
+      }
+      blocks.push({ type: 'list', ordered: isOrdered, start, items });
+      continue;
+    }
+
+    // 普通段落行（保留换行）
+    paragraph.push(line);
+    index += 1;
+  }
+  flushParagraph();
+  return blocks;
+}

package/lib/core/object.js

@@ -0,0 +1,19 @@
+/**
+ * 纯对象工具 —— 零依赖。
+ *
+ * `isPlainObject` 曾在本文件出现之前有三份（config.js / dsh/settings-file.js /
+ * actions/settings.js）：语义完全相同（非 null、typeof object、非数组），
+ * 但任何一份改了判定口径，三处的「配置/信封/深合并」就会不一致。
+ * 现在只保留这一份，其余位置一律 import。
+ */
+
+/**
+ * 是否是「普通对象」（非 null、typeof object、非数组）。
+ *
+ * 注意：这是本项目对「JSON 对象」的判定口径，不区分原型链（class 实例也算）。
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/lib/core/ranges.js

@@ -8,6 +8,7 @@
  *   - selectTestRange：M1 实验用，取最近 N 条（小范围、可预测）；
  *   - selectFullRange：M2 正式版用，跳过旧摘要（不二压）、保留近期尾部。
  */
+import { tokenOf } from './tokens.js';
 
 const isSeq = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 0;
 
@@ -91,8 +92,6 @@ export function selectFullRange({
   }
   if (begin >= list.length - 1) return null;
 
-  const tokenOf = (node) => node.heuristicTokens ?? node.tokens ?? 0;
-
   // 终点：从尾部往回留出 recentTailTokens 的逐字尾部。
   let end = list.length - 1;
   let tailSum = 0;

package/lib/core/relay.js

@@ -2,10 +2,10 @@
  * 接力链记录（A5）—— 把「这次交接建了哪个子会话」从文案变成数据。
  *
  * 写在**父会话**日志里的一条 plugin record（不进模型上下文、不算 token、压缩碰不到），
- * 和 stage/pin 同一种模式。下一次从同一会话交接时优先读它，不再靠解析标题/输出文案。
+ * 和压缩判断记录/pin 同一种模式。下一次从同一会话交接时优先读它，不再靠解析标题/输出文案。
  */
 
-/** 会话日志里记录 relay 的类型（与 stage/pin 的 plugin record 同前缀）。 */
+/** 会话日志里记录 relay 的类型（与压缩判断记录/pin 的 plugin record 同前缀）。 */
 export const RELAY_RECORD_TYPE = 'plugin:compact-relay/relay';
 
 /**

package/lib/core/tokens.js

@@ -0,0 +1,34 @@
+/**
+ * token 估算公共口径 —— 纯函数，零依赖。
+ *
+ * surface 节点（dsh/pressure 测出来的 node）同时可能带 `heuristicTokens`
+ * 与 `tokens`。口径必须全插件一致：
+ *   - 选段的「近期尾部预算」（core/ranges.js）
+ *   - state 帧里算可压范围（actions/state.js）
+ *   - 压缩预览/执行里算「腾出多少容量」（actions/better-compact.js、actions/test-compact.js）
+ *
+ * 以前这几处各写一份 `node.heuristicTokens ?? node.tokens ?? 0`，还有两处
+ * 完全相同的 `shadowedTokensOf` / `tokenCountOf` 求和函数；现在只保留这里一份。
+ */
+
+/**
+ * 单个 surface 节点按哪个字段算 token（heuristic 优先，口径唯一）。
+ * @param {{tokens?:number, heuristicTokens?:number}} node
+ * @returns {number}
+ */
+export function tokenOf(node) {
+  return node?.heuristicTokens ?? node?.tokens ?? 0;
+}
+
+/**
+ * 被遮罩 seq 集合的 token 总数（压缩范围要「腾出多少容量」的公共算法）。
+ * @param {{seq:number, tokens?:number, heuristicTokens?:number}[]} nodes
+ * @param {number[]} shadowedSeqs
+ * @returns {number}
+ */
+export function sumShadowedTokens(nodes, shadowedSeqs) {
+  const wanted = new Set(shadowedSeqs);
+  return nodes
+    .filter((node) => wanted.has(node.seq))
+    .reduce((sum, node) => sum + tokenOf(node), 0);
+}

package/lib/dsh/compaction-log.js

@@ -10,6 +10,7 @@
  *   3. 没有 compactionId 的旧日志按旧口径（有 replace 即算）。
  */
 import { sessionLog } from './session-view.js';
+import { scanCompactionLog } from './compaction-pair.js';
 
 const DEFAULT_LIMIT = 10;
 const MAX_LIMIT = 50;
@@ -86,25 +87,8 @@ function limitOf(options) {
 export function collectCompactions(session, options = {}) {
   const limit = limitOf(options);
   const maxChars = Number.isFinite(options.previewChars) ? Math.max(1, Math.trunc(options.previewChars)) : PREVIEW_CHARS;
-  const log = sessionLog(session);
-
-  const summaries = [];
-  const ends = new Map(); // compactionId -> end.data
-  const replaceByCoveredSeq = new Map(); // 被 replace 覆盖的 seq -> replace event
-
-  for (const event of log) {
-    if (event === null || typeof event !== 'object') continue;
-    if (event.type === 'compaction/summary') {
-      summaries.push(event);
-    } else if (event.type === 'compaction/end') {
-      const id = event.data?.compactionId;
-      if (typeof id === 'string') ends.set(id, event.data);
-    } else if (event.type === 'user/message' && Array.isArray(event.sourceEventSeqs)) {
-      for (const seq of event.sourceEventSeqs) {
-        if (typeof seq === 'number' && Number.isFinite(seq)) replaceByCoveredSeq.set(seq, event);
-      }
-    }
-  }
+  // 配对扫描与 dsh/session-view.countSummaries 共用（见 compaction-pair.js）。
+  const { summaries, ends, replaceByCoveredSeq } = scanCompactionLog(sessionLog(session));
 
   const items = [];
   for (let index = summaries.length - 1; index >= 0 && items.length < limit; index -= 1) {

package/lib/dsh/compaction-pair.js

@@ -0,0 +1,48 @@
+/**
+ * 压缩事件配对扫描（A6）—— 从会话日志里把 summary / end / replace 挂上钩。
+ *
+ * 两处消费方，口径必须一致：
+ *   - dsh/session-view.countSummaries：数「已提交的压缩份数」（advice/合并旧摘要用）；
+ *   - dsh/compaction-log.collectCompactions：还原最近几次压缩（只读面板 / diff 端点）。
+ *
+ * 以前两处各自 for 一遍日志、各自建 summaries / ends / replace 索引，键名和过滤
+ * 条件还不完全一样（countSummaries 用 replacedSeqs Set，compaction-log 用
+ * replaceByCoveredSeq Map）——只要一处改配对规则，另一处就静默漂移。
+ * 现在扫描只在这里做一次，两个消费方各自保留自己的「已提交」判定。
+ *
+ * 只读：不写日志、不碰 session 内部结构。
+ */
+
+/**
+ * 扫描事件日志，返回三类索引。
+ *
+ * - summaries：compaction/summary 事件，按日志顺序；
+ * - ends：compactionId → compaction/end 事件的 data（同 id 多次时后者覆盖，与旧实现一致）；
+ * - replaceByCoveredSeq：被 replace 覆盖的 seq → 该 user/message 事件。
+ *   只收 number 且有限的 seq（summary.seq 必然是整数，字符串/NaN 键匹配不上，
+ *   和旧实现直接 Set.add 的判定结果一致）。
+ *
+ * @param {object[]} log 会话事件日志（dsh/session-view.sessionLog 的返回值）
+ * @returns {{summaries:object[], ends:Map<string,object>, replaceByCoveredSeq:Map<number,object>}}
+ */
+export function scanCompactionLog(log) {
+  const summaries = [];
+  const ends = new Map();
+  const replaceByCoveredSeq = new Map();
+
+  for (const event of Array.isArray(log) ? log : []) {
+    if (event === null || typeof event !== 'object') continue;
+    if (event.type === 'compaction/summary') {
+      summaries.push(event);
+    } else if (event.type === 'compaction/end') {
+      const id = event.data?.compactionId;
+      if (typeof id === 'string') ends.set(id, event.data);
+    } else if (event.type === 'user/message' && Array.isArray(event.sourceEventSeqs)) {
+      for (const seq of event.sourceEventSeqs) {
+        if (typeof seq === 'number' && Number.isFinite(seq)) replaceByCoveredSeq.set(seq, event);
+      }
+    }
+  }
+
+  return { summaries, ends, replaceByCoveredSeq };
+}

package/lib/dsh/engine.js

@@ -27,9 +27,9 @@ export const engine = Object.freeze({
   createUserMessage,
   /** 错误 → 可持久化的 JSON 链。 */
   errorChain,
-  /** 追加一条插件私有记录（M4 阶段标记；不进模型可见 surface）。 */
+  /** 追加一条插件私有记录（压缩判断记录/锁定/接力链；不进模型可见 surface）。 */
   appendPluginRecord,
-  /** 声明一个模型可调用的工具（M4 mark_stage）。 */
+  /** 声明一个模型可调用的工具（M4 压缩判断；0.3.4 起工具名 mark_compress_point）。 */
   defineTool,
 });
 

package/lib/dsh/handoff-files.js

@@ -17,6 +17,34 @@ function headerField(text, label) {
   return match === null ? null : match[1].trim();
 }
 
+/**
+ * 交接单总数（0.3.4 BUG-006：列表端点要能报「共 N 份」，不能只回最近 20）。
+ *
+ * 只数合法文件名 + 普通文件，口径与 listHandoffFiles 一致；不读文件头，成本是
+ * 一次 readdir + 每个文件的 stat（目录里通常几十份，可忽略）。
+ * @param {string} dir
+ * @returns {number}
+ */
+export function countHandoffFiles(dir) {
+  if (typeof dir !== 'string' || dir.length === 0) return 0;
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return 0;
+  }
+  let total = 0;
+  for (const name of names) {
+    if (!NAME_RE.test(name)) continue;
+    try {
+      if (fs.statSync(path.join(dir, name)).isFile()) total += 1;
+    } catch {
+      /* 读不到 stat 的文件不计入（与列表口径一致） */
+    }
+  }
+  return total;
+}
+
 /**
  * 列交接单（新→旧）。
  * @param {string} dir

package/lib/dsh/handoff-writer.js

@@ -14,9 +14,7 @@ import { HANDOFF_INSTRUCTION, handoffRecoveryHint } from '../core/prompts.js';
 import { HANDOFF_MODEL_SECTIONS, HANDOFF_SPEC } from '../core/handoff-spec.js';
 import { describeHandoffProblems, validateHandoff } from '../core/validate-handoff.js';
 import { surfaceMessages } from './prefix.js';
-import { assertBudget, callStream, reasoningEffortFor } from './llm-call.js';
-import { cacheControls, routeOf } from './route.js';
-import { finishProblem } from './stream.js';
+import { cacheAlignedControls, callModelAttempt, modelAttemptResult, prepareModelCall } from './model-task.js';
 
 /** 首次 + 1 次带 recovery 提示的重试。 */
 const MAX_ATTEMPTS = 2;
@@ -36,21 +34,23 @@ const MAX_ATTEMPTS = 2;
  */
 export async function generateHandoffDoc({ ctx, engine, agent, maxTokens, inputTokens, timeoutMs, signal, programSections = {} }) {
   const session = agent?.session;
-  if (session === undefined) throw actionError('handoff', '会话不存在，无法生成交接单');
-
-  const target = routeOf(ctx, session, agent);
-  if (target === null) throw actionError('handoff', '没有可用的 provider/model，交接单无法生成');
-
-  // 架构 A2：整段 surface 喂给模型前先做预算预检（交接最容易超窗）。
-  await assertBudget({ ctx, target, inputTokens, maxTokens, label: '交接单生成' });
-  // P2-5：只有模型目录明确支持 off 才传。
-  const reasoningEffort = await reasoningEffortFor(ctx, target);
+  const { target, reasoningEffort } = await prepareModelCall({
+    ctx,
+    session,
+    agent,
+    inputTokens,
+    maxTokens,
+    label: '交接单生成',
+    code: 'handoff',
+    noSessionMessage: '会话不存在，无法生成交接单',
+    noTargetMessage: '没有可用的 provider/model，交接单无法生成',
+  });
 
   const prefix = surfaceMessages(session);
   if (prefix.length === 0) throw actionError('handoff', '这个会话还没有可交接的内容（没有模型可见的消息）');
 
   // 同摘要器：不继承 reasoningEffort（max 思考会把输出上限吃光）；是否传 off 由模型能力决定。
-  const { reasoningEffort: _ignored, ...controls } = cacheControls(session, target);
+  const controls = cacheAlignedControls(session, target);
   let lastProblems = [];
 
   for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
@@ -72,16 +72,15 @@ export async function generateHandoffDoc({ ctx, engine, agent, maxTokens, inputT
       // 交接是第三方调用，标 'handoff' 属类型层非法（运行时虽然不读，也不该留）。
     };
 
-    const assembler = await callStream({
+    const { assembler, problem } = await callModelAttempt({
       ctx,
       engine,
       options,
       signal,
       timeoutMs,
       label: '交接单生成',
+      code: 'handoff',
     });
-
-    const problem = finishProblem(assembler, { code: 'handoff', label: '交接单生成' });
     if (problem !== null) {
       if (assembler.finish?.kind === 'max-tokens' && attempt < MAX_ATTEMPTS) {
         lastProblems = ['输出达到 maxTokens 上限被截断（需要更短、更紧凑的交接单）'];
@@ -112,11 +111,7 @@ export async function generateHandoffDoc({ ctx, engine, agent, maxTokens, inputT
       return {
         text: full.text,
         sections: full.sections,
-        provider: options.provider,
-        model: options.model,
-        maxTokens,
-        attempts: attempt,
-        ...(assembler.usage === undefined ? {} : { usage: assembler.usage }),
+        ...modelAttemptResult({ assembler, options, maxTokens, attempt }),
       };
     }
     lastProblems = validation.problems;