dsh-context-toolkit 0.3.0 → 0.3.2

package/README.md

@@ -115,7 +115,7 @@ Tool switches: `tools.execute`, `tools.executeFile`, `tools.batchExecute`, `tool
 The offline suites need no DSH runtime:
 
 ```bash
-node smoke.mjs        # 70 checks: contract, runtime discovery, tools, gate (segment matching, prefix/path normalisation, host-aligned path base, script_path and host-fetcher coverage), resource disposal, knowledge base, observability, version reporting
+node smoke.mjs        # 85 checks: contract, runtime discovery, tools, gate (segment matching, host-aligned path base, script_path and host-fetcher coverage), output slimming with reversible retrieval and retention, resource disposal, knowledge base, observability, version reporting
 node test-client.mjs  # 27 checks: browser-half contract and bilingual dictionary parity
 node test-package.mjs # 20 checks: publish manifest and the zero-dependency constraint
 node release-check.mjs # 30 checks: release readiness (manifest, deps, tool count, gate matching, version, SHA coverage, no hardcoded paths)
@@ -139,6 +139,7 @@ At `tools/post-execute`, the strategy follows the shape:
 **Two gates**: a candidate must be at most 72% of the original bytes *and* have a strictly lower token estimate, or it is dropped — no saving means no claim, and the ledger never overstates.
 
 **Reversibility is the red line**: every lossy path stores the exact original first and injects a `[ctk_retrieve id=…]` marker, read back with `ctk_retrieve`. The originals live in the **same database as the FTS5 index** — one file, two jobs: FTS5 finds sections, blobs restore them.
+- **Retention**: `slimOriginalTtlMinutes` (default 1440 = one day, 0 = forever) is swept once on every load; when a marker cannot be delivered the blob is rolled back by id, so an unrelated original is never taken with it.
 
 ## Known limits
 

package/README.zh.md

@@ -116,7 +116,7 @@ await ctk_search({ queries: ['rate limit', 'auth'] });  // 只取相关片段
 离线套件不依赖 DSH 运行时：
 
 ```bash
-node smoke.mjs        # 70 项：契约、运行时探测、三工具、门禁（分段匹配 + 前缀/路径归一 + 路径基准对齐 + script_path 与取网页工具覆盖）、资源释放、知识库、观测、版本自述
+node smoke.mjs        # 85 项：契约、运行时探测、工具、门禁（分段匹配 + 路径基准对齐 + script_path 与取网页工具覆盖）、输出瘦身与可逆取回及保留期、资源释放、知识库、观测、版本自述
 node test-client.mjs  # 27 项：浏览器半体契约与双语字典一致性
 node test-package.mjs # 20 项：发布清单与零依赖约束
 node release-check.mjs # 30 项：发布就绪（清单/依赖/工具数/门禁匹配/版本/SHA 覆盖/无硬编码路径）
@@ -140,6 +140,7 @@ node release-check.mjs # 30 项：发布就绪（清单/依赖/工具数/门禁
 **双重门**：候选必须同时满足「字节 ≤ 72%」且「估算 token 严格下降」，否则放弃——压不动就不压，台账绝不虚报节省。
 
 **可逆红线**：任何有损路径先把原文**逐字节**存好并注入 `[ctk_retrieve id=…]` 标记，用 `ctk_retrieve` 取回。原文与 FTS5 索引同在**同一个数据库**（一个文件两个职责：FTS5 找段落，blob 逐字节还原）。
+- **原文保留期**：`slimOriginalTtlMinutes`（默认 1440 = 一天，0 = 永久）由插件在**每次加载时**执行一次清理；标记投递失败时按 id 精确回滚，不会牵连其他原文。
 
 ## 已知边界
 

package/index.js

@@ -284,6 +284,19 @@ export function apply(ctx, rawConfig) {
     log.warn('knowledge base unavailable: ' + String((error && error.message) || error))
   }
 
+  // Retention is enforced here, once per load, because the alternative was a setting
+  // the user could see and the code never read: slimOriginalTtlMinutes was exposed in
+  // the settings page while nothing consumed it, so stored originals accumulated
+  // forever and the promise the panel made was not kept.
+  if (store) {
+    try {
+      const swept = store.purgeBlobsOlderThan(Number(config.slimOriginalTtlMinutes))
+      if (swept.removed > 0) log.info('retention sweep removed ' + swept.removed + ' stored original(s)')
+    } catch (error) {
+      log.warn('retention sweep failed: ' + String((error && error.message) || error))
+    }
+  }
+
   registerRoutingGate(ctx, config, stats)
   registerOutputSlimmer(ctx, config, stats, store, log)
   registerTools(ctx, config, stats, storageDir, log)
@@ -559,7 +572,10 @@ function registerOutputSlimmer(ctx, config, stats, store, log) {
         if (Buffer.byteLength(slimmed, 'utf8') >= outcome.originalBytes) {
           stats.slimSkipped += 1
           rewritten.push(block)
-          if (marker) { try { store.purgeBlobs({ all: false }) } catch { /* blob stays, harmless */ } }
+          // The blob was written but the marker could not be delivered, so nothing will
+          // ever reference it. Removing this specific id is the point: the previous call
+          // passed { all: false } with no age, which purgeBlobs treats as "nothing to do".
+          if (marker) { try { store.purgeBlobs({ ids: [id] }) } catch { /* blob stays, harmless */ } }
           continue
         }
 
@@ -1086,11 +1102,16 @@ function registerKnowledgeTools(ctx, config, stats, store, log) {
           }
         }
         stats.calls['ctk_retrieve'] = (stats.calls['ctk_retrieve'] || 0) + 1
+        // isError must be present on every return: the host validates a tool's output
+        // against the declared schema and rejects the call outright when it is missing.
+        // Omitting it here made the whole tool unusable — the marker was injected, the
+        // original was stored, and the read-back failed with "missing required property".
         return {
           text: '## ctk_retrieve ' + id + '\n'
             + '- bytes: ' + found.bytes + ' (exact original, restored verbatim)\n'
             + '- stored: ' + new Date(found.createdAtMs).toISOString() + '\n\n'
             + found.text,
+          isError: false,
         }
       },
     }, 'ctk_retrieve'))
@@ -1411,8 +1432,11 @@ function registerObservabilityTools(ctx, config, stats, store, storageDir, log)
       description: 'Report this plugin\'s savings ledger and knowledge-base usage. Shows how many calls the routing gate refused, how many bytes the sandbox kept out of the conversation, how many bytes were filed, and the per-tool call counts.',
       parameters: { type: 'object', properties: {}, additionalProperties: false },
       async execute() {
-        const kb = store ? store.stats() : { documents: 0, chunks: 0, bytes: 0 }
-        const produced = stats.bytesSandboxed + stats.bytesIndexed + stats.deniedBytes
+        const kb = store ? store.stats() : { documents: 0, chunks: 0, bytes: 0, blobs: 0, blobBytes: 0 }
+        // Slimmed bytes are kept out too — they were removed from output before it
+        // reached the model. Leaving them out understated the ledger by exactly the
+        // amount this half of the plugin exists to save.
+        const produced = stats.bytesSandboxed + stats.bytesIndexed + stats.deniedBytes + stats.slimmedBytes
         const keptOut = produced
         const uptimeMs = Date.now() - stats.startedAt
         const lines = [
@@ -1422,12 +1446,15 @@ function registerObservabilityTools(ctx, config, stats, store, storageDir, log)
           '- 门禁拦截 denied: ' + stats.denied + ' 次（约 ' + stats.deniedBytes + ' 字节未进入上下文）',
           '- 沙箱保留 bytesSandboxed: ' + stats.bytesSandboxed + ' 字节（子进程产出但只回结论的部分）',
           '- 已归档 bytesIndexed: ' + stats.bytesIndexed + ' 字节（存入知识库、未留在对话里）',
+          '- 输出瘦身 slimmed: ' + stats.slimmed + ' 块（' + stats.slimmedBytes + ' 字节 ≈ ' + stats.slimmedTokens + ' tokens 未进入上下文；跳过的块 ' + stats.slimSkipped + '）',
           '- 合计 kept out of context: ' + keptOut + ' 字节 ≈ ' + Math.round(keptOut / 4) + ' tokens（按 4 字节/token 估算）',
           '',
           '### 知识库 / knowledge base',
           '- 文档 documents: ' + kb.documents,
           '- 片段 chunks: ' + kb.chunks,
           '- 原文字节 bytes: ' + kb.bytes,
+          '- 可逆原文 blobs: ' + (kb.blobs || 0) + '（' + (kb.blobBytes || 0) + ' 字节，可用 ctk_retrieve 逐字节取回）',
+          '- 原文保留期 retention: ' + (Number(config.slimOriginalTtlMinutes) > 0 ? Number(config.slimOriginalTtlMinutes) + ' 分钟（每次加载时清理过期项）' : '永久保留'),
           '- 位置: ' + storageDir,
           '',
           '### 本插件注册的工具',
@@ -1499,6 +1526,9 @@ function registerObservabilityTools(ctx, config, stats, store, storageDir, log)
         lines.push('- 门禁拦截 denied: ' + stats.denied + ' 次（' + stats.deniedBytes + ' 字节未进入上下文）')
         lines.push('- 沙箱保留 bytesSandboxed: ' + stats.bytesSandboxed + ' 字节')
         lines.push('- 已归档 bytesIndexed: ' + stats.bytesIndexed + ' 字节')
+        lines.push('- 输出瘦身 slimmed: ' + stats.slimmed + ' 块（' + stats.slimmedBytes + ' 字节 ≈ ' + stats.slimmedTokens + ' tokens 未进入上下文）')
+        lines.push('- 可逆原文 blobsStored: ' + stats.blobsStored + ' 份（可用 ctk_retrieve 逐字节取回）')
+        if (stats.slimmed > 0) lines.push('- 瘦身策略: ' + Object.keys(stats.slimStrategies).map((k) => k + '×' + stats.slimStrategies[k]).join(' · '))
         lines.push('- 已注册 registered: ' + stats.registered)
         return { text: lines.join('\n'), isError: false }
       },

package/lib/store.js

@@ -165,13 +165,27 @@ function makeApi(db, dbPath, storageDir) {
       return { id: String(id), text: Buffer.from(row.body).toString('utf8'), bytes: Number(row.bytes) || 0, createdAtMs: Number(row.created_at_ms) || 0 }
     },
 
-    /** Drop stored originals older than the given age, or all of them. */
-    purgeBlobs({ olderThanMs = 0, all = false } = {}) {
+    /**
+     * Drop stored originals: specific ids, everything older than an age, or all.
+     *
+     * The three modes answer different questions. A caller whose marker never reached
+     * the model removes the one id it just wrote; a retention policy removes by age; a
+     * reset removes all. Removing by id first means a rollback cannot take an unrelated
+     * original down with it.
+     */
+    purgeBlobs({ ids = [], olderThanMs = 0, all = false } = {}) {
       if (all) {
         const n = db.prepare('SELECT COUNT(*) AS n FROM blobs').get().n
         db.exec('DELETE FROM blobs;')
         return { removed: Number(n) || 0 }
       }
+      const list = (Array.isArray(ids) ? ids : [ids]).map((v) => String(v || '')).filter(Boolean)
+      if (list.length) {
+        const del = db.prepare('DELETE FROM blobs WHERE blob_id = ?')
+        let removed = 0
+        for (const id of list) removed += Number(del.run(id).changes) || 0
+        return { removed }
+      }
       if (!(olderThanMs > 0)) return { removed: 0 }
       const cutoff = Date.now() - olderThanMs
       const n = db.prepare('SELECT COUNT(*) AS n FROM blobs WHERE created_at_ms < ?').get(cutoff).n
@@ -179,6 +193,15 @@ function makeApi(db, dbPath, storageDir) {
       return { removed: Number(n) || 0 }
     },
 
+    /** Drop originals older than a retention in minutes; 0 means keep forever. */
+    purgeBlobsOlderThan(minutes) {
+      const n = Number(minutes)
+      // An explicit 0 is a policy ("keep forever"), not an oversight, so it must not be
+      // read as "expire immediately".
+      if (!(n > 0)) return { removed: 0 }
+      return this.purgeBlobs({ olderThanMs: n * 60000 })
+    },
+
     /** File one document, replacing any earlier version of the same path. */
     indexDocument({ path, title, text, mtimeMs }) {
       const abs = normalizeTarget(path)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-context-toolkit",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "DeepSeek Harness bundle: native ctk_* sandbox tools, a routing gate that keeps bulk output out of the transcript, and a local full-text knowledge base. No third-party runtime dependencies.",
   "repository": {
     "type": "git",