前言¶

在开发 DeepSeek Harness 智能体时，长对话历史和大量工具输出容易导致上下文溢出。宿主原有的压缩流程有时缺乏明确的收益判断，或难以精细控制关键记忆与诊断信息的保留。下面介绍 dsh-ctxopt-compaction，一个在宿主原有压缩流程基础上增加收益判断、有界摘要缓存、显式记忆控制以及保留诊断信息的工具输出裁剪插件。

插件简介¶

dsh-ctxopt-compaction 是 DeepSeek Harness 的上下文压缩插件，由维护者 chunsi-w 开发。当前版本为 0.0.1。它不作为独立聊天服务运行，而是依赖宿主提供必要的依赖（包括压缩引擎、工具裁剪、LLM、会话与 Schemastery）。插件通过 JavaScript 源码提供功能，无需转译。

安装与启用¶

在宿主环境中启用该插件，需要先获取并打包源码，然后通过宿主的安装机制加载。

获取与打包¶

git clone https://github.com/chunsi-w/dsh-ctxopt-compaction.git
cd dsh-ctxopt-compaction
npm pack

生成的包名为 dsh-ctxopt-compaction-0.0.1.tgz。

Headless 加载¶

在已安装依赖并构建完成的 DeepSeek Harness 目录中执行以下命令，替换插件的绝对路径：

pnpm dsh plugin --profile headless add file:/absolute/path/to/dsh-ctxopt-compaction
pnpm dsh --profile headless --dump-config

执行后检查生成配置中是否包含 ctxopt-compaction 和 ctxopt-tool-result-pruner，并确认同层默认组件已禁用。

Web 加载¶

在 Web 环境中，仅安装顶层 bundle 或直接传入 cordis.patch.yml 不足以替换 standard 预设中的默认组件。需基于宿主的 packages/bundle/web-app/presets/standard.patch.yml 创建覆盖配置。在 compaction 组内，将 compaction-basic 的 name 改为本仓库 src/engine.js 的绝对路径，将 tool-result-pruner 的 name 改为 src/pruner.js 的绝对路径。

- id: compaction-basic
  name: /absolute/path/to/dsh-ctxopt-compaction/src/engine.js
  config:
    thresholdRatio: 0.4
    headroomTokens: 512
    retainTokens: 1400
    maxTokens: 1536
    compactionRetries: 1
- id: tool-result-pruner
  name: /absolute/path/to/dsh-ctxopt-compaction/src/pruner.js
  config:
    thresholdChars: 8192
    headChars: 4096
    digestChars: 1536
    tailChars: 1024

核心功能¶

插件主要包含以下五个组件与能力：

1. 压缩收益判断：按实际待替换历史估算收益，排除未被替换的 system 消息；默认不足 512 估算 token 的片段跳过摘要调用。
2. 摘要质量与预算：摘要过短、超预算或节省不足时拒绝替换，保留原历史；默认不额外重试退化摘要。
3. 摘要缓存：按会话、输入、工具历史、路由及配置区分缓存，限制条数、字节数和有效期。
4. 可控记忆：通过明确指令保存、更新、删除键值事实与待办，将当前状态写入压缩 checkpoint。
5. 诊断保留：裁剪长工具输出时，在头尾之间保留预算允许的中段错误、文件、工单等诊断信息。

配置说明¶

插件通过配置文件控制收益判断、缓存大小、记忆条目和工具裁剪参数。宿主 patch 会替换目标条目的整个 config，不会递归合并。

引擎配置¶

以下为针对 32K 窗口的示例参数，其他数值为本插件默认值：

thresholdRatio: 0.4
headroomTokens: 512
retainTokens: 1400
maxTokens: 1536
compactionRetries: 1

budgets:
  minRegionTokens: 512
  minSavingsTokens: 96
  checkpointReserveTokens: 128
  maxCheckpointTokens: 2048
  maxExtrasTokens: 384

cache:
  enabled: true
  maxEntries: 16
  maxBytes: 262144
  ttlMs: 300000
  failureTtlMs: 30000

memoryBlock: true
reminders: true
memory:
  maxItems: 8
  maxTodos: 4
  maxItemChars: 160
  allowedKeys: []

anchorValidation: true
degenerateGate: true
degenerateRetries: 0
economics:
  enabled: false

关键参数说明¶

• thresholdRatio / headroomTokens：控制宿主触发压缩的位置和窗口余量，不是输入的硬截断上限。
• maxCheckpointTokens：用于计算摘要预算，需扣除 checkpointReserveTokens；最终 checkpoint 由宿主计量。
• cache.maxEntries / maxBytes：每个引擎实例的缓存条数和键/序列化载荷字节上限，不是进程 RSS。
• memory.allowedKeys：允许保存的键名白名单；空数组表示不限制键名。

工具输出裁剪配置¶

裁剪器的独立配置默认值如下：

thresholdChars: 8192
headChars: 2048
digestChars: 1536
tailChars: 2048
smartDiagnostic: true

headChars、digestChars、tailChars 分别控制头部、诊断摘要和尾部预算，按 Unicode code point 计数。设 tailChars: 0 可关闭智能裁剪路径的尾部保留。

记忆与待办控制¶

在用户消息中单独写入指令行，可控制记忆与待办状态。发送时不要放在代码块或引用内。

指令示例¶

MEMORY project=ATLAS
MEMORY schema=v3
TODO release=完成回归测试后发布
MEMORY schema=v4
FORGET project
DONE release
MEMORY RESET

指令规则¶

• 同一个键再次赋值表示更新。
• 删除、完成和清空的写法见上。
• 键名区分大小写，允许 1–64 个 ASCII 字母、数字、下划线、点或连字符。
• 条数超限时淘汰较早更新的条目；单条值超出 maxItemChars 时跳过整条。
• 待办只是摘要中的未完成状态，不是定时提醒，不跨会话共享。
• FORGET 和 MEMORY RESET 只清除插件管理的当前状态，不擦除原始聊天日志或模型摘要里的历史叙述。

注意事项¶

1. 信息保留：压缩仍由模型生成摘要，不能保证所有历史信息都被保留。
2. 依赖要求：需要宿主提供 package.json 中声明的 peer dependencies。
3. 运行方式：不能作为独立聊天服务运行。
4. 配置合并：宿主 patch 会替换目标条目的整个 config，不会递归合并。
5. 日志查看：源码路径加载不会自动生成已安装插件的管理卡片。可通过检查宿主日志中的 ctxopt decision、skip-small-region、summary-ready 等关键字判断是否生效。
6. 性能依赖：延迟与 token 收益依赖实际输入及模型服务，本 README 不承诺固定提升比例。