dsh-compaction-tower 0.1.39 → 0.1.42

package/README.md

@@ -8,7 +8,7 @@ DSH 的分块自动压缩工具：**无需主动压缩** —— 旧历史提前
 
 ## 它做什么
 
-- **压缩由它自己决定，不用模型操心**：观察者在后台把早期历史蒸成「块」写进日志 —— 只进日志不进上下文，模型看不见。每次请求前和每个回合结束前各判定一次，按「每层库存」决定蒸几块，并发发起（默认 10 个）。**每层库存 =（触发线 − 目标线）÷ 一个单位，再留 1 块当安全垫**，默认 45% / 15% / 5% 时是 **7 块**。
+- **压缩由它自己决定，不用模型操心**：观察者在后台把早期历史蒸成「块」写进日志 —— 只进日志不进上下文，模型看不见。每次请求前和每个回合结束前各判定一次，按「每层库存」决定蒸几块，并发发起（默认 10 个）。**每层库存 =（触发线 − 目标线）÷ 一块能回收的量，再留 1 块当安全垫**；一块顶掉的是「覆盖内容 − 自己的摘要」，按 80% 估，默认 45% / 15% / 5% 时是 **9 块**。
 - **越线那一刻不等模型**：块是提前蒸好的，提交就是一次查表，再交给宿主的压缩引擎换进表层 —— 不卡顿。
 - **压过的内容还能取回来**：`decompress` 看回被压缩的历史，`search_context` 在含已压缩内容的全部历史里搜。
 
@@ -183,9 +183,21 @@ DSH 的分块自动压缩工具：**无需主动压缩** —— 旧历史提前
 > 为什么不用宿主的 settings 服务：`settings.describe()` 只列出 **profile 文档里**的条目，
 > 由 bundle patch 插入的行不在其中——我们这条 `compaction-tower` 正是被插进去的，拿不到表单。
 
+## 接管了宿主的哪些入口
+
+| 入口 | 原来的行为 | 装了以后 |
+|---|---|---|
+| 到阈值自动压（`compactIfNeeded`） | 宿主自己挑一段、现调模型摘要 | 换成塔的判定与提交 |
+| `/compact` 命令（`compactNow`） | 绕过前者，直接 `compactSurfaceRegion` 压一段 | **提交塔里已经蒸好的块**；没块时可压内容为零，什么都不做 |
+| `summarize` | 宿主现场摘要 | 有现成块就直接返回，零 LLM 调用 |
+
+`/compact` 这一条必须接管：它原来走的是另一条路径，压出来的 checkpoint 没有块号，账本解释不了它，被它盖住的块会悄悄失效。
+
+**装之前已经被宿主压过的会话**：插件会把那些无主 checkpoint 认领成「只读块」——可见、不进库存、永远不会被再次提交，但 `decompress` 仍然能把它们背后被盖掉的原文取回来（`covers` 取自宿主写下的 `sourceEventSeqs`）。
+
 ## 已知限制
 
-- **原型补丁依赖方法名**：`compactIfNeeded` / `summarize` 是官方扩展点，但宿主大版本升级后需要复查。缺失时插件会记 warning 并降级为「只提供工具」。
+- **原型补丁依赖方法名**：`compactIfNeeded` / `summarize` / `compactNow` 是官方扩展点，但宿主大版本升级后需要复查。缺失时插件会记 warning 并降级为「只提供工具」。
 - **块记录每次现读**：`blocksOf()` 遍历会话全量事件。请求前的排程有 5 秒节流、回合尾才无条件跑一次，所以长会话下是「偶尔 O(事件数)」，不是每个 step。
 - **默认比例未经长会话标定**：`triggerRatio 0.45` 按 1M 窗口推；`distillMinRunRatio 0.05` 是单块分量（≈52K @ 1M），实际频率与块大小待多轮观察。
 

package/lib/engine.js

@@ -54,6 +54,14 @@ export function installEnginePatches(tower) {
     current?.rememberEngine?.(agent, this);
     return current.serveSummary(this, originalSummarize, input, agent, signal);
   };
+  // `/compact` 走的是 compactNow，它直接调 compactSurfaceRegion、绕过 compactIfNeeded。
+  // 不接管的话，用户敲一次命令就会压出一个没有块号的 checkpoint，把账本打出洞。
+  if (typeof proto.compactNow === 'function') {
+    proto.compactNow = function patchedCompactNow(agent, signal, commandId) {
+      current?.rememberEngine?.(agent, this);
+      return current.manualCompact(this, agent, signal, commandId);
+    };
+  }
 
   Object.defineProperty(proto, PATCHED, { value: true, configurable: true });
   current = tower;

package/lib/tower.js

@@ -43,6 +43,14 @@ function captureService(ctx, name) {
   }
 }
 
+/**
+ * 一块大约能回收它覆盖内容的多少。
+ *
+ * 提交一块换掉的是 covered（原文 / 下层摘要），换进来的是 summary（自己的摘要），
+ * 所以真实回收 = covered − summary。实测约 92%，这里取 0.8 留余量。
+ */
+const RECLAIM_RATE = 0.8;
+
 /** 把块记录变成模型可见的消息块。头部 + 正文。 */
 export function summaryBlocks(block, childBlockIds = []) {
   const header = blockHeader({
@@ -101,6 +109,109 @@ export class Tower {
     this.commitRequests = new WeakSet();
     /** 事实修正系数：WeakMap<Session, {scale, samples}>（见 calibration） */
     this.fits = new WeakMap();
+    /** 已经认领过宿主遗留 checkpoint 的会话（每次进程一次就够）。 */
+    this.imported = new WeakSet();
+  }
+
+  /**
+   * 认领「宿主压过、账本没记」的段。
+   *
+   * 装插件之前宿主压缩留下的 checkpoint 没有块号：对账本来说它是一个洞 ——
+   * 面板解释不了它，被它盖住的块悄悄失效却还挂着。这里把它登记成一个**只读块**：
+   *
+   *   - `covers` 从事件的 `surfaceOp` 还原（宿主写的是 replace 区间）；
+   *   - 写一条普通的 block 记录 + commit 记录，于是身份、状态、面板全都自动对上；
+   *   - 但它的 covers 已经不在表层，`usable()` 判 false → **永远不会被再次提交**；
+   *   - `decompress` 直接读日志，所以这些块的原文仍然取得回来。
+   *
+   * 幂等：某条 checkpoint 已经有块号（不管是我们提交的还是上次认领的）就跳过。
+   * @param {object} agent
+   */
+  async ensureImported(agent) {
+    const session = agent?.session;
+    if (session === undefined || session === null) return;
+    if (this.imported.has(session)) return;
+    try {
+      const blocks = readBlocks(session);
+      const owner = checkpointOwner(session);
+      let added = 0;
+      for (const seq of session.surface.nodes) {
+        if (owner.has(seq)) continue;
+        const event = session.eventAt(seq);
+        if (event?.type !== 'user/message') continue;
+        const source = event.data?.source;
+        if (source === undefined || !isCompactCheckpointSource(source)) continue;
+        const op = event.surfaceOp;
+        if (op?.op !== 'replace') continue;
+        // 宿主写 replace 时同时记了 sourceEventSeqs（被换掉的节点清单），比区间精确；
+        // 老格式没有这个字段就退回区间遍历。
+        const shadowed = Array.isArray(event.sourceEventSeqs) && event.sourceEventSeqs.length > 0
+          ? event.sourceEventSeqs
+          : (() => {
+            const list = [];
+            for (let cursor = op.startSeq; cursor <= op.endSeq; cursor += 1) list.push(cursor);
+            return list;
+          })();
+        const covers = [];
+        const children = new Set();
+        for (const cursor of shadowed) {
+          const covered = session.eventAt(cursor);
+          if (covered === undefined) continue;
+          if (session.deriveEventMessage(covered) === null) continue;
+          covers.push(cursor);
+          const child = owner.get(cursor);
+          if (child !== undefined) children.add(child);
+        }
+        if (covers.length === 0) continue;
+
+        const text = (event.data?.content ?? [])
+          .filter((part) => part.type === 'text')
+          .map((part) => part.text)
+          .join('\n');
+        const summaryTokens = Math.max(1, this.estimateText(text));
+        let coveredTokens = 0;
+        for (const cursor of covers) {
+          try {
+            coveredTokens += this.ctx.tokenMeter.estimateMessage(session.deriveEventMessage(session.eventAt(cursor)));
+          } catch {
+            // 估不出来就少算一点：这个数只影响合并配额，不影响正确性。
+          }
+        }
+        const tier = children.size === 0
+          ? 1
+          : Math.max(...[...children].map((id) => Number(blocks.find((b) => b.blockId === id)?.tier ?? 1))) + 1;
+        const blockId = this.allocateBlockId(session, blocks);
+        const record = {
+          blockId,
+          tier,
+          kind: 'import',
+          covers,
+          coveredTokens: Math.max(coveredTokens, summaryTokens),
+          summaryTokens,
+          childBlockIds: [...children],
+          summary: [{ type: 'text', text }],
+          origin: { kind: 'foreign', checkpointSeq: seq, compactionId: source?.compactionId ?? null },
+          tokensEstimated: true,
+          createdAt: new Date().toISOString(),
+        };
+        appendBlock(session, record);
+        appendCommit(session, {
+          blockId,
+          checkpointSeq: seq,
+          ...(typeof source?.compactionId === 'string' ? { compactionId: source.compactionId } : {}),
+        });
+        blocks.push(record);
+        owner.set(seq, blockId);
+        added += 1;
+      }
+      this.imported.add(session);
+      if (added > 0) {
+        this.debug(`认领了 ${added} 段宿主压缩留下的历史（只读块）`);
+        await this.flushSession(agent, session);
+      }
+    } catch (error) {
+      this.debug(`认领宿主 checkpoint 失败：${error?.message ?? error}`);
+    }
   }
 
   /**
@@ -130,18 +241,23 @@ export class Tower {
   /**
    * 每层该备多少份库存：把「触发线 → 目标线」这段缺口填满，再留 1 份安全垫。
    *
+   * 一块顶掉的不是它覆盖的全部原文，而是 covered − summary（摘要本身还占着）。
+   * 实测回收率约 92%，这里按 80% 算 —— 模糊的正确：把份数放大一点，
+   * 宁可多备一块，也别在越线那一刻差一点点。
+   *
    * 不做成配置项 —— 它完全由 triggerRatio / targetRatio / 一个单位 推出来，
    * 手填只会和这三个数打架。
    * @param {number} usable 可用预算（窗口 − 固定开销）
-   * @returns {number} 份数（至少 1）
+   * @returns {{unit:number, reclaim:number, blocks:number, tokens:number}}
    */
-  reserveUnitsOf(usable) {
+  reserveOf(usable) {
     const unit = Math.max(1, this.config.distillMinRunRatio * usable);
+    const reclaim = Math.max(1, Math.round(unit * RECLAIM_RATE));
     const gap = Math.max(0, this.config.triggerRatio - this.config.targetRatio) * usable;
     // 减一个极小量再 ceil：0.45−0.15 在浮点里是 0.30000000000000004，
     // 直接 ceil(6.000000000000001) 会多算一份。
-    const units = Math.ceil(gap / unit - 1e-9);
-    return Math.max(1, units + 1);
+    const blocks = Math.ceil(gap / reclaim - 1e-9) + 1;
+    return { unit, reclaim, blocks, tokens: blocks * reclaim };
   }
 
   /**
@@ -580,6 +696,9 @@ export class Tower {
   async compactIfNeeded(engine, agent, trigger, signal) {
     this.stats.pressureCalls = (this.stats.pressureCalls ?? 0) + 1;
     this.debug(`compactIfNeeded 被调用：trigger=${trigger}`);
+    // 先把「宿主压过、账本没记」的段认领成块：否则它们是账本上的洞，
+    // 库存与提交计划都会被这段无名历史带偏。
+    await this.ensureImported(agent);
     // 手动提交没法在空闲时做：宿主的 compactRegion 要求事件落在一个「打开的回合」里。
     // 所以按钮只排队，等下一回合开始、引擎来问的时候按目标 0 一次提交完。
     const manual = this.commitRequests.has(agent.session);
@@ -601,6 +720,7 @@ export class Tower {
 
     // 一次请求可以连续提交多块：每块自己一对 compaction 事件，区间互不重叠。
     let first = null;
+    const results = [];
     let succeeded = 0;
     let lastError = null;
     const surface = new Set(agent.session.surface.nodes);
@@ -619,6 +739,7 @@ export class Tower {
         if (result !== null) {
           this.stats.committed += 1;
           succeeded += 1;
+          results.push(result);
           this.recordCheckpoint(agent.session, block.blockId, result);
           first ??= result;
         }
@@ -638,9 +759,48 @@ export class Tower {
       ...previous,
       outcome: { planned: plan.blocks.length, succeeded, error: lastError },
     });
+    // 手动压缩（/compact）一次可能提交多块，把总量合起来回报给命令层，
+    // 否则它只会说「压了 1 段」。
+    if (manual === true && results.length > 1) {
+      return {
+        ...results[results.length - 1],
+        shadowedSeqs: results.flatMap((item) => item.shadowedSeqs ?? []),
+        shadowedTokenCount: results.reduce((sum, item) => sum + (item.shadowedTokenCount ?? 0), 0),
+      };
+    }
     return first;
   }
 
+  /**
+   * `/compact` 的落点：把塔里已经蒸好的块提交进上下文。
+   *
+   * 装了本插件之后，「压缩」这个动作的语义就是提交块 —— 宿主原来那套
+   * 「现场挑一段、现调模型摘要」已经不该再跑了（它压出来的东西没有块号，
+   * 账本无法解释）。所以这里不复用原实现，而是走自己的提交路径。
+   *
+   * 宿主要求手动压缩独占 agent，所以外面套一层 `runMaintenance`。
+   * @param {object} engine
+   * @param {object} agent
+   * @param {AbortSignal} [signal]
+   * @returns {Promise<object|null>} 宿主 compactRegion 的结果；没有可提交的块时为 null
+   */
+  async manualCompact(engine, agent, signal) {
+    const withMaintenance = typeof agent?.runMaintenance === 'function'
+      ? (task) => agent.runMaintenance(task)
+      : (task) => task(signal);
+    return withMaintenance(async (agentSignal) => {
+      const operation = agentSignal === undefined || signal === undefined
+        ? (agentSignal ?? signal)
+        : AbortSignal.any([agentSignal, signal]);
+      this.commitRequests.add(agent.session);
+      try {
+        return await this.compactIfNeeded(engine, agent, 'manual', operation);
+      } finally {
+        this.commitRequests.delete(agent.session);
+      }
+    });
+  }
+
   /**
    * 提交成功后，把「块号 ↔ checkpoint 节点」记进账本。
    *
@@ -847,6 +1007,9 @@ export class Tower {
     const unit = Math.min(this.config.distillMinRunRatio * usable, this.config.observerMaxTokens);
     // unit 是真实口径，而 availableUnits 累加的是节点估算值 → 换算成估算口径再比。
     const unitH = Math.max(1, Math.round(unit / scale));
+    // 库存与配额都按「一块能回收多少」记账：inventory 数的是 covered − summary，
+    // 拿 unit 当分母会永远差一点点（差的就是摘要本身的大小）。
+    const reserve = this.reserveOf(usable);
     const inventory = this.inventoryOf(session, blocks);
     const available = this.availableUnits({
       nodes, systemSeqs, coveredSeqs, checkpointSeqs, tierOf, unit: unitH, blocks,
@@ -854,8 +1017,8 @@ export class Tower {
     const plan = planObservation({
       available,
       inventory,
-      reserveTokens: this.reserveUnitsOf(usable) * unit,
-      unitTokens: unit,
+      reserveTokens: reserve.tokens,
+      unitTokens: reserve.reclaim,
       concurrency: this.config.observerConcurrency,
     });
     /** 记下这次观察判定，面板据此回答「为什么没蒸」。 */
@@ -871,7 +1034,7 @@ export class Tower {
     };
     if (plan.length === 0) {
       // 全部材料都在保护区里 或 库存已够：两种都记下来，别让人以为观察者没跑。
-      const stocked = [...available.keys()].some((tier) => (inventory.get(tier) ?? 0) >= this.reserveUnitsOf(usable) * unit);
+      const stocked = [...available.keys()].some((tier) => (inventory.get(tier) ?? 0) >= reserve.tokens);
       note({ kind: available.size === 0 ? 'no-material' : stocked ? 'stocked' : 'no-quota' });
       this.debug(`不补蒸：库存=${[...inventory].map(([t, v]) => `T${t}:${Math.round(v)}`).join(',') || '空'} 可用=${[...available].map(([t, v]) => `T${t}:${v}`).join(',') || '空'}`);
       return;

package/package.json

@@ -1,6 +1,6 @@
-{
+{
   "name": "dsh-compaction-tower",
-  "version": "0.1.39",
+  "version": "0.1.42",
   "description": "Layered background distillation for DeepSeek Harness: distill early history ahead of time, commit whole blocks with zero LLM calls, and expose decompress/search_context to the model",
   "type": "module",
   "main": "lib/index.js",