前言¶

在 DeepSeek Harness（DSH）里做长会话时，上下文会逼近压缩阈值。DSH 自带的 dsh-compaction-basic 在 agent/pre-step 测压，超过阈值后同步调用模型写摘要并提交 checkpoint，这段时间界面往往表现为「卡住」。输入侧前缀可以命中 KV 缓存，真正拖慢的是摘要的输出。把生成挪到用户不需要等待的时间窗，是这条路径上唯一有效的优化方向。

下面介绍社区插件 dsh-background-compaction（维护者 OZONGO，分类：工作流）。它在上下文到达阈值之前用一次几乎全缓存的模型调用，把截至上一轮的历史在后台总结成摘要；摘要就绪后的下一个回合边界，用 0 次模型调用把摘要提交成 checkpoint，用户可以继续对话。

这是什么¶

dsh-background-compaction 是 DSH 宿主平面上的压缩引擎扩展：接管压缩的触发时机，不改变 checkpoint 渲染、日志格式或计价规则。压缩后模型看到的是 摘要 + 上一整轮原文。

• 仓库：OZONGO/dsh-background-compaction
• 目录页：skillhub.cn 插件条目
• 当前 package 版本：0.1.0，许可证 MIT
• Node 要求：>=22.12.0

DSH 生态是「一切皆插件」；社区目录站点与 DeepSeek / 幻方无官方从属关系。

与原生压缩的差异¶

原生路径：没到阈值什么都不做；一到阈值就在 pre-step 同步 summarization。

本插件路径示意：

回合 N-1（上下文到自动触发比例，默认 85% × thresholdTokens）
  └─ 起游离任务，后台总结 [首节点 .. 上一轮结束]（约 30~60s，用户可继续对话）

回合 N（摘要已就绪）
  └─ pre-step 提交 held 摘要（毫秒级，summarize 指纹命中 → 0 次模型调用）
     本轮请求 ≈ system + 摘要 + 上一轮原文 + 本轮消息

Web 版把压缩放在 agent preset 里；本插件挂在宿主平面，通过 agent/pre-step 工作，并继承 compactRegion 自行提交。preset 里的原生引擎仍作兜底（摘要没赶上、上下文溢出、/compact 等）。子 agent（delegationDepth > 0）不做后台预计算。

核心功能¶

自动压缩¶

无需额外操作。当上下文达到 thresholdTokens × 自动触发比例（默认 0.85）时后台开始生成；摘要就绪后的下一回合自动换入。

注意：所有比例相对 DSH 的 thresholdTokens，不是 contextWindow × 0.8。以 200k 窗口为例，README 给出 thresholdTokens = min(160000, 68928) = **68928**，85% 触发点约 58.6k token，而非按窗口心算的 170k。

手动命令 /bcompact¶

命令在回合之外执行，不能同步压缩（公开 compactRegion 要求 open turn）。

实现方式：起后台任务 + 必要时 agent.followup(消息)。

设置页与配置文件¶

设置 → 后台压缩 三项，改完立即生效，无需重启：

持久化路径：~/.dsh/background-compaction/config.json

{
  "$schema": 1,
  "autoTriggerRatio": 0.85,
  "summarizationModel": { "provider": "", "model": "" },
  "maxFailures": 2
}

优先级：设置文件 > YAML 配置 > 内置默认值；只有文件里出现的键才覆盖 YAML。

YAML（bundle / profile patch）还可配置 background 段，例如 startRatio、tailRatio、minShadowedRatio、holdTtlMs、maxFailures、failureCooldownMs 等，详见仓库 README 第 6 节。

安装与启用¶

插件以当前 DSH 进程权限运行；安装前请自行审阅源码与 MIT 许可证。安装命令以仓库 README 为准，不要凭插件名拼接未文档化的 CLI。

从 Git 安装¶

cd ~/.dsh/profiles/desktop
pnpm add github:OZONGO/dsh-background-compaction

从本地目录安装（开发）¶

cd ~/.dsh/profiles/desktop
pnpm add file:E:/AI/workspace/dsh-plugin/dsh-background-compaction

（将 file: 路径改为你本机克隆或下载的目录。）

注册 bundle¶

在 profile 的 package.json 中把包名加入 dsh.profile.bundles，并在 dependencies 中声明依赖，例如：

{
  "dsh": {
    "profile": {
      "bundles": ["...", "dsh-background-compaction"]
    }
  },
  "dependencies": {
    "dsh-background-compaction": "github:OZONGO/dsh-background-compaction"
  }
}

然后重启 DSH（宿主默认不支持热加载 bundle）。

确认加载¶

宿主日志（Windows 示例：%APPDATA%/DSH Desktop/logs/host/dsh-YYYY-MM-DD.log）应出现类似：

[background-compaction-engine] background-compaction: engine ready (auto=true, startRatio=0.85, maxFailures=2, state=…)

设置面板左侧应出现 后台压缩 一页。

典型用法与验收¶

README 给出三步验收，无需刻意堆长对话：

1. 新会话做 2–3 轮对话（例如读一个文件，几百到几千 token）——应正常。
2. 输入 /bcompact 继续——应立即得到回答；日志出现 held ready。
3. 再发一条消息——该轮 pre-step 提交摘要；日志出现 swap hit；生成 ~/.dsh/background-compaction/last-swap.json。

/bcompact 需要非空且平衡的可压缩区间（绝对下限 512 token）；历史太短会提示「历史太短，压缩没有意义」。自动路径还要求被压缩区间至少为 thresholdTokens 的 10%（200k 窗口约 6.9k token）。

last-swap.json 中的 messages 来自提交之后的 session.deriveMessages()，可用来核对下一轮真正发出的 surface（摘要 + 保留尾巴）。

常用日志关键字：engine ready、started、held ready、swap hit、discarded、summarize miss。

适用场景与注意¶

适合：桌面 DSH 长会话、希望压缩发生在对话间隙而非 pre-step 阻塞的用户；需要与官方 /compact、溢出恢复、tool result pruner 共存时（本插件只改触发时机）。

注意：

• 摘要仅在前缀指纹、路由、surface 首节点等仍一致时换入；否则丢弃（见 README 失效矩阵）。任意 compaction/start（含 /compact）会中止在飞的后台任务。
• auto: false（YAML）时后台完全停止。
• 开发时在 Windows 上链本地包须用目录联接（junction），避免 Git Bash ln -s 退化成复制导致改代码不生效（README 8.1 节）。
• 升级 @deepseek-ai/dsh-compaction-basic 后，维护者建议先跑插件内 npm test（116 个用例，含真实 Session 换入）。

结尾¶

dsh-background-compaction 把上下文摘要生成提前到阈值前的空闲窗口，在下一回合用 held 摘要完成 checkpoint，避免 pre-step 同步等待。若你在 DSH 里常被压缩卡顿打断，可按上文安装并在设置里调整触发比例与摘要模型。

• 目录页：https://www.skillhub.cn/plugins/OZONGO/dsh-background-compaction
• GitHub：https://github.com/OZONGO/dsh-background-compaction