前言¶
在 DeepSeek Harness（DSH）里做长会话智能体开发时，上下文窗口迟早会顶到压力阈值。原生 compaction-basic 会在阈值到达后发起一次摘要模型调用，这段时间里当前回合处于前台阻塞——界面转圈、工具链停住。裁剪工具输出（例如 tool-result-pruner）能减轻载荷，但基准数据显示阻塞时长几乎不变，因为主要成本是一次模型往返，而不是发送体积。
下面介绍社区插件 dsh-plugin-background-compaction：它在对话越过水位线后于后台投机生成摘要并持有，阈值触发时直接提交已校验结果，把「压缩卡顿」从关键路径上挪走。维护者为 GitHub 用户 Jisiyong-A，当前版本 v2.0.1，MIT 许可，分类为模型推理。插件目录页托管在 SkillHub（独立社区站点，与 DeepSeek / 幻方无官方从属关系）。
这是什么¶
一句话定位：该插件是 compaction-basic 的替代品（不是旁挂组件）。DSH 在每个上下文中只挂载一个 CompactionEngine 作为 ctx.compaction，因此要改变压缩行为，插件必须接管这一服务。
它解决的核心问题是：原生压缩在触发瞬间才调用 summarizer，用户必须等待整段模型往返。本插件在达到硬阈值之前（默认约为阈值的 72%）后台调用 super.summarize()，持有 SummaryResult；阈值到达时 summarize() 直接交出持有摘要，不再发起模型调用。摘要仍由模型生成（与规则型压缩器 dsh-dcp 不同），失败路径一律退化为一次原生 compaction-basic，不会留下宿主读不懂的状态。
核心功能¶
零等待提交（有测量依据）¶
在同一份 16 份文档、约 49K token 的任务上，作者从会话事件日志读取 compaction/end.time − compaction/start.time（基类在构建摘要输入前写入 compaction/start），三次运行取中位数：
原生 compaction-basic |
本插件 | |
|---|---|---|
| 压缩期间回合冻结 | 16,095 ms | 7 ms |
完整对照与复现方式见仓库 benchmark/ 与 BENCHMARK.md。
与裁剪器、确定性压缩的分工¶
tool-result-pruner：基准中阻塞从 16.1 s 仅降到 15.3 s（约 5%）。本插件在提交前仍会跑裁剪器，两层叠加。dsh-dcp：延迟同样可忽略（12 ms vs 7 ms），但摘要由规则生成，无法压缩语义；本插件多约 2% 计费输入（缓存摊薄后），保留模型摘要能力。
相对原生方案，基准中计费输入约 +2.2%，缓存输入 +1.5%，输出 −4.0%——后台调用与最终提交共用 prompt 前缀，投机调用大多命中已预热缓存。
钉住 span 与指纹校验¶
compactRegion(start, end) 从不可变的 surface 序号重新推导摘要输入，使预计算与提交时 payload 逐字节一致。提交前 fingerprintSummarizationInput()（SHA-256 覆盖系统头、被遮蔽消息、工具定义及 { provider, model, maxTokens }）与预计算时记录值比对；漂移则丢弃持有项并走一次原生 super.compactIfNeeded()。
Fail-open¶
未达阈值、TTL 过期、裁剪改写 surface、compactRegion 拒绝、前台抢先压缩、auto: false / enabled: false 等路径，最坏情况与原生 compaction-basic 一致。
安装与启用¶
DSH 要求 Node.js >= 20；插件声明 dsh 引擎 >=0.2.1-rc.5，并依赖 @deepseek-ai/dsh-compaction 与 @deepseek-ai/dsh-compaction-basic（peerDependencies，版本区间与 package.json 一致）。
安装命令来自官方 README（需指向已获取的包目录，而非凭名称拼接 GitHub 短路径）：
dsh plugin --profile <profile> add <path-to-this-package>
peerDependencies 声明与 DSH 启动期 routeLinked 模块拦截相关：只有包名出现在插件 peerDependencies 中时，链接插件的 @deepseek-ai/* 导入才会路由到运行中 app.asar 内置副本。
随包附带的 cordis.patch.yml 会禁用 compaction-basic 并插入本引擎。典型片段如下：
- id: compaction-basic
disabled: true
- insert:
- id: background-compaction
name: dsh-plugin-background-compaction
config:
enabled: true
precomputeAtRatio: 0.72
经过上面的步骤，压缩服务由 background-compaction 接管；基类键（如 thresholdRatio、headroomTokens）仍透传给 BasicCompactionEngine。
典型用法与配置¶
日常使用时多数场景只需保持 enabled: true 与默认 precomputeAtRatio: 0.72。需要调参时，在 patch 的 config 中修改；基类键与后台键分开，未知键会导致基类在校验时抛错。
与本插件直接相关的常用项：
| 键 | 默认值 | 含义 |
|---|---|---|
enabled |
true |
总开关；false 时行为等同纯 compaction-basic |
precomputeAtRatio |
0.72 |
占 thresholdTokens 的比例，越过即武装后台投机 |
heldTtlMs |
300000 |
持有摘要有效期（毫秒） |
debounceMs |
1500 |
投机开始前的静默期 |
gateEnabled |
true |
滑窗命中率熔断，预测失准时暂停投机 |
trace |
false |
输出 [bgc] 诊断；环境变量 DBG_BGC=1 亦可开启 |
若要自行验证构建与单测（在插件源码目录内）：
pnpm exec tsc --noEmit
node scripts/build.mjs
node scripts/test.mjs
跨策略端到端证据在 BENCHMARK.md；真实 dsh --profile bc-headless 进程记录见 SANDBOX-REPORT.md。
适用场景与注意¶
更适合：长会话、频繁触发压缩、希望保留 LLM 摘要语义且不能接受十几秒回合冻结的 DSH 开发者；可与 tool-result-pruner 叠加。
考虑其他方案：
- 严格控 token、可接受规则摘要 →
dsh-dcp（后台零额外模型调用）。 - 保真度为硬指标 → 任何压缩策略都可能丢信息；基准 workload 下四组均保留 3/3 事实，不代表无损。
已知限制（README 原文）：
- 预计算与提交之间若 surface 被改写，持有摘要可能作废，多花一次后台调用（基准中 3 次里有 2 次观测到）。
- 单步直接跨过阈值时跳过准备窗口，退化为原生行为。
- headless runner 在 surface 折叠后重新注入完整提示包，可能抵消部分压缩收益。
- 无法与
compaction-basic并存，只能替换。
安全与信任：DSH 插件以当前 DSH 进程的权限运行。安装前应阅读仓库源码与 MIT 许可证，确认 patch 与配置符合你的 profile 策略；SkillHub 目录页便于发现插件，但不替代你对源码的审查。
结尾¶
dsh-plugin-background-compaction 用后台投机摘要把压缩从「前台等模型」改成「阈值处毫秒级提交」，在作者基准里回合冻结从约 16 s 降到 7 ms，token 开销约 +2%。它是 DSH「一切皆插件」生态里针对 CompactionEngine 的一条路径，与确定性压缩、工具裁剪解决的是不同层面的问题。
- 目录页：https://www.skillhub.cn/plugins/Jisiyong-A/dsh-plugin-background-compaction
- 源码与文档：https://github.com/Jisiyong-A/dsh-plugin-background-compaction
