dsh-compaction-cacheaware：DeepSeek Harness 中的 Reasonix 风格压缩后端

在 DeepSeek Harness (DSH) 的插件生态中，处理长对话上下文时，压缩策略决定了系统的稳定性和推理成本。DSH 自带的 compaction-basic 是一个基础实现。如果需要更接近 Reasonix 的缓存感知压缩逻辑，可以使用 dsh-compaction-cacheaware。这是一个独立、模块化的 DSH 插件，实现了官方的 ctx.compaction 接口。

插件定位与特性¶

该插件旨在为 DSH 提供一个 Reasonix 风格的后端。它不修改其他插件、预设或宿主文件，通过挂载来替换默认的压缩行为。

核心能力包括：
* Reasonix 风格设计：实现了缓存感知压缩的核心逻辑。
* 模块化实现：仅注册 ctx.compaction 及其自动监听器，不干涉其他组件。
* 官方接口对接：实现了 @deepseek-ai/dsh-compaction 的 ctx.compaction 接口。
* 自动同步：支持从 esengine/DeepSeek-Reasonix 自动同步设计更新。
* 单一触发机制：仅使用 compact_ratio（默认 0.85）作为自动触发条件。
* 结构化检查点：生成包含稳定前缀、摘要和近期尾部（recent tail）的结构化检查点。
* Realm 自检：具备 Realm 自检机制，防止在同一个领域内发生竞态条件。
* 非侵入性：安装后不影响现有的插件、预设或宿主文件配置。

安装¶

插件已发布至 npm registry，推荐通过 pnpm 安装。

    cd "$env:USERPROFILE\.dsh\profiles\web"

执行安装命令：

    pnpm add dsh-compaction-cacheaware

也可以从 GitHub 直接安装：

pnpm add dsh-compaction-cacheaware@github:Zhuchen00123/dsh-compaction-cacheaware

配置与启用¶

安装后，需要在预设的压缩领域（compaction realm）中挂载该插件以替换默认的 compaction-basic。

注意：Profile 级别的 bundle 补丁无法覆盖 Agent 预设内部的隔离压缩领域，因此必须手动在每个预设中配置。

配置示例¶

在 Agent 预设的 YAML 配置中，将 compaction-basic 替换为 dsh-compaction-cacheaware：

- id: compaction-cacheaware
  name: 'dsh-compaction-cacheaware'
  config:
    compactRatio: 0.85
    checkpointCeilingRatio: 0.5
    recentTailRatio: 0.1
    recentTailMinTokens: 8192
    recentTailMaxTokens: 16384
    summaryMaxTokens: 16384

同时，需要将 @deepseek-ai/dsh-command-compact 放在同一个 realm 中，以便 /compact 命令能够使用该后端。

配置参数¶

Key	Default	Meaning
`compactRatio`	`0.85`	唯一的自动触发阈值，决定上下文压缩的触发点。
`checkpointCeilingRatio`	`0.5`	正常自动检查点接受的阈值上限。
`recentTailRatio`	`0.1`	近期原文尾部保留的比例。
`recentTailMinTokens`	`8192`	生产尾部的下限。
`recentTailMaxTokens`	`16384`	生产尾部的上限。
`summaryMaxTokens`	`16384`	摘要生成器的输出上限。
`exceptionalMinSavingsRatio`	`0.25`	当固定前缀超过阈值时，所需的最低节省比例。
`minRecentKeep`	`2`	最近保留的最小消息数。
`minCompactMessages`	`2`	可压缩的最小消息数。
`maxPinnedFirstUserTokens`	`1500`	首轮用户对话被固定的 Token 上限。
`pinnedFirstUserWindowFrac`	`0.15`	首用户固定窗口的分数上限。
`protocolReserveTokens`	`256`	协议保留 Token。
`summarizationProvider` / `summarizationModel`	`''`	可选的摘要路由，默认使用对话路由。
`auto`	`true`	注册自动压力/溢出监听器。

注意事项¶

运行环境：要求 Node.js 版本 >= 22。
许可证：MIT。
非侵入性：插件不会修改 dsh-wsl-bash、dsh-team-dashboard 等其他插件或宿主文件。
隔离领域限制：Profile 级别的 bundle 补丁无法直接作用于 Agent 预设的隔离压缩领域。如果预设中已经包含了 compaction-basic，必须单独迁移该预设以使用此插件。

总结¶

dsh-compaction-cacheaware 为 DSH 提供了一个从 Reasonix 迁移而来的、经过结构化设计的压缩后端。它通过单一的触发机制和结构化的检查点设计，优化了长上下文的处理流程。开发者可以通过简单的替换操作，在 Agent 预设中启用这一能力。

更多细节与源码，请参考 GitHub 仓库。