dsh-jev-prune 0.1.0

package/src/receipt.js

@@ -0,0 +1,800 @@
+/**
+ * receipt.js —— 第二层：**整对调用的「回执压缩」**（纯函数，无 DSH 依赖）。
+ *
+ * 第一层（prune.js）只裁工具结果的**正文**，调用记录与结果的外壳都留着。
+ * 这一层把**整个工具调用对**（assistant 消息里的 tool-call + 对应的 tool/result）
+ * 移出 surface，用一个**确定性回执**顶替原本由模型写的摘要。
+ *
+ * 为什么值得做：
+ *   DSH 自带的压缩会让主模型读原始历史、**写一段摘要**。摘要会幻觉——它可能写出
+ *   「我们确认了 bug 在 X」这种历史里并没有的断言。而回执的每一行都是代码算出来的
+ *   事实（工具名、命令、路径、字符数、seq），**不可能包含模型推断**。
+ *   代价是它不解释、不总结——它是一个**可索引的收据**，不是一个摘要。
+ *
+ * 为什么敢删整对：
+ *   ① 原始事件仍在会话日志里（`compactRegion` 只把它们移出 surface，不销毁）
+ *   ② 回执**逐字记录了命令/路径**，所以"发生过什么副作用"这个事实不会丢
+ *   ③ 只处理只读探查类工具，且 Jev 必须同时判定"结果可丢"且"没有副作用"
+ *
+ * 为什么不能随便删（实测教训，见 README）：
+ *   · `Edit`/`Write` 这类改写型调用是承重信息，判错一次就丢失关键改动 → 硬规则排除
+ *   · 含 error/assert/fail 等**证据词**的结果可能正是根因所在 → 证据守卫生效时不删
+ *   · 落在最近 compactPreserveRecent 个节点内的（含正在进行的调用）→ 一律不碰
+ *   · 有**副作用**的调用（写文件、提交、安装、删除）→ 结果可能很短，但"发生过"是承重的
+ *
+ * 工具配对平衡：镜像 DSH 的 `@deepseek-ai/dsh-compaction/tool-pairing`。
+ * `compactRegion` 会在服务端再做一次同样的校验并抛错；我们自己先算一遍，
+ * 是为了**在花钱之前**就把非法范围筛掉，而不是等 API 报错。
+ */
+
+import { cachedVerdictForEvent, countChars, isToolIn, normalizeToolName } from './prune.js'
+
+// 归一化工具在 prune.js（依赖链最底层）——两层的安全黑名单共用同一套比较。
+// 这里转出以保持既有 import 路径（check.js / 调用方）不变。
+export { cachedVerdictForEvent, isToolIn, normalizeToolName }
+
+/** 回执文本的识别前缀（用于判断某个 checkpoint 是不是我们写的）。 */
+export const RECEIPT_MARKER = '[已压缩 · 确定性回执]'
+
+/**
+ * 真实 DSH 只读探查类工具名（**取证得到，不是猜的**：解压会话日志读到的是 `read` / `glob` / `grep`）。
+ *
+ * ⚠️ **刻意不含 shell**（`pwsh` / `bash` / `sh` / `shell`）：shell 能做任何事，
+ * `pwsh: Remove-Item important.txt` 就是合法调用 —— 外部审查复现过这个案例。
+ * "整对移出 shell 调用"不是只读安全操作，哪怕回执逐字记录了命令。
+ *
+ * 这份清单就是 `DEFAULT_COMPACT_TOOLS` 的内容（默认生效）。
+ * 想放宽就把它配成 `[]`（只受 neverCompactTools 约束）—— 那是显式 opt-in 的不安全模式。
+ *
+ * 历史教训（保留给维护者）：我最初把 Claude Code 风格的 PascalCase 名字当默认白名单，
+ * 在真实 DSH 里**命中 0/11** —— 第二层静默地永不触发。所以白名单比较必须走
+ * `normalizeToolName`，且命中/拦截的名字都要进 `selectReceiptRanges` 的 stats 上报，
+ * 让"白名单没配上"可观测。
+ */
+export const DSH_READONLY_TOOLS = [
+  'read', 'view', 'cat', 'glob', 'grep', 'list', 'ls', 'search', 'find', 'tree', 'stat',
+  'fetch', 'websearch', 'web_search',
+  'getcontent', 'getchilditem', 'getitem', 'selectstring', 'testpath', 'measureobject', 'resolvepath',
+]
+
+/** 默认白名单 = 上面的只读工具集（安全默认）。设为 `[]` 可放宽为只受黑名单约束。 */
+export const DEFAULT_COMPACT_TOOLS = [...DSH_READONLY_TOOLS]
+
+/**
+ * 相对分位模式需要的**最小总体规模**；低于它则降级为绝对下限模式（见 computeEligibleSeqs）。
+ * 独立导出是为了让 index.js 的 schema 与 receipt.js 的运行时兜底共用同一个数字——
+ * 两处各写一个字面量的话，改一处就会漂移。
+ */
+export const DEFAULT_MIN_CANDIDATES_FOR_RELATIVE = 4
+
+/**
+ * 降级模式（总体 < 上面那个数）的**绝对下限阈值**。明显严于 compactThreshold(0.5)：
+ * 没有相对排序信息时，只能靠"概率本身够不够低"来替代，所以阈值必须更保守。
+ */
+export const DEFAULT_FLOOR_THRESHOLD = 0.2
+
+/** 降级模式仍要求的最低样本量：低于它连"分布"都谈不上，宁可不做。 */
+export const DEFAULT_MIN_CANDIDATES_FOR_FLOOR = 2
+
+/**
+ * 证据守卫必须扫描当前结果及其完整来源链。
+ *
+ * 第一层会把超长 tool/result 替换成“头 + 标记 + 尾”；若 error/assert/fail 恰好位于
+ * 被截掉的中间，只扫描 replacement 会让第二层的确定性守卫失明。DSH 保留所有旧事件，
+ * 且 replacement 通过 sourceEventSeqs 指回它们，所以这里沿来源链取回原文。
+ */
+function resultEvidenceText(eventAt, startSeq) {
+  const pending = [startSeq]
+  const seen = new Set()
+  const texts = []
+  while (pending.length > 0) {
+    const seq = pending.pop()
+    if (seen.has(seq)) continue
+    seen.add(seq)
+    const event = eventAt(seq)
+    if (event == null) continue
+    if (event.type === 'tool/result') texts.push(resultText(event))
+    for (const sourceSeq of event.sourceEventSeqs ?? []) pending.push(sourceSeq)
+  }
+  return texts.join('\n')
+}
+
+/**
+ * 永不**整对移出**的工具（第二层黑名单）：改写型调用是承重信息
+ * （第一版实测 Jev 误删过 Edit）。比较时归一化。
+ *
+ * 为什么必须与第一层的默认黑名单分开（issue #31）：两层的破坏性根本不同。
+ * 第一层只是**截断**——原文留在会话日志里，仍有损但可逆；
+ * 第二层是**整对移出**——调用与结果一起从 surface 上消失。
+ *
+ * 而这一组里两者兼有：`Write` / `NotebookEdit`（参数含完整内容）确实该两层都守；
+ * `Edit` / `MultiEdit` / `ApplyPatch` / `str_replace_*` / `apply_patch` 的参数
+ * 只是 **find/replace 差异**，第一层截掉的往往正是那段差异——但截断仍能靠重读文件
+ * 恢复；整对移出则会把"我改了什么"这个事实一起抹掉。
+ *
+ * 所以第二层保留全部，第一层放宽到只守"参数即内容"的那两个。
+ * 共用同一个常量会让第一层的意图（尽量多裁）被第二层的意图（尽量少删）绑住。
+ */
+export const DEFAULT_NEVER_COMPACT_TOOLS = [
+  'Edit', 'Write', 'MultiEdit', 'ApplyPatch', 'NotebookEdit',
+  'str_replace_editor', 'str_replace_based_edit_tool', 'apply_patch',
+]
+
+/**
+ * 第一层（截断）永不触碰的工具。比第二层黑名单**窄**：只守住"参数本身就是内容"
+ * 的写文件类工具——截掉它们的入参等于把写进去的内容丢了，且日志里未必还有第二份。
+ * 差异型编辑工具（Edit 等）的参数是 diff，第一层截断后靠重读文件可以恢复，
+ * 因此不在这里（第二层仍然守）。
+ */
+export const DEFAULT_NEVER_PRUNE_TOOLS = ['Write', 'NotebookEdit']
+
+/**
+ * 证据守卫的默认词表。命中即**不整对删除**（仍允许第一层截断，那是有损但可逆的）。
+ * 方向性说明：这里宁可误守（少省一点）也不能漏守（丢证据）。
+ * 命中数量会如实上报到状态里，如果发现守得过宽可以直接改配置。
+ * 匹配口径见 scanEvidence —— 要求命中落在标识符段开头，所以 `bug` 不会被 `debug` 触发。
+ */
+export const DEFAULT_EVIDENCE_PATTERNS = [
+  'error', 'exception', 'traceback', 'stack trace', 'assertion',
+  'failed', 'fail:', 'panic', 'unexpected', 'mismatch',
+  'todo', 'fixme', 'bug',
+]
+
+// ---------------------------------------------------------------- 工具配对平衡
+
+/** 一个 surface 事件对"未闭合工具调用数"的增量（与 DSH 同口径）。 */
+export function eventDelta(event) {
+  if (event?.type === 'assistant/message') {
+    const content = event.data?.message?.content
+    if (!Array.isArray(content)) return 0
+    return content.filter((block) => block?.type === 'tool-call').length
+  }
+  if (event?.type === 'tool/result') return -1
+  return 0
+}
+
+/**
+ * 计算每个切点的平衡性。N 个 surface 节点有 N+1 个切点：
+ * 下标 i 表示"第 i 个节点之前"的切点，下标 N 表示"尾部之后"。
+ *
+ * @returns {Array<{balanced:boolean, inProgress:number}>} 长度为 N+1
+ * @throws 当 surface 损坏（节点的 seq 无对应事件 / 出现无主的 tool/result）时
+ */
+export function computeCuts(surface, eventAt) {
+  const cuts = [{ balanced: true, inProgress: 0 }]
+  let inProgress = 0
+  for (const seq of surface) {
+    const event = eventAt(seq)
+    if (event == null || event.seq !== seq) {
+      throw new Error(`tool-pairing: surface seq ${seq} 没有对应的会话事件（surface 损坏）`)
+    }
+    inProgress += eventDelta(event)
+    if (inProgress < 0) {
+      throw new Error(`tool-pairing: surface seq ${seq} 的 tool/result 没有对应的 tool-call（surface 损坏）`)
+    }
+    cuts.push({ balanced: inProgress === 0, inProgress })
+  }
+  return cuts
+}
+
+/** 第 index 个节点之前的切点是否平衡（等价于 DSH 的 toolPairingBalancedBefore）。 */
+export function balancedBefore(cuts, index) {
+  return cuts[index]?.balanced === true
+}
+
+/** 第 index 个节点之后的切点是否平衡（等价于 DSH 的 toolPairingBalancedAfter）。 */
+export function balancedAfter(cuts, index) {
+  return cuts[index + 1]?.balanced === true
+}
+
+// ---------------------------------------------------------------- 事件解析
+
+/** assistant 消息里的 tool-call 块（带 seq 以便定位）。 */
+function toolCallsOf(event) {
+  if (event?.type !== 'assistant/message') return []
+  const content = event.data?.message?.content
+  if (!Array.isArray(content)) return []
+  return content.filter((block) => block?.type === 'tool-call')
+}
+
+function toolCallIdOf(block) {
+  return block?.id ?? block?.callId ?? block?.toolCallId ?? null
+}
+
+function resultCallIdOf(event) {
+  return event?.data?.message?.source?.callId ?? event?.data?.callId ?? null
+}
+
+/**
+ * 按块类型分别统计 assistant 消息的字符数。
+ *
+ * ⚠️ **text 与 reasoning 必须分开统计、分开设阈值**（这是 issue #26 的修复）。
+ *
+ * 历史经过（保留给维护者，避免又合并回去）：
+ *   最初只数 `text` —— 实测 DSH 的 assistant 消息块是 `[reasoning, tool-call]`，
+ *   模型把思考写在 reasoning 里、text 常常只有一句"看一下。"，于是门控形同虚设，
+ *   一条思考了两千字的步骤会被当成纯探查删掉。于是改成"text + reasoning 累加"。
+ *   但两者**性质完全不同**：`text` 是用户可见的结论/说明（长 = 有信息量，该守），
+ *   `reasoning` 是模型的草稿（长 = 想得多，**不代表这一步有承重信息**）。
+ *   合并累加的直接后果是阈值被 reasoning 主导：实测 DeepSeek 单步
+ *   text 0~287、reasoning 0~1207 字符，合并后卡在 1200 的右端——
+ *   **只要模型在思考上多花点字，第二层整层静默关闭**（实测 reasoning=1300 时
+ *   10 步里合格 0 步，且无任何日志提示是这道门导致的）。
+ *   分开之后，各自按自己的分布标定，两个信号互不污染。
+ *
+ * @returns {{text:number, reasoning:number}} 各自独立的字符数（码点计）
+ */
+function assistantBlockChars(event) {
+  const content = event.data?.message?.content
+  if (!Array.isArray(content)) return { text: 0, reasoning: 0 }
+  let text = 0
+  let reasoning = 0
+  for (const block of content) {
+    if (typeof block?.text !== 'string') continue
+    const chars = Array.from(block.text).length
+    if (block.type === 'text') text += chars
+    else if (block.type === 'reasoning') reasoning += chars
+  }
+  return { text, reasoning }
+}
+
+/** tool-call 块的 id（不同版本字段名不同，逐个容忍）。
+ *  已删除：callBlockId 此前导出但全仓无引用（issue #14 死代码）。 */
+
+/**
+ * 把一次调用的入参渲染成一行可读文本。
+ *
+ * 先取"最有信息量"的字段（命令 / 路径 / 模式），再补上**取值很短的其它字段**
+ * （例如 Bash 的 `cwd`）—— 后者对"能不能重跑这条命令"是必要的，不该被静默丢掉。
+ * 体积型字段（正文/替换内容/子任务提示词）刻意跳过：那些是载荷，不是可复现性信息。
+ */
+const ARG_PRIORITY = ['command', 'file_path', 'notebook_path', 'pattern', 'query', 'path', 'url', 'glob']
+const ARG_IGNORED = new Set(['content', 'old_string', 'new_string', 'prompt', 'description'])
+const ARG_SECONDARY_MAX_CHARS = 40
+
+export function renderCallArgs(block, maxChars = 120) {
+  let args = block?.arguments
+  if (typeof args === 'string') {
+    try {
+      args = JSON.parse(args)
+    } catch {
+      return clip(args, maxChars)
+    }
+  }
+  if (args == null) return ''
+  if (typeof args !== 'object') return clip(String(args), maxChars)
+
+  const parts = []
+  const used = new Set()
+  for (const key of ARG_PRIORITY) {
+    if (args[key] == null) continue
+    parts.push(String(args[key]))
+    used.add(key)
+    if (parts.length >= 3) break
+  }
+  if (parts.length < 3) {
+    for (const [key, value] of Object.entries(args)) {
+      if (used.has(key) || ARG_IGNORED.has(key) || value == null) continue
+      const text = String(value)
+      if (text.length > ARG_SECONDARY_MAX_CHARS) continue
+      // 次要字段带 key 前缀：不写 key 的话，光看值不知道它是哪个参数
+      parts.push(`${key}=${text}`)
+      if (parts.length >= 3) break
+    }
+  }
+  if (parts.length === 0) {
+    // 没有任何可用字段（全是载荷型）→ 整体序列化，至少让形状可见
+    return clip(JSON.stringify(args), maxChars)
+  }
+  return clip(parts.join(' '), maxChars)
+}
+
+function clip(text, maxChars) {
+  const value = String(text ?? '').replace(/\s+/g, ' ').trim()
+  const points = Array.from(value)
+  if (points.length <= maxChars) return value
+  return `${points.slice(0, maxChars).join('')}…`
+}
+
+// ---------------------------------------------------------------- 证据守卫
+
+/**
+ * 找出文本命中的证据词。
+ *
+ * 匹配口径：命中必须落在**一个标识符段的开头** —— 串首、非字母数字之后，
+ * 或者驼峰分界（小写字母之后的大写开头）。这样：
+ *   · `TypeError` 里的 `error` 命中（真证据）
+ *   · `debug` / `__debug__` / `this.debug` 里的 `bug` **不**命中（子串误报，issue #1）
+ * 为什么不是"整词匹配"（词首词尾都要求边界）：那会让 `errors`、`bugfix`、
+ * `failures` 这类真证据一起漏掉，而本守卫的方向性是宁可误守也不能漏守。
+ * 代价是 `myerror` 这种无分隔符的复合标识符不再命中 —— 与 `debug` 同类，属于有意取舍。
+ *
+ * @returns {{hit:boolean, matches:string[]}}
+ */
+export function scanEvidence(text, patterns) {
+  const haystack = String(text ?? '') // 保持原始大小写：驼峰分界只能对原文判定
+  const matches = []
+  for (const pattern of patterns ?? []) {
+    const needle = String(pattern).toLowerCase()
+    if (needle.length === 0) continue
+    const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const atSegmentStart = new RegExp(`(?<=^|[^A-Za-z0-9])${escaped}`, 'i')
+    const camelFirst = escaped.charAt(0).toUpperCase() + escaped.slice(1)
+    const atCamelBoundary = new RegExp(`(?<=[a-z])${camelFirst}`)
+    if (atSegmentStart.test(haystack) || atCamelBoundary.test(haystack)) matches.push(needle)
+  }
+  return { hit: matches.length > 0, matches }
+}
+
+// ---------------------------------------------------------------- 相对分位门控
+/**
+ * **为什么不能用一个固定的绝对阈值**（开发期实测，数据未随仓库提交，结论与 README 一致）：
+ *
+ *   在 10 个真假已知的调用上（5 个有副作用、5 个纯只读）：
+ *     轴        有副作用组均值   纯只读组均值   间距      排序正确率
+ *     result       0.076          0.160      -0.084        0%
+ *     effect       0.274          0.068      +0.206      100%
+ *
+ *   effect 轴的**排序是完美的**（有副作用组最低 0.220 > 只读组最高 0.080），
+ *   但**所有值都落在 0.5 以下** —— 拿 0.5 当阈值会把 10 条全判成"无副作用"。
+ *   这是 Jev 概率被压在一个窄带里的必然结果（同 dsh-compact 实测：分布密集区
+ *   不能放阈值）。所以第二层用**相对分位**：只在"本次会话已判定集合"的尾部取。
+ *
+ * 另一条实测结论：`result` 轴被**体量**污染（只读结果往往更大，于是"要保留"的分更高）。
+ * 相对分位能抵消掉一部分全局偏置，但不能抵消这种相关性——所以两轴取**交集**
+ * （必须同时在两轴的尾部），而不是取并集。
+ *
+ * @param {Array<{seq:number, prob?:number, effectProb?:number}>} verdicts
+ * @param {{quantile:number, minCandidates:number, minCandidatesForAbsolute?:number,
+ *   floorThreshold?:number, onNote?:(note:string)=>void}} options
+ * @returns {Set<number>} 同时落在两轴尾部 quantile 的 seq 集合
+ * @throws quantile 非法时抛错（issue #6：此前 NaN/undefined 会静默返回空集——
+ *   第二层"功能静默死亡"，而 compactPass 还会把它渲染成"样本不够"，误导排查）
+ */
+export function computeEligibleSeqs(verdicts, {
+  quantile, minCandidates,
+  // ⚠️ 必须引用导出常量，不能写字面量。此前这里是硬编码的 `3` / `0.2`，
+  // 于是改 DEFAULT_MIN_CANDIDATES_FOR_FLOOR 时**这个函数的默认值不会跟着变** ——
+  // 插件实体走 resolveConfig（读常量，行为会变），而直接调本函数的地方（含 check.js）
+  // 吃的是旧字面量，两边悄悄分叉。实测：常量改成 2 后 check.js 仍全绿，
+  // 因为它绕开了配置路径，测的是另一个数。
+  minCandidatesForAbsolute = DEFAULT_MIN_CANDIDATES_FOR_FLOOR,
+  floorThreshold = DEFAULT_FLOOR_THRESHOLD,
+  onNote,
+} = {}) {
+  if (!Number.isFinite(quantile) || quantile < 0 || quantile > 1) {
+    throw new Error(`compactQuantile 非法：${quantile}（必须是 0~1 的有限数值；配置留空/解析成 null 都会走到这里）`)
+  }
+  // 0 是显式关闭值；必须先于小样本降级，否则低分候选会绕过开关。
+  if (quantile === 0) {
+    onNote?.('compactQuantile=0 → 相对分位选择已显式关闭')
+    return new Set()
+  }
+  const usable = (verdicts ?? []).filter(
+    // 必须用 Number.isFinite：typeof NaN === 'number'，用 typeof 会让 NaN 混进总体，
+    // 而排序比较 (a-b) 返回 NaN 时被 V8 当作"相等"不换位 → NaN 项按**数组位置**
+    // 混进尾部，可能被选中做整对移出。口径与上面的 quantile 校验统一。
+    (v) => Number.isFinite(v?.prob) && Number.isFinite(v?.effectProb),
+  )
+  if (usable.length === 0) return new Set()
+
+  // ── 小总体分支（issue #27 修复）────────────────────────────────────────────
+  // 此前 `usable.length < minCandidates` 直接返回空集：只读工具在写/执行密集会话里
+  // 常常只占极少数（实测只读 1/6 → 总体仅 2 条），于是**第二层在绝大多数真实会话里
+  // 静默不工作**，而报错文案只说"需要 ≥4 个"，看起来像"样本确实不够"，不像 bug。
+  //
+  // 修法：小总体时降级为**绝对下限兜底**，而不是放弃。安全性论证——
+  //   分位排序携带的是"会话内相对位置"信息，需要总体；绝对下限携带的是"这个值本身
+  //   够不够低"，不需要比较。两者正交，所以降级不是放宽安全标准，而是**换一个更弱的
+  //   信号**。为补偿这个信号更弱，这里加三重约束：
+  //     ① floorThreshold 比 compactThreshold(0.5) 严格得多（默认 0.2）
+  //     ② 仍然要求**两轴同时**满足（与相对模式口径一致——实测 result 轴被体量污染，
+  //        单看它会放过"结果很大但确实无用"的调用）
+  //     ③ 样本比 minCandidatesForAbsolute 还少时仍然不做（1 条根本谈不上分布）
+  //   注意这在数学上**不是绝对禁止**：当相对阈值取到 0.5 附近时，尾部就是 prob<0.5，
+  //   与绝对阈值同构。降级分支只是把阈值收紧到 0.2 来补足"没有相对信息"这个缺口。
+  if (usable.length < Math.max(2, minCandidates ?? 4)) {
+    if (usable.length < Math.max(1, minCandidatesForAbsolute)) {
+      onNote?.(`总体仅 ${usable.length} 条，低于绝对下限模式的最低样本 ${minCandidatesForAbsolute} → 不做整对移出`)
+      return new Set()
+    }
+    const floor = usable.filter((v) => v.prob < floorThreshold && v.effectProb < floorThreshold)
+    onNote?.(`总体仅 ${usable.length} 条（< ${minCandidates}）→ 降级为绝对下限模式：`
+      + `要求两轴同时 < ${floorThreshold}，命中 ${floor.length}/${usable.length} 条`)
+    return new Set(floor.map((v) => v.seq))
+  }
+
+  const take = Math.max(1, Math.floor(usable.length * quantile))
+  const tailOf = (key) => new Set(
+    [...usable]
+      .sort((a, b) => (a[key] - b[key]) || (a.seq - b.seq))
+      .slice(0, take)
+      .map((v) => v.seq),
+  )
+  const byResult = tailOf('prob')
+  const byEffect = tailOf('effectProb')
+  const intersection = new Set([...byResult].filter((seq) => byEffect.has(seq)))
+  if (intersection.size > 0) return intersection
+
+  const floor = usable.filter((v) => v.prob < floorThreshold && v.effectProb < floorThreshold)
+  onNote?.(`两轴尾部交集为空 → 降级为绝对下限模式：要求两轴同时 < ${floorThreshold}，命中 ${floor.length}/${usable.length} 条`)
+  return new Set(floor.map((v) => v.seq))
+}
+
+// ---------------------------------------------------------------- 范围选择
+
+/** 一个"步骤"= assistant 消息（含 ≥1 个 tool-call）+ 紧随其后的 1:1 tool/result。 */
+function readStep(surface, eventAt, headIdx) {
+  const headSeq = surface[headIdx]
+  const head = eventAt(headSeq)
+  const calls = toolCallsOf(head)
+  if (calls.length === 0) return null
+
+  const resultIdx = []
+  for (let offset = 1; offset <= calls.length; offset += 1) {
+    const idx = headIdx + offset
+    if (idx >= surface.length) return { headIdx, headSeq, head, calls, resultIdx, complete: false }
+    if (eventAt(surface[idx])?.type !== 'tool/result') {
+      return { headIdx, headSeq, head, calls, resultIdx, complete: false }
+    }
+    resultIdx.push(idx)
+  }
+  const callIds = calls.map(toolCallIdOf)
+  const resultIds = resultIdx.map((idx) => resultCallIdOf(eventAt(surface[idx])))
+  const anyId = [...callIds, ...resultIds].some((id) => id != null)
+  let pairedResultIdx = [...resultIdx]
+  if (anyId) {
+    if (callIds.some((id) => id == null) || resultIds.some((id) => id == null)
+      || new Set(callIds).size !== callIds.length || new Set(resultIds).size !== resultIds.length) {
+      return { headIdx, headSeq, head, calls, resultIdx, pairedResultIdx: [], complete: false }
+    }
+    const resultByCallId = new Map(resultIds.map((id, offset) => [id, resultIdx[offset]]))
+    pairedResultIdx = callIds.map((id) => resultByCallId.get(id))
+    if (pairedResultIdx.some((idx) => idx == null)) {
+      return { headIdx, headSeq, head, calls, resultIdx, pairedResultIdx: [], complete: false }
+    }
+  }
+  return { headIdx, headSeq, head, calls, resultIdx, pairedResultIdx, complete: true }
+}
+
+/**
+ * 挑出可以整对移出的范围（连续步骤合并成一段）。
+ *
+ * 依赖全部注入，所以能脱离 DSH 单测。
+ *
+ * @param {object} input
+ * @param {number[]} input.surface surface 上的 seq 列表
+ * @param {(seq:number)=>object} input.eventAt seq → 事件
+ * @param {Map<number,object>} input.cache 判定缓存：**按工具结果 seq** 索引
+ * @param {(seq:number, verdict:object)=>boolean} input.dropVerdict 判定"这条可以整对移出"
+ * @param {(event:object)=>string} input.toolNameOf
+ * @param {object} input.cfg 见下面用到的字段
+ * @returns {{ranges:Array, stats:object}}
+ */
+export function selectReceiptRanges({ surface, eventAt, cache, dropVerdict, cfg }) {
+  const stats = {
+    scanned: 0,
+    steps: 0,
+    eligibleSteps: 0,
+    skippedTail: 0,
+    skippedTool: 0,
+    /**
+     * 被工具规则排除的**调用名统计**。
+     *
+     * 为什么必须记这个：第二层用的是**白名单**，一旦真实工具名与默认白名单对不上
+     * （各宿主的命名风格差很多：Read / read / fs_read / Get-Content…），
+     * 整个功能会**静默地永不触发**——第一层用黑名单所以一直没暴露这个问题。
+     * 把名字如实统计出来并上报，才能一眼看出"是白名单没配上"而不是"模型判断不对"。
+     */
+    blockedToolNames: {},
+    allowedToolNames: {},
+    skippedToolUnknown: 0,
+    skippedVerdict: 0,
+    skippedGuard: 0,
+    /** 用户可见文本过长的步骤数（text 轴） */
+    skippedText: 0,
+    /** 思考草稿过长的步骤数（reasoning 轴）——与 skippedText 分开计数，
+     *  否则排查时无法区分"是结论在守"还是"是草稿在守"（issue #26） */
+    skippedReasoning: 0,
+    skippedIncomplete: 0,
+    skippedShort: 0,
+    /** 同一 assistant 批次里仅部分 result 合格时，安全降级为逐结果回执的批次数。 */
+    partialSteps: 0,
+    /** 逐结果回执实际选中的 tool/result 数。 */
+    partialResults: 0,
+    /** 已经是确定性回执的结果，防止低阈值配置下重复压缩。 */
+    skippedReceipt: 0,
+    guardHits: [],
+  }
+  const cuts = computeCuts(surface, eventAt)
+  const lastAllowed = surface.length - 1 - cfg.preserveRecent
+
+  const steps = []
+  let index = 0
+  while (index < surface.length) {
+    stats.scanned += 1
+    const step = readStep(surface, eventAt, index)
+    if (step == null) {
+      index += 1
+      continue // 不是步骤头（user 消息 / 纯文本 assistant / checkpoint）
+    }
+    stats.steps += 1
+    steps.push(step)
+    // 无论是否合格都跳到这一步的末尾，避免把同一个调用数两遍。
+    // ⚠️ 这里必须用**位置**推进，不能用 seq 值 —— 一旦发生过 surface 替换
+    // （我们的第一层裁剪就会替换），seq 就不再等于「位置+1」了。
+    index = step.resultIdx.length > 0 ? step.resultIdx[step.resultIdx.length - 1] + 1 : index + 1
+  }
+
+  const eligible = []
+  const partial = []
+  for (const step of steps) {
+    const lastResultIdx = step.resultIdx[step.resultIdx.length - 1] ?? step.headIdx
+    const resultSeqs = (step.pairedResultIdx ?? step.resultIdx).map((idx) => surface[idx])
+    let reason = null
+
+    if (!step.complete) reason = 'incomplete'
+    else if (!balancedBefore(cuts, step.headIdx) || !balancedAfter(cuts, lastResultIdx)) reason = 'incomplete'
+    else {
+      // 两轴分开判（issue #26）：text = 结论/说明（长则守），reasoning = 草稿（长则守）。
+      // 拆开的重点是**阈值各自标定**——合并累加会让 reasoning 的分布盖住 text 的语义。
+      const { text, reasoning } = assistantBlockChars(step.head)
+      if (text > cfg.maxStepTextChars) reason = 'text'
+      else if (reasoning > cfg.maxStepReasoningChars) reason = 'reasoning'
+    }
+    let hits = []
+
+    // 完整性和 assistant 文本门是整批属性；通过后，其余规则逐调用判断。
+    // 这样一个 6-read 批次中 5 条合格、1 条不合格时，5 条仍可各自替换为回执。
+    const pairs = reason == null
+      ? step.calls.map((call, offset) => {
+          const resultIdx = (step.pairedResultIdx ?? step.resultIdx)[offset]
+          const seq = surface[resultIdx]
+          const event = eventAt(seq)
+          let pairReason = null
+          if (resultIdx > lastAllowed) pairReason = 'tail'
+          else if ((cfg.compactTools.length > 0 && !isToolIn(cfg.compactTools, call.name))
+            || isToolIn(cfg.neverCompactTools, call.name)) pairReason = 'tool'
+          else if (resultText(event).includes(RECEIPT_MARKER)) pairReason = 'receipt'
+          else {
+            const verdict = cachedVerdictForEvent(cache, event)
+            if (verdict == null || !dropVerdict(seq, verdict)) pairReason = 'verdict'
+          }
+          let pairHits = []
+          if (pairReason == null && cfg.evidenceGuard) {
+            const scan = scanEvidence(resultEvidenceText(eventAt, seq), cfg.evidencePatterns)
+            if (scan.hit) {
+              pairHits = scan.matches
+              pairReason = 'guard'
+            }
+          }
+          return { call, resultIdx, seq, event, chars: resultCharsOf(event), reason: pairReason, hits: pairHits }
+        })
+      : []
+
+    if (reason == null) {
+      const selected = pairs.filter((pair) => pair.reason == null)
+      const rejected = pairs.filter((pair) => pair.reason != null)
+      if (selected.length === pairs.length && step.headIdx <= lastAllowed) {
+        // 原路径：整批合格，交给 compactRegion 一次移出 assistant + 全部 results。
+      } else if (selected.length > 0) {
+        const selectedInSurfaceOrder = [...selected].sort((a, b) => a.resultIdx - b.resultIdx)
+        const selectedStep = {
+          ...step,
+          calls: selectedInSurfaceOrder.map((pair) => pair.call),
+          resultIdx: selectedInSurfaceOrder.map((pair) => pair.resultIdx),
+          resultSeqs: selectedInSurfaceOrder.map((pair) => pair.seq),
+          pairs: selectedInSurfaceOrder,
+          lastResultIdx: selectedInSurfaceOrder[selectedInSurfaceOrder.length - 1].resultIdx,
+        }
+        const chars = selected.reduce((sum, pair) => sum + pair.chars, 0)
+        partial.push({
+          kind: 'partial',
+          startIdx: selectedInSurfaceOrder[0].resultIdx,
+          endIdx: selectedInSurfaceOrder[selectedInSurfaceOrder.length - 1].resultIdx,
+          start: selectedInSurfaceOrder[0].seq,
+          end: selectedInSurfaceOrder[selectedInSurfaceOrder.length - 1].seq,
+          steps: [selectedStep],
+          chars,
+        })
+        stats.eligibleSteps += 1
+        stats.partialSteps += 1
+        stats.partialResults += selected.length
+        for (const pair of selected) {
+          const name = pair.call.name ?? 'unknown'
+          stats.allowedToolNames[name] = (stats.allowedToolNames[name] ?? 0) + 1
+        }
+        for (const pair of rejected) {
+          if (pair.reason === 'tail') stats.skippedTail += 1
+          else if (pair.reason === 'verdict') stats.skippedVerdict += 1
+          else if (pair.reason === 'guard') {
+            stats.skippedGuard += 1
+            stats.guardHits.push({ headSeq: step.headSeq, resultSeq: pair.seq, matches: pair.hits })
+          } else if (pair.reason === 'receipt') stats.skippedReceipt += 1
+          else if (pair.reason === 'tool') {
+            stats.skippedTool += 1
+            const name = pair.call.name ?? 'unknown'
+            if (name === 'unknown' || name === '') stats.skippedToolUnknown += 1
+            stats.blockedToolNames[name] = (stats.blockedToolNames[name] ?? 0) + 1
+          }
+        }
+        continue
+      } else {
+        reason = pairs[0]?.reason ?? (step.headIdx > lastAllowed ? 'tail' : 'verdict')
+        hits = pairs.find((pair) => pair.reason === 'guard')?.hits ?? []
+      }
+    }
+
+    if (reason != null) {
+      if (reason === 'tail') stats.skippedTail += 1
+      else if (reason === 'tool') {
+        stats.skippedTool += 1
+        // 只记**真正没通过工具门**的那个名字（issue #7）：此前把整步的所有调用名
+        // 都记进 blockedToolNames，通过白名单的名字也被列为"被拦下"，用户按
+        // jev_probe_shapes 的提示去"补配"一个本来就在白名单里的名字，而真正的
+        // 元凶淹没在同一份名单里——这个诊断字段就完成不了它的设计任务。
+        const offending = cfg.compactTools.length > 0
+          ? step.calls.filter((call) => !isToolIn(cfg.compactTools, call.name))
+          : step.calls.filter((call) => isToolIn(cfg.neverCompactTools, call.name))
+        for (const call of offending) {
+          const name = call.name ?? 'unknown'
+          if (name === 'unknown' || name === '') stats.skippedToolUnknown += 1
+          stats.blockedToolNames[name] = (stats.blockedToolNames[name] ?? 0) + 1
+        }
+      } else if (reason === 'verdict') stats.skippedVerdict += 1
+      else if (reason === 'receipt') stats.skippedReceipt += 1
+      else if (reason === 'guard') {
+        stats.skippedGuard += 1
+        stats.guardHits.push({ headSeq: step.headSeq, matches: hits })
+      } else if (reason === 'text') stats.skippedText += 1
+      else if (reason === 'reasoning') stats.skippedReasoning += 1
+      else stats.skippedIncomplete += 1
+      continue
+    }
+
+    stats.eligibleSteps += 1
+    for (const call of step.calls) {
+      const name = call.name ?? 'unknown'
+      stats.allowedToolNames[name] = (stats.allowedToolNames[name] ?? 0) + 1
+    }
+    eligible.push({
+      kind: 'full',
+      ...step,
+      resultSeqs,
+      lastResultIdx,
+      resultChars: resultSeqs.reduce((sum, seq) => sum + resultCharsOf(eventAt(seq)), 0),
+      tools: step.calls.map((call) => call.name ?? 'unknown'),
+    })
+  }
+
+  // 相邻的合格步骤合并成一段（合并后两端仍然平衡：步骤之间没有别的东西）
+  const merged = []
+  for (const step of eligible) {
+    const previous = merged[merged.length - 1]
+    if (previous != null && previous.endIdx + 1 === step.headIdx) {
+      previous.steps.push(step)
+      previous.endIdx = step.lastResultIdx
+      previous.end = surface[step.lastResultIdx]
+      previous.chars += step.resultChars
+      continue
+    }
+    merged.push({
+      kind: 'full',
+      startIdx: step.headIdx,
+      endIdx: step.lastResultIdx,
+      start: surface[step.headIdx],
+      end: surface[step.lastResultIdx],
+      steps: [step],
+      chars: step.resultChars,
+    })
+  }
+
+  // 省得不够多的范围不值得开一次压缩事务
+  const ranges = []
+  for (const range of [...merged, ...partial].sort((a, b) => a.startIdx - b.startIdx)) {
+    if (range.chars < cfg.compactMinChars) {
+      stats.skippedShort += 1
+      continue
+    }
+    ranges.push(range)
+  }
+  return { ranges, stats }
+}
+
+function resultText(event) {
+  const content = event?.data?.message?.content
+  if (!Array.isArray(content)) return ''
+  const block = content.find((item) => item?.type === 'tool-result')
+  const inner = block?.content
+  if (!Array.isArray(inner)) return ''
+  return inner
+    .filter((item) => item?.type === 'text' && typeof item.text === 'string')
+    .map((item) => item.text)
+    .join('\n')
+}
+
+function resultCharsOf(event) {
+  const content = event?.data?.message?.content
+  if (!Array.isArray(content)) return 0
+  const block = content.find((item) => item?.type === 'tool-result')
+  return countChars(block?.content)
+}
+
+// ---------------------------------------------------------------- 回执渲染
+
+/**
+ * 取 assistant 消息的**可见文本**（`text` 块），折叠空白并按码点截断，不做任何推断。
+ *
+ * 为什么必须保留原文摘录（修复：长任务提前收工）：
+ *   第二层把「调用 + 结果」整段移出 surface。若回执只留调用事实，模型自己写下的
+ *   **结论与进度**会一并消失。`maxStepTextChars` 只拦「长文本」，而「每步一句短结论」
+ *   这类工作流的文本很短（实测 10–20 字），拦不住。
+ *   实测证据：37 步逐文件读取任务中，模型的 12/13 条中间输出被逐步抹掉，
+ *   随后在第 14 步只输出一句概括、不再发起工具调用，任务中途终止。
+ *   把模型原话摘录进回执，**不引入任何模型生成**，但保住模型的进行中状态。
+ *
+ * 注意：这里只折叠空白并截断，不改写措辞，也不作推断。测试中「回执不得含推断性表述」的断言
+ * 针对的是**插件生成**的内容；原话属于摘录，且由“模型原话（原文摘录）”标签标明来源。
+ */
+function assistantVisibleText(event, maxChars) {
+  if (maxChars <= 0) return ''
+  const content = event?.data?.message?.content
+  if (!Array.isArray(content)) return ''
+  const parts = []
+  for (const block of content) {
+    if (block?.type !== 'text' || typeof block.text !== 'string') continue
+    parts.push(block.text)
+  }
+  const text = parts.join(' ').replace(/\s+/g, ' ').trim()
+  if (text.length === 0) return ''
+  const chars = Array.from(text)
+  return chars.length > maxChars ? `${chars.slice(0, maxChars).join('')}…` : text
+}
+
+/**
+ * 渲染确定性回执。
+ *
+ * 每一行都是可以核对的**事实**：工具名、命令/路径（逐字截断）、输出字符数、seq。
+ * assistant 文本只做空白折叠与定长截断，不改写措辞；插件不生成结论。
+ */
+export function renderReceipt(range, { eventAt, argChars = 120, textChars = 400 } = {}) {
+  const lines = []
+  const count = range.steps.reduce((sum, step) => sum + step.calls.length, 0)
+  lines.push(
+    `${RECEIPT_MARKER} 原历史 s${range.start}–s${range.end} 是 ${count} 次工具调用`
+    + `（共约 ${range.chars} 字符输出），为释放上下文已移出。以下为事实清单`
+    + `（工具名/入参/字符数/seq 由代码算出；模型原话仅作原文摘录，插件不新增推断）：`,
+  )
+  for (const step of range.steps) {
+    // ★ 修复：把该步模型自己的可见文本摘录带上，避免把模型的结论/进度一并抹掉。
+    const said = assistantVisibleText(step.head, textChars)
+    if (said) lines.push(`· s${step.headSeq} 模型原话（原文摘录）：${said}`)
+    step.calls.forEach((call, offset) => {
+      const seq = step.resultSeqs[offset] ?? step.headSeq
+      const args = renderCallArgs(call, argChars)
+      const chars = resultCharsOf(eventAt(step.resultSeqs[offset]))
+      lines.push(`· s${seq} ${call.name ?? 'unknown'}${args ? `：${args}` : ''} → ${chars} 字符输出`)
+    })
+  }
+  lines.push(
+    `原始事件仍完整保存在会话日志中（seqs ${range.start}–${range.end}）。`
+    + '需要内容时重跑相同命令/读取相同文件即可；本回执不含对内容的解释。',
+  )
+  return lines.join('\n')
+}
+
+/**
+ * 为批量步骤中的单个合格结果生成短回执。
+ *
+ * 这里不删除 assistant/tool-call 外壳，只替换对应 tool/result 的正文。因此同批次
+ * 其他不合格结果可以原样留在 surface，且每次单节点 replace 前后都保持配对完整。
+ */
+export function renderPartialResultReceipt(pair, { argChars = 120 } = {}) {
+  const call = pair?.call ?? {}
+  const seq = pair?.seq ?? pair?.event?.seq ?? '?'
+  const chars = resultCharsOf(pair?.event)
+  const args = renderCallArgs(call, argChars)
+  return `${RECEIPT_MARKER} s${seq} ${call.name ?? 'unknown'}${args ? `：${args}` : ''}`
+    + ` 的 ${chars} 字符输出已从当前上下文移出；原始事件仍保存在会话日志中，`
+    + '需要内容时请重跑相同命令或重新读取相同文件。本回执不含对内容的解释。'
+}