压缩阈值管理器 frankshi2024/dsh-compact-manager

dsh-compact-manager

面向 DeepSeek Harness（dsh）的分层压缩阈值管理器：让你按全局 → 上下文长度档位 → 模型三级覆盖自动压缩（compaction）的触发点，并在侧边栏里实时查看每个模型当前生效的阈值与策略。

Layered compaction-threshold manager for DeepSeek Harness. Precedence: global → context-window tier → model. Configure it from a sidebar page and see every model's resolved threshold live.

不幸被官方机制压缩到只有四分之一的 K3-256K

不幸被官方机制压缩到只有四分之一的 K3-256K，本仓库的设计缘由。

为什么需要它

dsh 内置的 @deepseek-ai/dsh-compaction-basic 触发阈值是：

floor(min(W × 0.8, W − O − 65536))

其中 W 是模型的上下文窗口，O 是该路由请求的输出预留（模型配置里的 maxTokens）。当模型把输出上限报得很高时，W − O − 65536 这一项会把阈值压到很低。以 256K 窗口、128K 输出预留的 kimi-coding/k3-256k 为例：

| 项 | 取值 |
| W × 0.8 | 209,715 |
| W − O − 65536 | 262,144 − 131,072 − 65,536 = 65,536 |
| 内置阈值 | 65,536（窗口的 25%） |

实测（同一 profile 的历史会话日志，7 次压缩）：压缩全部发生在 65,934–69,573 tokens，正好贴着 65,536。也就是说窗口用到四分之一就开始丢历史。

本插件把「什么时候压缩」变成可配置的三级策略，例如把 256K 档设成 80% 或 W−32K，阈值就从 65,536 变成 209,715。

它只改变触发时机。一次压缩保留多少逐字历史仍由内置后端决定（最近 16% × (W − O)）。区域选择、工具配对、摘要请求全部沿用官方实现。

三级策略与优先级

低 → 高，后者覆盖前者：

1. 全局 — 所有路由
2. 上下文长度档位 — 窗口长度落在档位值的 ±5% 内即算同一档（例如档位 256K = 262144，则 249,037 ~ 275,251 都命中；多档重叠时取最近的一档）
3. 模型 — 精确的 provider/model

每一层都是完整选择：四个项各自只有「启用 / 停用」，没有「继承」。高层一旦存在就整体覆盖低层，所以「档位层」或「模型层」里关掉的项不会从全局层漏回来。

为了不让你因为这条规则踩坑，界面里新增档位/模型覆盖时会以「当前继承到的策略」作为起点（新增档位复制全局策略，新增模型复制该模型当前生效的策略），而不是一上来把四项全关掉。

四个策略项

每个项都可以独立启用/停用，取值自定义；最终阈值取已启用项的最小值再向下取整，其中 absolute 是覆盖规则的例外：

| 项 | 公式 | 含义 |
| ratio | W × v | 上下文的比例（0 < v < 1） |
| outputAware | W − O − v | 扣掉该路由的输出预留 O 和固定值 v |
| fixed | W − v | 只扣固定值 |
| absolute | v | 硬编码阈值：v < W 时直接覆盖另外三项；v ≥ W 时永不触发，被忽略并在预览处给出提醒。只在档位层和模型层可用——全局层没有可比较的窗口 |

没有启用任何项时，插件完全不介入，继续使用官方内置阈值。

安装

在 dsh 中让 agent 调用插件管理器，或使用 CLI：

从 npm（发布后）
dsh plugin --profile <profile> add dsh-compact-manager

从本地目录
dsh plugin --profile <profile> add link:/path/to/dsh-compact-manager

安装后侧边栏会出现「压缩策略」页面。通过 plugin_manager / dsh plugin 安装通常即时生效；若侧边栏没有出现，先刷新浏览器页面，再考虑重启 dsh。

本地 link: 安装不会自动安装被链接包自己的依赖，请在插件仓库里先执行一次 pnpm install（本插件需要 zod）。

侧边栏用法

打开侧边栏的「压缩策略」页：

- 模型下拉：选择任意一个已知路由，页面显示它的 W、O、当前生效阈值、官方内置阈值，以及各启用项的取值和决定项。
- 预设：一键套用常见策略（含 256K 档：80% 或 上下文−32K、256K 档：硬编码阈值 209,715）。
- 全局 / 档位 / 模型策略：每个项都只有一个勾选开关（开/关）加一个数值；档位可增删，模型覆盖的 provider/model 用下拉列表选择。全局层不提供「固定阈值」项，它只出现在档位层和模型层。
- 提醒：当 absolute 的值 ≥ 上下文窗口 W（永远不会触发）时，或当 outputAware 因为 O 过大而主导阈值时，预览区会直接给出黄色提示。
- 保存：写回宿主并持久化；页面每 5 秒、窗口获得焦点时自动刷新，所以「实时看到阈值」不需要手动刷。

工作原理

- 宿主半（lib/index.js）：把策略文档存进 ctx.storageDomain（域名 compact_manager，json 后端落在 $DSH_HOME/storages/），并通过两条自有 /api/compact-manager/* Fetch 路由给浏览器半读写。
- 阈值钩子：Web 组合把压缩放在每个 agent preset 的隔离作用域里（dsh-web-app 停用了 profile 层的 compaction-basic，preset 内以 isolate: { compaction: true } 各挂一份），因此 profile 层的插件注入不到 ctx.compaction。本插件改为装饰 @deepseek-ai/dsh-compaction-basic 导出类的原型方法 compactIfNeeded：压力达到策略阈值就交回内置实现，否则直接返回「不压缩」。这样无论引擎实例在哪个作用域都能生效，context-overflow 恢复路径保持原样。
- 浏览器半（lib/client.js）：手写的 window.__ModuleLoader__.load(...) 经典脚本。第三方插件无法向页面推送自定义事件（转发事件白名单是构建期固定的），因此采用「自行轮询 + 窗口聚焦刷新」。
- 引擎被替换或卸载时，宿主半边通过 Cordis effect 还原原型方法。

HTTP API

| 方法 | 路径 | 说明 |
| GET | /api/compact-manager/state[?refresh=1] | 策略文档、模型表、预设、revision |
| POST | /api/compact-manager/policy | 提交 { document }；校验失败返回 400 与 issues |

策略文档格式

每一层都是完整选择：四项必须各自表态，所以持久化的文档里每层都长这样（未提到的项按「停用 + 默认值」补齐）：

{
"global": {
"ratio": { "enabled": true, "value": 0.8 },
"outputAware": { "enabled": false, "value": 32768 },
"fixed": { "enabled": false, "value": 32768 },
"absolute": { "enabled": false, "value": 131072 }
},
"tiers": [
{
"window": 262144,
"policy": {
"ratio": { "enabled": true, "value": 0.8 },
"outputAware": { "enabled": false, "value": 32768 },
"fixed": { "enabled": true, "value": 32768 },
"absolute": { "enabled": false, "value": 131072 }
}
}
],
"models": [
{
"provider": "kimi-coding",
"model": "k3-256k",
"policy": {
"ratio": { "enabled": true, "value": 0.7 },
"outputAware": { "enabled": false, "value": 32768 },
"fixed": { "enabled": false, "value": 32768 },
"absolute": { "enabled": false, "value": 131072 }
}
}
]
}

开发

无构建步骤：宿主半是普通 ESM，浏览器半是手写的 ModuleLoader 包装。

npm test # 纯函数策略测试（node --test）

lib/policy.js 纯策略词汇与解析（无依赖，可直接复用/测试） lib/schema.js storageDomain 记录 schema（zod） lib/index.js 宿主插件 lib/client.js 浏览器插件

已知限制

- 只覆盖压力触发；上下文溢出恢复（context-overflow）仍走官方路径。
- 只改变触发阈值，不改变一次压缩的保留比例。
- 原型钩子作用于所有会话（策略本身就是进程级配置）。引擎模块被热替换后会重新导入并再次挂钩；若宿主改用不继承该原型的自定义压缩后端，钩子不会生效（宿主日志会给出告警）。
- 模型下拉来自 ctx.llm.listProviders() × listModels()；不公开目录的 provider（例如某些账号型 provider 未登录时）不会出现在列表里，也就无法为它新增覆盖（已经存在的条目仍会保留并显示）。
- 页面数据来自宿主自有路由，因此不受 dsh 的 Remote 事件白名单限制，但也因此不会收到推送，只能轮询/聚焦刷新。
- 与任何同样装饰 compactIfNeeded 的插件（例如本仓库同作者早期的 compaction-threshold-override）功能重叠，建议只保留一个。

License

MIT