kusesad-1122/dsh-context-compactor

dsh-context-compactor

开箱即用的 上下文压缩 / 上下文总结 插件。它把 DSH 官方 dsh-compaction-basic
压缩引擎 + 工具结果裁剪器一次性装配进 profile，解决「对话满了不会自动压缩、模型
直接报 maximum context length 导致本轮失败」的问题。

功能

1. 80% 自动触发（总结最优先 + 压缩后验）

- 通过 ctx.tokenMeter 估算当前会话 token 用量；
- 达到模型窗口 80%（thresholdRatio 默认 0.8）时，下一步前自动先做详细总结：
把全部较早历史用 LLM 压缩成一份详尽中文 checkpoint，替换旧消息，只保留最近
retainRatio（默认 16%）的原样尾巴；
- 本引擎的监听器以 prepend 注册，会抢在任何 preset 默认压缩引擎之前执行，
保证“总结最优先”且用的是详细版总结；
- 压缩前后都有会话日志事件（compaction/start、compaction/summary、compaction/end）。

1.5 硬性保证：压缩必须真的变小

- 每次压缩都会做 before/after 校验：压缩后 totalTokens 必须严格小于压缩前；
- 自动压缩：
- 目标 = 低于 80% 阈值（所以 80% → 必须 .md（默认开启，
可关 saveSummaryFile: false）；
- 总结调用生成上限默认 maxTokens: 12288（详细预算，可调大）。

3. context-overflow 自动恢复（专治 context length 报错）

- provider 明确报上下文超限时，先详细总结压缩，再自动 retry 本轮请求；
- 默认最多连续恢复 maxOverflowRetries 次。

4. 超大工具结果裁剪（辅助手段，不替代总结）

- 超过 pruneThresholdChars（默认 8192 字符）的工具输出，保留头 + 标记 + 尾；
- 只裁剪工具结果文本，对话历史一律走详细总结，绝不粗暴截断。

5. 输入框上方的「压缩总结」+「提示增强」按钮

- 浏览器半边通过 dsh.client 清单自动发现，注册到 conversation.input.dock
（输入框正上方，与 goal/todo 工具条同一排）；
- 工具条实时显示上下文用量百分比（contextPressure 投影），到 80% 自动
高亮提醒；
- 左侧按钮「压缩总结」：点击通过 remote.commands.execute(sessionId, '/compact')
立即触发全局详细总结压缩，按钮会显示「压缩总结中…」并在条上回显结果；
- 右侧按钮「提示增强」：这是合并自 LLM-Prompt-Enhancer
的功能，点击读取输入框草稿，调用 DSH 当前模型增强为更清晰的提示词，
自动写回输入框（无需额外 Groq Key）；按钮显示「增强中…」并在条上回显结果；
- agent 运行中按钮自动禁用；全新空白会话不显示。

6. 手动命令

| 命令 | 作用 |
| --- | --- |
| /compact | 立即【全局详细总结】并把全部较早历史压缩成一个 checkpoint |
| /enhance-prompt | 用当前模型增强提示词（支持直接跟文本或 JSON {"text":"..."}） |
| /context-status | 查看 token 用量、窗口、80% 阈值、风险与总结保存路径 |

默认配置

enabled: true
auto: true                      # 开启 80% 压力压缩 + overflow 自动恢复
thresholdRatio: 0.8             # 用量达到窗口 80% 触发【详细总结】压缩
retainRatio: 0.16               # 保留最近 16% 的原样对话
maxTokens: 12288                # 总结调用生成上限（详细预算）
compactionRetries: 1            # 一次压力压缩后仍超阈值时的追加尝试
maxOverflowRetries: 2           # context-overflow 恢复重试上限
saveSummaryFile: true           # 总结额外落盘到 ~/.dsh/storages/dsh-context-compactor/summaries/
pruneToolResults: true          # 只裁剪超大工具结果；对话历史一律走总结
pruneThresholdChars: 8192
pruneHeadChars: 4096
pruneTailChars: 1024
registerCommands: true

也可以给指定模型写精确覆盖策略：

modelPolicies:
- provider: deepseek
model: deepseek-chat
thresholdRatio: 0.7
retainRatio: 0.2
maxOverflowRetries: 3

工作原理（与官方架构一致）

DSH 的 dsh-web-app 会禁用宿主层的压缩后端，压缩由每个 agent preset 决定。
本插件不跟宿主层抢位置：它监听 agent/created（并补扫已存活 agent），对没有压缩
引擎的 agent 在其 agent scope 内用独立 isolate 挂载 compaction-basic 和
tool-result-pruner——等价于官方 standard preset 里的

- id: compaction
name: cordis:group
group: true
isolate: { compaction: true, toolResultPruner: true }
config:
- id: compaction-basic
name: '@deepseek-ai/dsh-compaction-basic'
- id: command-compact
name: '@deepseek-ai/dsh-command-compact'
- id: tool-result-pruner
name: '@deepseek-ai/dsh-compaction-tool-result-pruner'

因此：

- 每个 agent 一个独立槽位，不会抢占全局服务名；
- 即使 preset 自带默认引擎，本引擎的 prepend 监听器也会在自动压缩中先执行，
保证“详细总结优先”；
- 引擎生命周期跟随 agent，agent 销毁即回收。

安装

1. 构建（host: src → lib/index.js；client: src/client → lib/client.js）
bash scripts/build.sh

2. 加入 profile（写入 dependencies + bundles，重启后自动装配）
profile 包名：@dsh-external/dsh-context-compactor
根入口 index.js 同时兼容「按包根 index.js 导入」的 loader 约定。
浏览器按钮无需额外配置：clientModules 会通过 dsh.client 清单 +
exports["./client"] 自动发现并伺服 lib/client.js。

3. 热装配（当前进程立即生效）
dev_install_package / dev_inject_plugin 指向本目录
若遇到 loader 模块缓存中毒，重启 DSH 即可（bundle 路径不依赖热装配）。

装配后刷新页面，输入框上方会出现「压缩总结」工具条；输入
/context-status 可查看用量与阈值。

说明

- 总结调用会优先复用当前会话实际路由的 provider/model；也可用
summarizationProvider + summarizationModel 指定专门的总结模型。
- 单条消息本身就超过模型窗口时，任何表面压缩都无法修复——这种情况需要
换更大窗口的模型或拆小输入。