dsh-compact-relay 0.3.6 → 0.4.0

package/lib/core/compress-cue.js

@@ -1,17 +1,26 @@
 /**
- * 0.3.4：「可以记一个压缩节点」的动态提示 —— 纯函数，零依赖。
+ * 0.3.4 / 0.4 P0-1：「可以记一个压缩节点」的动态提示 —— 纯函数，零依赖。
  *
  * 背景（BUG-010）：0.3.1 的 `mark_stage` 工具只告诉模型「条件合适时调用」，
  * 但模型根本看不到当前容量，两条条件无法判断 → 427 个真实会话里 0 次调用。
- * 现在由宿主在 system prompt 的动态 context 里给出「当前处于可压缩区间」的提示，
- * 模型才具备可执行判断；`mark_compress_point` 工具再自己复核一次（服务端仍校验）。
+ * 0.3.4 起由宿主在 system prompt 的动态 context 里给出「当前处于可压缩区间」的提示。
  *
- * 这段输出会被塞进**每一轮**的 system prompt，所以两件事很重要：
+ * 0.4 P0-1（BUG-010 的后续，Win 173 会话 cue 注入 18 次但工具 0 调用）：
+ *  1. 文案 v2：把抽象的「自然节点」换成 4 个可自检的完成信号（功能已实现并验证 /
+ *     文档已交付 / 问题已定位并修复 / 准备交接），并把「不确定就别调」改成
+ *     「不确定也建议调一次让工具判断：被拒绝不会改动历史」——零成本试错；
+ *  2. 区间 v2：cue 只在 [CUE_MIN_RATIO, min(CUE_MAX_RATIO, compactRatio)) 内生成；
+ *     下限与动态最小线（保留尾部 + 最小可压 token / 窗口）取较大者，保证 `min` 显示的
+ *     是「真正压得划算」的线；上限不含压缩线（到线该直接建议压缩，不该再记节点）。
+ *
+ * 这段输出会被塞进 system prompt，所以两件事很重要：
  *  1. 尽量稳定：容量按 5% 桶取整，避免每个 token 变化都让提示重发；
- *  2. 尽量安静：刚记过 hint（差 10 个百分点内）就不再重复提醒。
+ *  2. 尽量安静：刚记过 hint（差 10 个百分点内）不再重复提醒；注入频率由
+ *     adapters/prompt.js 的门控（≥ CUE_MIN_TURNS 轮一次）再收一道。
  *
  * 只做纯计算：入参都是数字/小对象，不 import 任何 DSH 模块，可裸跑单测。
  */
+import { CUE_MAX_RATIO, CUE_MIN_RATIO } from './policy.js';
 
 /** 动态 context 的名称（宿主按 name 去重/覆盖）。 */
 export const COMPRESS_CUE_NAME = 'compact-relay:compress-cue';
@@ -56,13 +65,35 @@ export function formatPercent(ratio) {
 }
 
 /**
- * 是否处于「可以记压缩节点」的区间：最小压缩线 ≤ 当前 < 压缩线。
- * @param {{ratio:number, minRatio:number, compactRatio:number}} input
+ * 0.4 P0-1：计算本会话的 cue 区间。
+ *
+ * - 下限 = max(CUE_MIN_RATIO, 动态最小线)：10% 以下压不划算，动态最小线以下同样不划算；
+ * - 上限 = min(CUE_MAX_RATIO, compactRatio)：40% 及以上该直接建议压缩，用户把压缩线
+ *   配得更低时也不能越过它（否则 cue 会诱导一次注定被拒的调用）。
+ *
+ * 返回的 `{minRatio, maxRatio}` 直接喂给 inCompressCueBand / compressCueText，
+ * 也用于提示里的「可压缩区间 X%–Y%」显示（与真实可接受区间一致）。
+ *
+ * @param {{compactRatio?:number, dynamicMinRatio?:number}} [input]
+ * @returns {{minRatio:number, maxRatio:number}}
+ */
+export function cueBandOf({ compactRatio, dynamicMinRatio } = {}) {
+  const dynamic = Number.isFinite(dynamicMinRatio) ? dynamicMinRatio : 0;
+  const lower = Math.max(CUE_MIN_RATIO, dynamic);
+  const configured = Number.isFinite(compactRatio) ? compactRatio : CUE_MAX_RATIO;
+  const upper = Math.min(CUE_MAX_RATIO, configured);
+  return { minRatio: lower, maxRatio: upper };
+}
+
+/**
+ * 是否处于「可以记压缩节点」的区间：minRatio ≤ 当前 < maxRatio。
+ * 上限不含压缩线本身 —— 到线该直接建议压缩，而不是记节点（工具也会拒绝）。
+ * @param {{ratio:number, minRatio:number, maxRatio: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;
+export function inCompressCueBand({ ratio, minRatio, maxRatio }) {
+  if (!Number.isFinite(ratio) || !Number.isFinite(minRatio) || !Number.isFinite(maxRatio)) return false;
+  return ratio >= minRatio && ratio < maxRatio;
 }
 
 /**
@@ -70,13 +101,13 @@ export function inCompressCueBand({ ratio, minRatio, compactRatio }) {
  *
  * @param {object} input
  * @param {number} input.ratio 当前上下文占用比例（0–1）
- * @param {number} input.minRatio 最小压缩线（compressionMinRatio 的结果）
- * @param {number} input.compactRatio 压缩提醒线（cfg.thresholds.compactRatio）
+ * @param {number} input.minRatio cue 区间下限（cueBandOf 的结果，已含动态最小线）
+ * @param {number} input.maxRatio cue 区间上限（cueBandOf 的结果，已含压缩线）
  * @param {{ratio:number}|null} [input.compressHint] 当前有效的「适合压缩」记录（没有为 null）
  * @returns {string}
  */
-export function compressCueText({ ratio, minRatio, compactRatio, compressHint = null }) {
-  if (!inCompressCueBand({ ratio, minRatio, compactRatio })) return '';
+export function compressCueText({ ratio, minRatio, maxRatio, compressHint = null }) {
+  if (!inCompressCueBand({ ratio, minRatio, maxRatio })) return '';
   // 刚记过断点：容量只涨了不到 10 个百分点 → 不重复提醒（模型已经判断过一次）。
   if (
     compressHint !== null &&
@@ -90,7 +121,8 @@ export function compressCueText({ ratio, minRatio, compactRatio, compressHint =
   // 的动态最小线是 33.569% —— 那样提示会自相矛盾（「约 30%（可压缩区间 33.6%–40%）」）。
   const shownRatio = Math.max(bucketRatio(ratio), minRatio);
   return (
-    `上下文容量约 ${formatPercent(shownRatio)}%（可压缩区间 ${formatPercent(minRatio)}%–${formatPercent(compactRatio)}%）。` +
-    '如果刚刚完成一个明确的任务/阶段（自然节点），调用 mark_compress_point 记录一个压缩节点；不确定就不用调。'
+    `上下文容量约 ${formatPercent(shownRatio)}%（可压缩区间 ${formatPercent(minRatio)}%–${formatPercent(maxRatio)}%）。` +
+    '如果你刚刚完成了一个明确阶段——功能已实现并验证 / 文档已交付 / 问题已定位并修复 / 准备交接——就在回复前调用一次 mark_compress_point 记录节点。' +
+    '不确定也建议调一次让工具判断：被拒绝不会改动历史、不影响会话。不处于阶段收尾就不用管这句。'
   );
 }

package/lib/core/handoff-doc.js

@@ -106,6 +106,7 @@ function siteLines(site) {
  * @param {number} [input.summaries] 原会话已发生的压缩摘要份数
  * @param {string} input.file 本文件绝对路径（写进文档头，方便回查）
  * @param {object} [input.site] 现场快照（dsh/site-info.buildSiteSnapshot 的产物）
+ * @param {number} [input.ordinal] 0.4 P2-2：本次是第几次交接（链式序号，首次 1）
  * @returns {string}
  */
 export function renderHandoffDoc({
@@ -117,6 +118,7 @@ export function renderHandoffDoc({
   summaries,
   file,
   site,
+  ordinal,
 }) {
   const lines = [
     '# 交接单',
@@ -125,6 +127,8 @@ export function renderHandoffDoc({
     ...siteLines(site),
     `- 原会话：${sourceSessionId ?? '未知'}`,
     `- 原会话标题：${sourceTitle ?? '（未命名）'}`,
+    // 0.4 P2-2：接力链元数据可读化——文档头直接写「第 N 次交接」，接手者不用解析标题。
+    ...(Number.isInteger(ordinal) && ordinal > 0 ? [`- 交接序号：第 ${ordinal} 次交接`] : []),
     `- 已压缩次数：${summaries ?? 0}`,
     `- 交接时已用容量：${pressure ?? '未知'}`,
     `- 交接单路径：${file ?? '（未落盘）'}`,

package/lib/core/handoff-edit.js

@@ -0,0 +1,86 @@
+/**
+ * 交接预览「两段可编辑」（0.4 P2-1）—— 纯函数，零依赖。
+ *
+ * 只有 `约束` / `下一步` 两段允许用户改；其它七段一律来自模型或程序，**前后端都不接受覆盖**。
+ * 校验口径（方案 P2-1）：
+ *  - 非法字段（程序生成段/拼错的段名/非对象）→ 抛 `actionError('edits', …)`，由 HTTP 适配层回 400；
+ *  - 值必须是字符串；trim 后为空 → 视为「没改」，回落生成后的原文（不覆盖）；
+ *  - 单段长度上限 `HANDOFF_EDIT_MAX_CHARS`，超限拒绝（不截断，避免用户以为保存成功）；
+ *  - 只有用户确认交接时才应用（本模块只算覆盖结果，不写盘）。
+ */
+import { actionError } from './errors.js';
+import { HANDOFF_EDITABLE_SECTIONS } from './handoff-spec.js';
+
+/** 单段编辑长度上限（字符）。 */
+export const HANDOFF_EDIT_MAX_CHARS = 4000;
+
+/**
+ * 校验并规整用户编辑。只返回「真正要覆盖」的段（空值已剔除）。
+ *
+ * @param {unknown} edits 客户端提交的 { 段标题: 文本 }
+ * @returns {Record<string, string>} 段标题 → trim 后的新正文（可能为空对象）
+ * @throws {Error & {code:'edits'}} 非法字段/类型/超长
+ */
+export function normalizeHandoffEdits(edits) {
+  if (edits === undefined || edits === null) return {};
+  if (typeof edits !== 'object' || Array.isArray(edits)) {
+    throw actionError('edits', '编辑内容必须是一个对象（只允许「约束」「下一步」两段）');
+  }
+  const allowed = new Set(HANDOFF_EDITABLE_SECTIONS);
+  const out = {};
+  for (const [title, raw] of Object.entries(edits)) {
+    if (!allowed.has(title)) {
+      const program = title === '当前进度' || title === '改过的文件' ? '（程序生成的段）' : '';
+      throw actionError(
+        'edits',
+        `只能编辑「${HANDOFF_EDITABLE_SECTIONS.join('」「')}」两段，不能改「${title}」${program}；其余段落由模型/程序生成`,
+      );
+    }
+    if (typeof raw !== 'string') {
+      throw actionError('edits', `「${title}」的编辑内容必须是字符串`);
+    }
+    const text = raw.trim();
+    if (text.length === 0) continue; // 空值回落原文
+    if (text.length > HANDOFF_EDIT_MAX_CHARS) {
+      throw actionError('edits', `「${title}」超过长度上限 ${HANDOFF_EDIT_MAX_CHARS} 字符（当前 ${text.length}）`);
+    }
+    out[title] = text;
+  }
+  return out;
+}
+
+/**
+ * 把编辑覆盖到生成后的九段上（只动可编辑段，返回新对象，不改入参）。
+ * @param {Record<string,string>} sections 生成后的九段（标题 → 正文）
+ * @param {Record<string,string>} edits normalizeHandoffEdits 的产物
+ * @returns {Record<string,string>} 覆盖后的九段（新对象）
+ */
+export function applyHandoffEdits(sections, edits) {
+  const source = sections !== null && typeof sections === 'object' ? sections : {};
+  const overrides = edits !== null && typeof edits === 'object' ? edits : {};
+  const out = { ...source };
+  for (const title of HANDOFF_EDITABLE_SECTIONS) {
+    const text = overrides[title];
+    if (typeof text === 'string' && text.trim().length > 0) out[title] = text.trim();
+  }
+  return out;
+}
+
+/**
+ * 预览接口给客户端的「可编辑段」信息（客户端只渲染这两段 textarea）。
+ * @param {Record<string,string>} sections 生成后的九段
+ * @returns {{titles:string[], maxChars:number, note:string, sections:Record<string,string>}}
+ */
+export function editableHandoffView(sections) {
+  const source = sections !== null && typeof sections === 'object' ? sections : {};
+  const picked = {};
+  for (const title of HANDOFF_EDITABLE_SECTIONS) {
+    picked[title] = typeof source[title] === 'string' ? source[title] : '';
+  }
+  return {
+    titles: [...HANDOFF_EDITABLE_SECTIONS],
+    maxChars: HANDOFF_EDIT_MAX_CHARS,
+    note: '只允许编辑这两段；总体目标 / 当前进度 / 改过的文件等由模型或程序生成，不能改（留空 = 使用原文）。',
+    sections: picked,
+  };
+}

package/lib/core/handoff-facts.js

@@ -17,7 +17,8 @@ function shortPath(file, cwd) {
  * @param {object|null} [facts.compressHint] 模型判断「这里适合压缩」的产物
  * @param {number} [facts.summaries] 已压缩次数
  * @param {number|null} [facts.pressure] 已用容量（token）
- * @param {{count:number, seqs:number[]}|null} [facts.pins] 锁定消息
+ * @param {{count:number, seqs:number[], anchors?:Array<{seq:number,role:string,snippet:string}>}|null} [facts.pins]
+ *   锁定消息；anchors 是「保留契约」锚点（seq + 角色 + 一句摘要，≤60 字符，不贴全文）
  * @param {string[]} [facts.changedFiles] 本会话写/改过的文件
  * @param {object|null} [facts.site] buildSiteSnapshot 的产物
  * @returns {Record<string,string>} 标题 → 正文
@@ -32,8 +33,22 @@ export function buildHandoffProgramSections(facts = {}) {
     `- 已压缩：${Number.isFinite(summaries) ? summaries : 0} 次`,
     `- 已用容量：${Number.isFinite(pressure) ? pressure : '未知'}`,
     `- 锁定消息：${pins !== null && pins !== undefined && Number.isFinite(pins.count) ? `${pins.count} 条` : '无'}`,
-    `- 后台任务：${jobs.length === 0 ? '无' : `${jobs.length} 个可能仍在运行`}`,
   ];
+  // 0.4 P1-2：pin 作为「保留契约」——在「当前进度」程序段里列出锚点（seq + 角色 + 一句摘要）。
+  // 不动九段结构（仍是 9 个 ## 段），因为这是程序收集的事实，属于「当前进度」的一部分。
+  const pinAnchors =
+    pins !== null && pins !== undefined && Array.isArray(pins.anchors) ? pins.anchors.filter((anchor) => anchor !== null && typeof anchor === 'object') : [];
+  if (pinAnchors.length > 0) {
+    progressLines.push('- 锁定锚点（保留契约，接手者请原样保留这些消息）：');
+    for (const anchor of pinAnchors.slice(0, 10)) {
+      progressLines.push(`  - seq ${anchor.seq} · ${anchor.role} · 「${anchor.snippet}」`);
+    }
+    if (pinAnchors.length > 10) {
+      progressLines.push(`  - …另有 ${pinAnchors.length - 10} 条锁定未列出（会话内 /pin list 可看全）`);
+    }
+    progressLines.push('- 说明：以上锚点是「保留意图」的声明；跨引擎压缩器是否遵守取决于其实现。');
+  }
+  progressLines.push(`- 后台任务：${jobs.length === 0 ? '无' : `${jobs.length} 个可能仍在运行`}`);
   if (site !== null && typeof site === 'object' && typeof site.cwd === 'string') {
     progressLines.push(`- 工作目录：${site.cwd}`);
   }

package/lib/core/handoff-spec.js

@@ -21,6 +21,8 @@ export const HANDOFF_SPEC = Object.freeze([
     title: '约束',
     owner: 'model',
     required: true,
+    // 0.4 P2-1：只有这两段允许用户在手改预览里编辑（其余段一律程序/模型写，前后端都不接受覆盖）。
+    editable: true,
     hint: '不能违反的边界：权限/安全/用户明确要求/禁止事项',
   },
   {
@@ -70,6 +72,7 @@ export const HANDOFF_SPEC = Object.freeze([
     title: '下一步',
     owner: 'model',
     required: true,
+    editable: true,
     hint: '接手者第一步做什么；可执行、别写「继续努力」',
   },
 ]);
@@ -87,6 +90,21 @@ export const HANDOFF_PROGRAM_SECTIONS = Object.freeze(
   HANDOFF_SPEC.filter((section) => section.owner === 'program').map((section) => section.title),
 );
 
+/** 0.4 P2-1：允许用户编辑的段落标题（当前只有「约束」「下一步」）。 */
+export const HANDOFF_EDITABLE_SECTIONS = Object.freeze(
+  HANDOFF_SPEC.filter((section) => section.editable === true).map((section) => section.title),
+);
+
+/**
+ * 把「标题 → 正文」按九段规格顺序拼成 markdown（段落顺序/标题的唯一渲染口径）。
+ * @param {Record<string, string>} sections
+ * @returns {string}
+ */
+export function composeHandoffText(sections) {
+  const source = sections !== null && typeof sections === 'object' ? sections : {};
+  return HANDOFF_SPEC.map((spec) => `## ${spec.title}\n${String(source[spec.title] ?? '').trim()}`).join('\n\n');
+}
+
 /** 按标题查规格；找不到返回 null。 */
 export function handoffSpecOf(title) {
   return HANDOFF_SPEC.find((section) => section.title === title) ?? null;

package/lib/core/ledger.js

@@ -0,0 +1,176 @@
+/**
+ * 轻账本（0.4 P1-3）—— 压缩/交接「可审计流水」的**纯数据层**（零 IO、零依赖）。
+ *
+ * 只做三件事：
+ *  1. `buildLedgerRecord(input)`：按 allowlist 构造一条记录（只收数值/枚举/时间/交接单路径；
+ *     **绝不收消息原文、摘要、交接单正文、sessionId、cwd、用户名**等隐私内容）；
+ *  2. `normalizeLedgerRecord(raw)` / `parseLedgerLines(text)`：读侧容错——坏行/坏记录直接跳过，
+ *     让损坏文件永远不会影响宿主动作；
+ *  3. `summarizeLedgerRecords(records)`：设置页那一行累计数字（次数 / 腾出 tokens / 平均耗时）。
+ *
+ * 文件读写在 `dsh/ledger.js`；本模块可裸跑单测。
+ */
+
+/** 账本 schema 版本（JSONL 每行一个对象）。 */
+export const LEDGER_SCHEMA = 'dcr-ledger/v1';
+
+/** 保留的最近条数上限（超过就裁掉最旧的）。 */
+export const LEDGER_MAX_ENTRIES = 200;
+
+/** 允许的 kind。 */
+export const LEDGER_KINDS = Object.freeze(['compact', 'handoff']);
+
+function finiteOrNull(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/** token 数：非负整数（>2^53 的怪值也夹住，防手滑）。 */
+function tokensOrNull(value) {
+  const number = finiteOrNull(value);
+  if (number === null) return null;
+  return Math.max(0, Math.min(Number.MAX_SAFE_INTEGER, Math.round(number)));
+}
+
+/** 比例：0–1，保留 3 位小数。 */
+function ratioOrNull(value) {
+  const number = finiteOrNull(value);
+  if (number === null) return null;
+  return Math.round(Math.min(1, Math.max(0, number)) * 1000) / 1000;
+}
+
+/** 耗时 ms：非负整数。 */
+function durationOrNull(value) {
+  const number = finiteOrNull(value);
+  if (number === null) return null;
+  return Math.max(0, Math.round(number));
+}
+
+/** 单行文本（路径/id 用）：折叠空白 + 截断；空串 → null。 */
+function lineOrNull(value, maxChars) {
+  if (typeof value !== 'string') return null;
+  const text = value.replace(/\s+/gu, ' ').trim();
+  if (text.length === 0) return null;
+  return text.length > maxChars ? `${text.slice(0, maxChars - 1)}…` : text;
+}
+
+/**
+ * 构造一条账本记录；kind 非法返回 null（调用方静默丢弃）。
+ *
+ * @param {object} input
+ * @param {'compact'|'handoff'} input.kind
+ * @param {string} [input.at] 本地 ISO 时间（由 dsh/ledger 注入；纯函数这里只做字符串校验）
+ * @param {number} [input.durationMs]
+ * @param {number|null} [input.beforeTokens]
+ * @param {number|null} [input.afterTokens]
+ * @param {number|null} [input.beforeRatio]
+ * @param {number|null} [input.afterRatio]
+ * @param {{inRange?:number|null, total?:number|null}|null} [input.pinHits]
+ * @param {{path?:string, childId?:string, started?:boolean}|null} [input.handoff] 仅交接记录
+ * @returns {object|null}
+ */
+export function buildLedgerRecord(input) {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) return null;
+  const kind = LEDGER_KINDS.includes(input.kind) ? input.kind : null;
+  if (kind === null) return null;
+
+  const beforeTokens = tokensOrNull(input.beforeTokens);
+  const afterTokens = tokensOrNull(input.afterTokens);
+  // 「腾出」= 压前 - 压后；拿不到两个数就 null（不猜）。
+  const freedTokens = beforeTokens !== null && afterTokens !== null ? Math.max(0, beforeTokens - afterTokens) : null;
+  const pinSource = input.pinHits !== null && typeof input.pinHits === 'object' ? input.pinHits : {};
+  const pinInRange = tokensOrNull(pinSource.inRange);
+  const pinTotal = tokensOrNull(pinSource.total);
+  const handoffSource = input.handoff !== null && typeof input.handoff === 'object' ? input.handoff : null;
+
+  return {
+    schema: LEDGER_SCHEMA,
+    kind,
+    at: lineOrNull(input.at, 40),
+    durationMs: durationOrNull(input.durationMs),
+    beforeTokens,
+    afterTokens,
+    freedTokens,
+    beforeRatio: ratioOrNull(input.beforeRatio),
+    afterRatio: ratioOrNull(input.afterRatio),
+    pinHits: { inRange: pinInRange, total: pinTotal },
+    handoff:
+      kind === 'handoff' && handoffSource !== null
+        ? {
+            // 只记路径（任务要求）与短 id/布尔；不记交接单正文。
+            path: lineOrNull(handoffSource.path, 500),
+            childId: lineOrNull(handoffSource.childId, 120),
+            started: typeof handoffSource.started === 'boolean' ? handoffSource.started : null,
+          }
+        : null,
+  };
+}
+
+/**
+ * 读侧单条记录容错：形状不对/kind 非法 → null（该行跳过）。
+ * @param {unknown} raw
+ * @returns {object|null}
+ */
+export function normalizeLedgerRecord(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (raw.schema !== LEDGER_SCHEMA) return null;
+  return buildLedgerRecord(raw);
+}
+
+/**
+ * 解析 JSONL 文本：逐行 JSON.parse，坏行/坏记录跳过（损坏文件静默降级）。
+ * @param {string} text
+ * @returns {object[]}
+ */
+export function parseLedgerLines(text) {
+  if (typeof text !== 'string' || text.length === 0) return [];
+  const records = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      continue; // 坏行（半截写/手改）直接跳过
+    }
+    const record = normalizeLedgerRecord(parsed);
+    if (record !== null) records.push(record);
+  }
+  return records;
+}
+
+/**
+ * 设置页「一行累计数字」的数据（与账本同源，可直接对照）。
+ *
+ * @param {object[]} records 账本记录（已按时间顺序）
+ * @returns {{count:number, compactCount:number, handoffCount:number, freedTokens:number, avgDurationMs:number|null, lastAt:string|null}}
+ */
+export function summarizeLedgerRecords(records) {
+  const list = Array.isArray(records) ? records.filter((record) => record !== null && typeof record === 'object') : [];
+  let compactCount = 0;
+  let handoffCount = 0;
+  let freedTokens = 0;
+  let durationSum = 0;
+  let durationCount = 0;
+  let lastAt = null;
+  for (const record of list) {
+    if (record.kind === 'compact') compactCount += 1;
+    else if (record.kind === 'handoff') handoffCount += 1;
+    if (typeof record.freedTokens === 'number' && Number.isFinite(record.freedTokens) && record.freedTokens > 0) {
+      freedTokens += record.freedTokens;
+    }
+    if (typeof record.durationMs === 'number' && Number.isFinite(record.durationMs) && record.durationMs >= 0) {
+      durationSum += record.durationMs;
+      durationCount += 1;
+    }
+    if (typeof record.at === 'string' && record.at.length > 0) lastAt = record.at;
+  }
+  return {
+    count: compactCount + handoffCount,
+    compactCount,
+    handoffCount,
+    freedTokens,
+    avgDurationMs: durationCount === 0 ? null : Math.round(durationSum / durationCount),
+    lastAt,
+  };
+}

package/lib/core/native-line.js

@@ -0,0 +1,65 @@
+/**
+ * 0.4 P2-3：DSH 原生自动压缩的**真实触发线**（纯函数，零依赖）。
+ *
+ * 背景（BUG-012 后续 / Win 真实会话 session-1f90f5ee）：
+ * 指示灯过去把 compaction-basic 的 `thresholdRatio` 直接当触发线显示（默认 80%），
+ * 但 DSH 实际判断压力用的是 token 数，公式（见 dsh-compaction-basic 源码）：
+ *
+ *   messageBudgetTokens  = contextWindow − reservedCompletionTokens
+ *   pressureBudgetTokens = messageBudgetTokens − headroomTokens
+ *   thresholdTokens      = floor(min(contextWindow × thresholdRatio, pressureBudgetTokens))
+ *   真实触发点           = thresholdTokens / contextWindow
+ *
+ * 其中：
+ *   - contextWindow：路由模型的上下文窗口（dcr 已从 ctx.llm.resolveModelInfo 拿到）；
+ *   - reservedCompletionTokens：该次路由请求给输出预留的 token 数
+ *     = session.requestHeader().config.maxTokens ?? 适配器 defaultMaxTokens ?? 0；
+ *   - headroomTokens：compaction-basic 的余量（默认 65536，可被全局或 modelPolicies 覆盖）。
+ *
+ * 只有 `min` 的第二项更小时（输出预留 + 余量把可用空间压下去），真实线才低于
+ * 窗口比例；这时显示「原生自动压缩线 67.8%」而不是 80%。
+ */
+
+/** compaction-basic 的 headroomTokens 默认值（源码：?? 65536）。 */
+export const NATIVE_HEADROOM_DEFAULT = 65536;
+
+/**
+ * 计算真实触发线。
+ *
+ * @param {object} input
+ * @param {number} input.contextWindow 路由上下文窗口（>0 的整数）
+ * @param {number} [input.reservedCompletionTokens] 路由输出预留（缺省 0）
+ * @param {number} input.thresholdRatio compaction-basic 有效窗口比例（0–1）
+ * @param {number} [input.headroomTokens] 余量（缺省 NATIVE_HEADROOM_DEFAULT）
+ * @returns {{ok:boolean, reason:string|null, thresholdTokens:number|null, ratio:number|null, pressureBudgetTokens:number|null, messageBudgetTokens:number|null}}
+ *   ok=false 时 thresholdTokens/ratio 为 null，reason 说明原因（input/no-budget/overflow）
+ */
+export function nativeLineOf({ contextWindow, reservedCompletionTokens, thresholdRatio, headroomTokens } = {}) {
+  const window = contextWindow;
+  if (!Number.isFinite(window) || window <= 0) {
+    return { ok: false, reason: 'input', thresholdTokens: null, ratio: null, pressureBudgetTokens: null, messageBudgetTokens: null };
+  }
+  const ratioCfg = thresholdRatio;
+  if (!Number.isFinite(ratioCfg) || ratioCfg <= 0 || ratioCfg > 1) {
+    return { ok: false, reason: 'input', thresholdTokens: null, ratio: null, pressureBudgetTokens: null, messageBudgetTokens: null };
+  }
+  const reserved = Number.isFinite(reservedCompletionTokens) && reservedCompletionTokens >= 0 ? reservedCompletionTokens : 0;
+  const headroom = Number.isFinite(headroomTokens) && headroomTokens >= 0 ? headroomTokens : NATIVE_HEADROOM_DEFAULT;
+  const messageBudget = window - reserved;
+  const pressureBudget = messageBudget - headroom;
+  if (pressureBudget <= 0) {
+    return { ok: false, reason: 'no-budget', thresholdTokens: null, ratio: null, pressureBudgetTokens: pressureBudget, messageBudgetTokens: messageBudget };
+  }
+  const threshold = Math.floor(Math.min(window * ratioCfg, pressureBudget));
+  if (!(threshold > 0) || threshold >= window) {
+    return { ok: false, reason: 'overflow', thresholdTokens: threshold, ratio: null, pressureBudgetTokens: pressureBudget, messageBudgetTokens: messageBudget };
+  }
+  return {
+    ok: true,
+    reason: null,
+    thresholdTokens: threshold,
+    ratio: threshold / window,
+    pressureBudgetTokens: pressureBudget,
+    messageBudgetTokens: messageBudget,
+  };
+}

package/lib/core/pin-anchors.js

@@ -0,0 +1,93 @@
+/**
+ * pin 锚点 / 消息摘要 —— 纯函数，零依赖（0.4 P1-1 / P1-2）。
+ *
+ * 三处展示共用同一份「怎么从会话事件里取一句可读短摘要 + 角色」的实现：
+ *  1. `/pin list` 的候选列表（actions/pin.js，0.3.1 起就有这段逻辑，挪到这里收口）；
+ *  2. 压缩预览的「建议锁定」候选（core/pin-suggest.js，P1-1）；
+ *  3. 交接单的「锁定锚点（保留契约）」段（core/handoff-facts.js，P1-2）。
+ *
+ * 只做展示：摘要截断到一句（默认 60 字符，不贴原文全文），不读全量历史、不调模型。
+ */
+
+/** 事件类型 → 中文角色标签（唯一来源）。 */
+export const ROLE_LABELS = Object.freeze({
+  'system/message': '系统',
+  'user/message': '用户',
+  'assistant/message': '助手',
+  'tool/result': '工具',
+});
+
+/**
+ * @param {string|undefined} type 事件类型
+ * @returns {string} 角色标签；未知类型返回「其他」
+ */
+export function roleLabelOf(type) {
+  return ROLE_LABELS[type] ?? '其他';
+}
+
+/**
+ * 从事件里抠出纯文本（消息 content 可能是字符串，也可能是 text block 数组）。
+ *
+ * DSH v4：user/message 的 data 本身就是消息（{role,content,source}），
+ * 只有 system/assistant/tool 包在 data.message 里。2026-10-19 debug 实测：
+ * 只读 data.message 会让用户消息全部显示「（无文本）」。
+ *
+ * @param {object|undefined|null} event
+ * @returns {string} 空白折叠后的文本；没有文本返回 ''
+ */
+export function messageTextOf(event) {
+  const content = event?.data?.content ?? event?.data?.message?.content;
+  let text = '';
+  if (typeof content === 'string') text = content;
+  else if (Array.isArray(content)) {
+    text = content
+      .filter((block) => block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string')
+      .map((block) => block.text)
+      .join(' ');
+  }
+  return text.replace(/\s+/gu, ' ').trim();
+}
+
+/**
+ * 一句可读摘要：折叠空白 + 截断（默认 60 字符，超长加省略号）。
+ * @param {object|undefined|null} event
+ * @param {number} [maxChars]
+ * @returns {string} 没有文本返回 ''
+ */
+export function messageSnippetOf(event, maxChars = 60) {
+  const text = messageTextOf(event);
+  if (text.length === 0) return '';
+  const limit = Number.isInteger(maxChars) && maxChars > 1 ? maxChars : 60;
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+
+/**
+ * 是不是「真正的用户消息」：user/message 且 source 缺失（老夹具/测试）或 source.kind==='user'。
+ *
+ * 运行时合成的 user/message（runtime-context / time-context / compact-checkpoint 等）
+ * source.kind 不是 'user'，不该被当成「用户明确要求」去做建议锁定/保留锚点。
+ * @param {object|undefined|null} event
+ * @returns {boolean}
+ */
+export function isUserAuthoredMessage(event) {
+  if (event?.type !== 'user/message') return false;
+  const source = event?.data?.source;
+  if (source === undefined || source === null) return true;
+  return source.kind === 'user';
+}
+
+/**
+ * 一个 pin 锚点：seq + 角色 + 一句摘要（不贴全文）。
+ * @param {object|undefined|null} event
+ * @param {{maxChars?:number}} [options]
+ * @returns {{seq:number, role:string, snippet:string}|null} 没有可用 seq 返回 null
+ */
+export function pinAnchorOf(event, { maxChars = 60 } = {}) {
+  const seq = event?.seq;
+  if (!Number.isInteger(seq) || seq < 0) return null;
+  return {
+    seq,
+    role: roleLabelOf(event.type),
+    snippet: messageSnippetOf(event, maxChars) || '（无文本）',
+  };
+}