前言¶

在 DeepSeek Harness（DSH）里，web profile 把 compaction 后端写在 agent preset 的 config.plugins 中。若只想调整 @deepseek-ai/dsh-compaction-basic 的自动压缩压力阈值（thresholdRatio），常见做法是改 profile patch（cordis.patch.yml）。但 patch 对一行是整体替换 config，而 preset 里声明的插件行又不在 patch 可递归的 group 结构里——往往要把上百行 preset 声明整份复制进 profile，bundle 升级后还容易和上游失同步。

dsh-compaction-threshold 由社区维护者 Lyoko-Jeremie 提供，在运行时替换 preset 内已挂载的 basic 压缩引擎配置，profile 里只需多挂一个插件 bundle，不必重述整份 preset。

这是什么¶

dsh-compaction-threshold 是一个 DSH Cordis bundle（npm 包名 dsh-compaction-threshold，当前版本 0.1.0，MIT 许可）。它监听 agent 创建事件，通过 preset registry 定位 dsh-compaction-basic 引擎实例，用新的 thresholdRatio 整体替换其已解析且被冻结的 config，不改动 preset 声明文件，也不引入第二份压缩引擎包。

工作原理概要¶

下面介绍插件在 Harness 内的介入顺序，便于理解为何能「只改阈值、不复制 preset」。

1. 监听 agent/created（此时 agent 的 preset generation 已挂载）。
2. 通过 agentPresets.serviceFor(agent, 'compaction') 读取该 preset isolate 域内的 compaction 服务；若无 registry 或找不到服务，则回退到 agent.ctx.get('compaction')。
3. 用结构判断识别 basic 引擎（检查已解析 config 上是否存在数值型 thresholdRatio），不依赖模块身份。
4. 因引擎 config 经 deepFreeze，插件整体替换实例的 config 属性，而非就地改冻结对象。
5. 不修改任何 preset 声明或既有配置文件。

shipped preset 将 compaction group 声明为 isolate: { compaction: true }，服务注册在 group 私有 realm；父级 agent 作用域用根符号查找会得到 undefined，因此不能单靠 agent.ctx.get('compaction')。serviceFor 是 preset registry 提供的、能读到 mount 内实现的入口。

安装与启用¶

方式一：Plugin Manager（推荐）¶

在 Harness Web UI 中让 agent 调用 plugin_manager 的 install_bundle，目标为本插件目录或发布后的 GitHub 包，由管理器完成依赖安装与 bundle 选择。

方式二：手动加入 profile¶

编辑 $DSH_HOME/profiles/<name>/package.json，在既有 bundles 与 dependencies 中增加本包：

{
  "dsh": {
    "profile": {
      "bundles": [/* 既有 bundles */, "dsh-compaction-threshold"]
    }
  },
  "dependencies": {
    "dsh-compaction-threshold": "github:<user>/<repo>"
  }
}

在 profile 目录执行 pnpm install，并重启 dsh web。包名须与 cordis.patch.yml 里 name 字段一致；若重命名包（例如加 scope），需同步修改该字段。

配置 thresholdRatio¶

bundle 默认 thresholdRatio 为 0.5。在 profile 的 cordis.patch.yml 中按行 id 覆盖整个 config：

- id: compaction-threshold
  config:
    thresholdRatio: 0.6

合法范围为 (0, 1]，且必须大于引擎的 retainRatio（默认 0.16），否则自动压缩会在运行时拒绝该配置。

实际触发用的 token 数并非简单的 contextWindow × thresholdRatio，而是：

thresholdTokens = min(contextWindow × thresholdRatio,
                      contextWindow − maxTokens − headroomTokens)

例如 contextWindow = 1,048,576、maxTokens = 256,000、headroomTokens = 65,536 时，thresholdRatio 为 0.8 与 0.5 对应的实际阈值分别为 727,040 与 524,288。

验证是否生效¶

经过上面的步骤并重启后，可按 README 建议观察日志：

• 启动时出现 dsh-compaction-threshold: pressure threshold set to 0.5（或你配置的值）。
• 上下文用量接近阈值时出现 compaction (step pressure)。
• 若 preset 内没有 basic 引擎（换了其他压缩后端），插件会打 debug 日志并跳过。
• 在 isolate preset 下，agent.ctx.get('compaction') 为 undefined 属正常；插件会走 preset registry。

适用场景与注意¶

适合谁： 已在 web profile 使用 shipped preset 与 dsh-compaction-basic，只想微调自动压缩触发时机、又不想维护整份 preset 复制的开发者。

权限与安全： 插件与当前 dsh 进程同权运行，安装前请阅读仓库源码并确认 MIT 许可与行为是否符合预期。本方式属于社区扩展，不是 Harness 文档化的官方扩展点。

行为边界（摘自维护者说明）：

• 仅作用于 preset 内运行的 dsh-compaction-basic；host 层 disabled: true 的行不受影响。
• 手动 /compact 与自动压缩共用覆盖后的阈值。
• 只对插件加载后创建的 agent 生效；HMR 重载后需新会话才会应用。
• 依赖 BasicCompactionEngine.config 的实例属性形态；Harness 内部结构变化时可能只打 warning 并保持原阈值。
• 依赖 @deepseek-ai/dsh-agent-preset-registry 的 serviceFor；registry 缺失或改名时，在 isolate preset 下可能不再生效。
• 绕过引擎启动期的 resolveConfig 校验；范围与 retainRatio 冲突由插件自行校验。

卸载时从 dsh.profile.bundles 移除该 bundle（或删除对应插件行），执行 pnpm install 后重启即可。

链接¶

• 社区插件目录：https://www.skillhub.cn/plugins/Lyoko-Jeremie/dsh-compaction-threshold
• 源码与完整说明：https://github.com/Lyoko-Jeremie/dsh-compaction-threshold