@logictan/dsh-verbatim-compaction 0.3.1 → 0.5.0

package/README.md

@@ -17,14 +17,16 @@
 ## 摘要长什么样
 
 ```
-## user (turn 37)
+## user
 （用户原话，逐字，永不改写）
 
-### assistant (turn 37)
+### assistant
+## Asked
+- 是否要用 FULL 而不是 INCREMENTAL
 ## Did
 - 实测 `auto_vacuum=FULL` 删除后自动缩容：19.61 MB → 0.01 MB
 ## Concluded
-- 选 FULL 而非 INCREMENTAL：回收发生在宿主自己的 DELETE 里，不受 busy_timeout=0 影响
+- 选 FULL：回收发生在宿主自己的 DELETE 里，不受 busy_timeout=0 影响
 ## Overturned
 - 先前认为必须显式执行 VACUUM 才能回收空间
   tools: bash×280 ssh_exec×44 web_search×6 (408830 bytes)
@@ -32,6 +34,8 @@
   wrote: /Volumes/LogicExt/Git/BookReader/src/video.js
 ```
 
+标题不带轮次号：日志里的 `turn` 号既不唯一也不是一轮一个（一个真实会话把两条请求都编号成 1），印出来就是会撒谎的标题。
+
 - **用户原话逐字**，不重写、不改写、不摘要。
 - **助手正文由提取块替代**，不并列保留——并列就是同一份内容写两遍。
 - 工具结果只留「工具名 × 次数 + 字节数」，内容丢弃。
@@ -51,7 +55,11 @@
 
 只抄正文救不了「正文为空」的轮次。实测一个 13878 事件的会话：1973 条 assistant 消息里只有 317 条带正文，其中一轮跑了 342 次工具调用却一个字没写，纯逐字摘要把它压成一行 `tools: bash×281`——活干了，记录没了。
 
-所以提取的材料是三段：用户请求（逐字）、助手正文（逐字）、工具轨迹（每条调用的 `description`，失败的调用另记一行首行错误）。模型输出固定的三节：`## Did` / `## Concluded` / `## Overturned`。
+所以提取的材料是三段：用户请求（逐字）、助手正文（逐字）、工具轨迹（每条调用的 `description`，失败的调用另记一行首行错误）。模型输出固定的四节：`## Asked` / `## Did` / `## Concluded` / `## Overturned`。
+
+空节直接删掉，不留 `(none)` 占位。实测一份真实提取块里 `## Asked` 和 `## Overturned` 都是 `(none)`，删掉后 312 → 271 字符；按 130 轮算，这些占位合计约 900 token 只是在记录「什么都没发生」。清理在代码里做（`pruneEmptySections`），不只依赖提示词——模型仍写了 `(none)` 也不会白花 token。判据是整节每一行去掉项目符号后都只是 `(none)` / `none` / `n/a` / `无` 之类的占位；`none of the tests passed`、`无法连接，改用代理` 这类真内容照原样保留。
+
+`## Asked` 记的是「这一轮向用户提了什么、给了哪些选项」。实测 123 条真人消息里 43 条（35%）不超过 12 个字符——`3`、`1`、`同意`、`做`、`继续`——而 46% 是在回答上一轮助手的提问。只逐字保留「3」而不保留它在回答什么问题，等于记下一个决定却没记下决定的是什么。
 
 模型用的是会话自己的路由（`session.requestHeader()?.config`），和宿主原生压缩同一个取法，不需要单独配置凭据。
 
@@ -61,6 +69,10 @@
 - **工具调用从 `assistant/message` 的 block 里取**。日志里没有独立的 `tool/call` 事件类型，按它过滤会一条都取不到。
 - **提取失败就退回逐字正文**。模型不可达、超时、输出为空时，该轮保留原来的助手正文；压缩本身不能因此失败，否则会话死于上下文溢出，比丢细节更糟。降级是逐轮的：一批里某一轮没答，只有那一轮退回正文。
 
+提取结果按内容哈希缓存，同一次会话内复用。`digestSource` 每次压缩都从原始日志重建，而原始事件永远留在日志里，所以同一轮会被反复读到。实测那个压缩了 33 次的会话：共提取 142 轮，其中 **129 轮（91%）在更早的压缩里已经提取过**；全机 370 个会话、456 次压缩里，**81% 的压缩工作量是这种重复**（有压缩的 88 个会话中 70 个压缩过 2 次以上）。
+
+缓存的键是提取材料的哈希（用户请求 + 助手正文 + 工具轨迹），不是 slot 位置：位置会随历史增长而错位，内容变了哈希就变，不会读到过期块。缓存是进程内的，重启即失效——代价只是重新提取一次，与加缓存前行为一致。
+
 提取按批调用：每 8 轮一次，一轮输出一个 `=== TURN n ===` 块。早期实现是每轮一次调用，122 轮就是 131 次往返，单轮 400 token 的输出上限乘以 131 就可能超过整个摘要上限。批处理把往返压到约 17 次，并共享 prompt 前缀以复用 provider 的 KV cache。
 
 用户原话在布局上**先占额度**，提取块不得挤占。实测那个 122 轮会话：区间内真人原话共 469 字符（117 token），而每轮一块 420 字符的提取共 55020 字符——提取是正文的 117 倍，任何让二者竞争的布局都会把正文挤掉，而正文是「请用pixi管理开发环境」这类永不过期的约束，提取描述的却是已经做完的工作。

package/lib/index.js

@@ -150,12 +150,64 @@ export function isErrorResult(event) {
     const message = messageOf(event);
     return message?.isError === true;
 }
+/**
+ * Drop headings whose body says nothing.
+ *
+ * The instruction asks the model to omit empty sections, but a model that writes
+ * `## Overturned\n- (none)` anyway must not cost tokens on every turn: 130 turns
+ * of that placeholder is ~900 tokens recording that nothing was overturned. So
+ * the shape is enforced here as well, not only requested in the prompt.
+ *
+ * A heading is dropped when every non-blank line under it, once its bullet is
+ * stripped, is a placeholder — `(none)`, `none`, `n/a`, `-`, `无`. A heading with
+ * any real content is kept verbatim.
+ *
+ * @param body - one slot's extracted text.
+ * @returns the same text with empty sections removed, or an empty string when
+ * nothing substantive remains.
+ */
+export function pruneEmptySections(body) {
+    const lines = body.split('\n');
+    const kept = [];
+    let pendingHeading;
+    let pendingBody = [];
+    const flush = () => {
+        if (pendingHeading === undefined) {
+            kept.push(...pendingBody);
+            pendingBody = [];
+            return;
+        }
+        const substantive = pendingBody.some((line) => {
+            const text = line.replace(/^\s*(?:[-*]|\d+\.)\s*/, '').trim();
+            if (text.length === 0)
+                return false;
+            return !/^(?:\(?none\)?|n\/a|na|-{1,2}|无|沒有|没有)$/i.test(text);
+        });
+        if (substantive)
+            kept.push(pendingHeading, ...pendingBody);
+        pendingHeading = undefined;
+        pendingBody = [];
+    };
+    for (const line of lines) {
+        if (/^#{1,6}\s/.test(line)) {
+            flush();
+            pendingHeading = line;
+            continue;
+        }
+        pendingBody.push(line);
+    }
+    flush();
+    return kept.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
 /** Directive appended as the final user message of the extraction call. */
 const EXTRACT_INSTRUCTION = [
     'You are summarizing a batch of turns from a coding session for a compaction checkpoint.',
     'Each item is introduced by a line `=== SLOT <key> (turn <n>) ===` and contains the user request, the assistant prose (may be empty), and a trace of the tool calls it made (descriptions only) plus any results the log marked as errors.',
     '',
-    'For EVERY item, emit exactly one block, introduced by `=== SLOT <key> ===` using that same key, containing these three Markdown headings in order. Under each, at most two terse lines. If a section has no real information, write "(none)" — never invent.',
+    'For EVERY item, emit exactly one block, introduced by `=== SLOT <key> ===` using that same key. Under each heading write at most two terse lines. OMIT a heading entirely when it has no real information — do not write "(none)" and do not invent. An item where nothing substantive happened may be omitted altogether.',
+    '',
+    '## Asked',
+    '- the question(s) this turn put to the user, and the options it offered — the next user message is usually the answer',
     '',
     '## Did',
     '- what was actually done, concretely',
@@ -382,6 +434,39 @@ function withExtractions(sections, extracted) {
 function turnKey(sectionIndex, turnIndex) {
     return `${sectionIndex}:${turnIndex}`;
 }
+/**
+ * Cache key for one slot's extraction material: a hash of everything the model
+ * would be shown.
+ *
+ * The material, not the slot's position or turn number: positions shift as
+ * history grows and numbers repeat, but identical material must produce an
+ * identical extraction. Hashing the exact string `buildExtractionMaterial`
+ * returns means a change anywhere in the user request, the prose, or the tool
+ * trace invalidates the entry — nothing can silently go stale.
+ *
+ * FNV-1a, 32-bit, two seeds. Not cryptographic: the risk here is an accidental
+ * collision between two turns, and 64 bits over a few hundred entries makes that
+ * vanishingly unlikely.
+ *
+ * @param events - one slot's events, in log order.
+ * @returns a stable hex key.
+ */
+function materialKey(events) {
+    const prose = events
+        .filter((event) => event.type === 'assistant/message')
+        .map((event) => textOf(event))
+        .filter((text) => text.length > 0)
+        .join('\n');
+    const material = buildExtractionMaterial(events, prose);
+    let a = 0x811c9dc5;
+    let b = 0x01000193;
+    for (let index = 0; index < material.length; index += 1) {
+        const code = material.charCodeAt(index);
+        a = Math.imul(a ^ code, 0x01000193) >>> 0;
+        b = Math.imul(b ^ (code + index), 0x85ebca6b) >>> 0;
+    }
+    return `${a.toString(16)}${b.toString(16)}`;
+}
 /**
  * Render one section to digest text, truncating assistant prose to `capChars`.
  *
@@ -396,15 +481,14 @@ function turnKey(sectionIndex, turnIndex) {
 function renderSection(section, capChars) {
     const lines = [];
     for (const turn of section.turns) {
-        const label = turn.turn === undefined ? '?' : String(turn.turn);
         if (turn.user.length > 0)
-            lines.push(`\n## user (turn ${label})\n${turn.user.join('\n')}`);
+            lines.push(`\n## user\n${turn.user.join('\n')}`);
         if (turn.extracted !== undefined) {
             let block = turn.extracted;
             if (capChars !== undefined && block.length > capChars) {
                 block = `${block.slice(0, capChars)}\n…(+${block.length - capChars} chars)`;
             }
-            lines.push(`### assistant (turn ${label})\n${block}`);
+            lines.push(`### assistant\n${block}`);
         }
         else {
             let body = turn.assistant.join('\n');
@@ -412,7 +496,7 @@ function renderSection(section, capChars) {
                 body = `${body.slice(0, capChars)}\n…(+${body.length - capChars} chars)`;
             }
             if (body.length > 0)
-                lines.push(`### assistant (turn ${label})\n${body}`);
+                lines.push(`### assistant\n${body}`);
         }
         if (turn.tools.size > 0) {
             const names = [...turn.tools.entries()]
@@ -711,7 +795,7 @@ async function extractBatch(ctx, agent, batch, signal) {
     const blocks = answer.split(/^=== SLOT ([^\s(]+)[^=]*===$/m);
     for (let index = 1; index < blocks.length; index += 2) {
         const key = blocks[index];
-        const body = (blocks[index + 1] ?? '').trim();
+        const body = pruneEmptySections((blocks[index + 1] ?? '').trim());
         if (key !== undefined && body.length > 0)
             out.set(key, body);
     }
@@ -727,6 +811,23 @@ async function extractBatch(ctx, agent, batch, signal) {
  * subclass cannot diverge from the host's transaction semantics.
  */
 export default class VerbatimCompactionEngine extends BasicCompactionEngine {
+    /**
+     * Extraction results, keyed by a hash of the material they were derived from.
+     *
+     * `digestSource` rebuilds from the raw log on every compaction, and raw events
+     * never leave the log, so the same turn is re-read on every later compaction.
+     * Measured on the session that compacted 33 times: 142 turns extracted, 129 of
+     * them (91%) already extracted earlier. Across all 370 local sessions, 81% of
+     * compaction work is that repeat.
+     *
+     * Keyed by content, not by slot position: a position holds different content
+     * once history grows, so a positional key would serve a stale block. A turn
+     * whose prose changed hashes differently and is extracted again.
+     *
+     * Process-local and bounded. A restart loses it, costing one re-extraction —
+     * the same behaviour as before this cache existed.
+     */
+    extractionCache = new Map();
     /**
      * Build the replacement checkpoint content from the session log.
      *
@@ -822,13 +923,26 @@ export default class VerbatimCompactionEngine extends BasicCompactionEngine {
             }
         }
         const extracted = new Map();
-        for (let index = 0; index < slots.length; index += TURNS_PER_CALL) {
+        const missing = [];
+        for (const slot of slots) {
+            const cached = this.extractionCache.get(materialKey(slot.events));
+            if (cached === undefined)
+                missing.push(slot);
+            else
+                extracted.set(slot.key, cached);
+        }
+        for (let index = 0; index < missing.length; index += TURNS_PER_CALL) {
             if (signal?.aborted === true)
                 break;
-            const batch = slots.slice(index, index + TURNS_PER_CALL);
+            const batch = missing.slice(index, index + TURNS_PER_CALL);
             const blocks = await extractBatch(this.ctx, agent, batch, signal);
-            for (const [key, block] of blocks)
-                extracted.set(key, block);
+            for (const slot of batch) {
+                const block = blocks.get(slot.key);
+                if (block === undefined)
+                    continue;
+                extracted.set(slot.key, block);
+                this.extractionCache.set(materialKey(slot.events), block);
+            }
         }
         return extracted;
     }

package/lib/types/index.d.ts

@@ -80,6 +80,23 @@ export interface SummaryResult {
  * @returns true only when the log itself marks the result as an error.
  */
 export declare function isErrorResult(event: SessionEvent): boolean;
+/**
+ * Drop headings whose body says nothing.
+ *
+ * The instruction asks the model to omit empty sections, but a model that writes
+ * `## Overturned\n- (none)` anyway must not cost tokens on every turn: 130 turns
+ * of that placeholder is ~900 tokens recording that nothing was overturned. So
+ * the shape is enforced here as well, not only requested in the prompt.
+ *
+ * A heading is dropped when every non-blank line under it, once its bullet is
+ * stripped, is a placeholder — `(none)`, `none`, `n/a`, `-`, `无`. A heading with
+ * any real content is kept verbatim.
+ *
+ * @param body - one slot's extracted text.
+ * @returns the same text with empty sections removed, or an empty string when
+ * nothing substantive remains.
+ */
+export declare function pruneEmptySections(body: string): string;
 /**
  * Build the compact per-turn trace fed to the summarizer.
  *
@@ -214,6 +231,23 @@ export declare function buildExtractionMaterial(turn: readonly SessionEvent[], p
  * subclass cannot diverge from the host's transaction semantics.
  */
 export default class VerbatimCompactionEngine extends BasicCompactionEngine {
+    /**
+     * Extraction results, keyed by a hash of the material they were derived from.
+     *
+     * `digestSource` rebuilds from the raw log on every compaction, and raw events
+     * never leave the log, so the same turn is re-read on every later compaction.
+     * Measured on the session that compacted 33 times: 142 turns extracted, 129 of
+     * them (91%) already extracted earlier. Across all 370 local sessions, 81% of
+     * compaction work is that repeat.
+     *
+     * Keyed by content, not by slot position: a position holds different content
+     * once history grows, so a positional key would serve a stale block. A turn
+     * whose prose changed hashes differently and is extracted again.
+     *
+     * Process-local and bounded. A restart loses it, costing one re-extraction —
+     * the same behaviour as before this cache existed.
+     */
+    private readonly extractionCache;
     /**
      * Build the replacement checkpoint content from the session log.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logictan/dsh-verbatim-compaction",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Deterministic compaction backend that keeps conversation prose verbatim in the checkpoint instead of re-summarizing it: user and assistant text survive word for word, tool results collapse to one-line pointers, reasoning is never read, and no model call is made.",
   "type": "module",
   "main": "lib/index.js",