前言¶
DeepSeek Harness (DSH) 的上下文压缩层主要负责管理对话上下文。其中的 dsh-compaction-basic 负责对工具结果进行总结，这是一个调用昂贵模型的过程。如果上下文溢出但压力尚未达到总结阈值，直接总结往往是不必要的开销。dsh-compaction-micro 插件旨在填补这一空缺，它作为一个独立的“微清理层”，在官方总结层之前，将白名单内的可重运行工具结果替换为占位符，从而在不调用模型的情况下快速释放 Token 空间。
它是什么¶
这是一个为 DeepSeek Harness 压缩流程设计的微型清理层。它遵循观察者模式：不修改模型请求，不发起模型调用，仅通过替换 tool/result 内容来触发压缩事件。每次重写操作都会伴随一个 compaction/prune 事件，确保持久化日志仍作为可重构的事实来源。
- 所有者：Perfirstvito
- 许可证：MIT
- 定位：在官方总结层之前介入的预压缩层。
安装与启用¶
安装该插件需要使用本地链接的方式。在插件目录下执行以下命令：
dsh plugin --profile headless add link:<this-dir>
配置说明¶
该插件通过配置项控制清理行为。以下是核心配置项：
| 字段 | 默认值 | 说明 |
|---|---|---|
clearableTools |
[] |
允许被清理的工具白名单。仅限只读、可重运行工具（如 read, glob, grep）。留空则禁用该层。 |
retainRecent |
3 |
保留最新的 N 个可清理结果在上下文中可见。 |
microThresholdRatio |
0.85 |
清理触发的阈值比例。当 Token 占用超过 (contextWindow - reservedTokens) * 0.85 时触发。 |
reservedTokens |
0 |
从有效上下文窗口中预先扣除的 Token 数量。 |
auto |
true |
是否自动安装监听器。设为 false 时仅暴露 ctx.microCompaction.clearSession()。 |
使用示例¶
通常需要将此插件挂载在 dsh-compaction-basic 之前。在 DSH 的插件配置中，建议按以下顺序排列：
- name: '@deepseek-ai/dsh-token-meter'
- name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
- name: '@deepseek-ai/dsh-compaction-basic'
config:
thresholdRatio: 0.9
- name: 'dsh-compaction-micro'
config:
clearableTools: [read, glob, grep, web_search, web_fetch]
retainRecent: 3
microThresholdRatio: 0.85
reservedTokens: 0
工作原理¶
插件通过两个前置监听器工作：
-
agent/pre-step(prepend)：- 监听并测量上下文压力。
- 当
totalTokens达到阈值（即(contextWindow - reservedTokens) × microThresholdRatio）时，按从旧到新的顺序清除白名单工具结果，但始终保留最近retainRecent个结果可见。 - 清理后，底层会重新测量，若压力已缓解，则跳过昂贵的总结步骤。
-
agent/request-error(prepend)：- 当确认发生上下文溢出时，优先执行清理操作。
- 清理完成后，再将控制权委托给官方的后端修剪、总结及重试流程。
注意事项¶
- 挂载顺序：虽然监听器设置了
prepend: true，但为了确保逻辑顺序正确，建议将dsh-compaction-microbundle 挂载在dsh-compaction-basic之前。 - 工具安全：该插件仅对只读、可重运行工具（如读取文件、搜索内容）安全。写操作、编辑、Shell 调用等工具必须从
clearableTools白名单中移除，否则可能导致不可逆的数据丢失。 - 权限运行：插件以当前 DSH 进程权限运行，使用前请检查源码与许可证。
开发¶
本地开发需要将 DSH 的工作空间包 junction 到 node_modules/@deepseek-ai 目录下。
npm run typecheck # TypeScript 类型检查
node --import tsx --test tests/micro.test.ts
