前言¶
用 DeepSeek Harness（dsh）跑编码智能体时，会话很快会堆满工具调用、文件内容和推理过程。上下文窗口一旦接近上限，默认后端 @deepseek-ai/dsh-compaction-basic 会再调一次模型，把旧历史摘要成一段话。摘要要等推理、要花 token，文件路径、命令和标识符还可能被改写成「差不多」的说法。
dsh 把压缩做成可替换的能力缝：服务定义在 @deepseek-ai/dsh-compaction（ctx.compaction），内置实现是 dsh-compaction-basic，人手动触发走 dsh-command-compact（/compact）。官方文档写明每个上下文只加载一个实现，所以换引擎不需要改 Harness 源码，换插件即可。
社区插件 dsh-compaction-instant 走另一条路：不调用模型，按 lllyasviel/VCC 的对话编译思路，把旧历史整理成一份只含原文的检查点，被裁掉的内容用 seq 指针指回只增不改的会话日志。本文按插件目录页、GitHub README / package.json，以及 DeepSeek Harness 官方压缩文档核对后整理。
这是什么¶
dsh-compaction-instant 是面向 DeepSeek Harness 的会话与消息插件，目录页标注由 KitDoesIt 维护，仓库为 KitDoesIt/dsh-compaction-instant，许可证 MIT。目录页一句话是：无 LLM 的无损压缩引擎，压缩上下文而不丢失信息。仓库 README 写得更精确：检查点里只有原文，省略处都带出处标记，完整内容仍在持久日志里，因此定位是近无损，不是把整段历史原样塞进上下文。
它要替换的是内置摘要引擎 @deepseek-ai/dsh-compaction-basic。压缩发生在毫秒级文本处理里，不发摘要请求、不占 KV 缓存。/compact 命令与后端无关，换引擎后仍然可用。
核对时（2026-08-18）目录页与 GitHub 均为 7 星；仓库 package.json 版本为 0.1.4，要求 Node.js >= 18。npm 上同名包 dsh-compaction-instant 当时最新公开版本是 0.1.3。目录页走 GitHub 源，README 里的别名安装走 npm 解析，两边版本可能不一致，安装前按实际解析结果确认。
DeepSeek Harness 的核心理念是「一切皆插件」。本文引用的插件目录 deepseek-harness-plugin.com 是独立社区站点，与 DeepSeek / 幻方没有官方从属关系，不要把它当成官方应用商店。
核心功能¶
1、不调模型的确定性编译¶
压缩是对阴影区间做一次确定性扫描：无网络、无模型、无摘要 prompt。同样的输入会得到同样的检查点。summarizationProvider / summarizationModel 为兼容官方配置而保留，不起作用。
仓库给的编译示例（用户请求、助手回复加工具调用、再跟下一问）如下：
[user]
please fix the bug
[assistant]
on it
* read "a.js" (seq 2 -> result 3)
[user]
next question
规则可以收成几条：
- 每个工具调用只占一行。白名单工具（
toolArgTools，含read/write/edit/glob/grep/bash/shell/web_search/skill/subagent等）显示关键参数，其余只显示名字，hideTools里的工具整行不出现。 - 工具结果不占条目，靠
-> result N指针，一次recall(type:"result")取回。 - 过长的用户 / 助手文本按预算截断，末尾写
...(truncated from seq N)。 - 默认不保留 reasoning；
includeReasoning: true才会写进检查点。 - 更早的检查点被空间压力裁掉时，会留下
[checkpoint N]（1 为最早），不会无声消失。
预算有两道限制：token 数，以及 预算 × 4 的字符上限，避免 base64 或压缩文件绕过截断。超预算时先删最旧的工具行，再删其余最旧条目，对话文本不会被工具调用挤掉；最新内容优先保留。
2、近无损：省略都带 seq，日志里还能取回¶
「近无损」不是检查点等于全文，而是：
- 检查点里只有原文，不做改写、不编造。
- 每处省略都指向持久日志里的
seq。 - 旧检查点原样拷贝，不再二次摘要。
同一包还带回读层，模型和人都能用：
| 入口 | 模块 | 作用 |
|---|---|---|
recall 工具 |
dsh-compaction-instant/tool |
按 seq / result / checkpoint 把原文写回当前工具结果 |
search 工具 |
同上 | 在整份持久日志里做关键词 / 正则搜索，含已被压缩的内容 |
/recall 命令 |
dsh-compaction-instant/command |
把匹配事件和 seq 指针追加成一条用户消息，下一轮模型能看见 |
recall 能取回文本、推理、完整工具参数和嵌套工具结果。默认 maxRecallTokens 为 16000，超限会截断并标注；搜索默认最多展示 50 条（maxSearchHits）。这两个插件是独立行，只读日志，可以挂在任意压缩后端旁边。每个检查点开头还有一段 RECALL 指南，告诉模型怎么用 recall / search。
3、契约兼容，可顶替内置引擎¶
仓库称它是 compaction-basic 的契约级替换：同一个 ctx.compaction 缝、相同的注入列表（llm、tokenMeter、sessions）、相同的事件和报错词表，并走同一个 ctx.tokenMeter 计费。压缩后若不能缩小表面上下文，检查点会被拒绝。可选的 toolResultPruner 也兼容：pruner 整理保留尾部，本引擎处理被阴影覆盖的旧区间。
部分默认值和 basic 不同，换引擎后行为会变：
| 项 | instant 默认 | basic 文档默认 |
|---|---|---|
thresholdRatio |
0.5（用到窗口一半就自动压） |
0.8 |
retainRatio |
0.05 |
0.16 |
auto |
true |
true |
| 摘要模型 | 接受配置但不路由 | 一次 ctx.llm.stream() 摘要 |
手动 /compact 会按 manualRetainRatio（默认 0.05）留下最近原文，正在聊的内容不会整段被收走。
从 0.1.4 起，装配了 settings 域的部署（标准 web / desktop profile）会在「设置 → 插件」出现 compaction-instant 卡片，可改 checkpointScale、checkpointCap、maxTokens、auto、debug、debugLogPath。改完写入 settings.yaml，并叠在 cordis 配置之上。卡片在客户端 bundle 里，装完后需要重启一次 dsh web。npm 若仍停在 0.1.3，则没有这一项。
4、仓库 README 给出的压缩率¶
下面数字来自仓库 README，测的是本项目自己的开发会话，编译时不丢条目，只做条目级截断和工具调用单行化。百分比相对原文 token。这不是第三方评测，工具密集会话会明显好看，纯文本会差一截。
| 负载 | 原文 tokens | 编译后 | 保留 |
|---|---|---|---|
| 工具密集会话全量（3181 节点） | 2,523,012 | 226,205 | 9.0% |
| 另一会话全量（864 节点） | 685,088 | 62,705 | 9.2% |
| 同一工具密集会话，最近 800 条 | 625,927 | 45,031 | 7.2% |
| 纯文本（去掉全部工具行） | 160,963 | 109,945 | 68.3% |
压缩主要来自：工具结果不占条目、工具调用压成一行（上限 128 tokens）、reasoning 默认整段省略。纯文本大约只剩 1.5 倍压缩，多半是去掉 JSON 包装和截断最长块。README 也写了权衡：叙述型长对话的信息密度可能不如 LLM 摘要，因为长句是截断而不是合并。
部署默认 checkpointCap 为 65536。同一份 252 万 token 的工具密集会话，在这个封顶下保留约 2.2%，会丢掉大量旧条目；要不丢条目，检查点大约要到 22.6 万 tokens。需要更完整的历史时，应调高 checkpointCap / checkpointScale，或依赖 recall，不要默认「压完还等于全文」。
安装与启用¶
目录页给出的安装命令如下，在 DeepSeek Harness 终端执行：
dsh plugin add github:KitDoesIt/dsh-compaction-instant
可复现安装请固定 commit 哈希：
dsh plugin add github:KitDoesIt/dsh-compaction-instant#<commit>
目录页同时写明：插件以当前 dsh 进程的权限运行，安装时可能执行代码。装前检查源码仓库和许可证。
只执行上面这一条，未必能让内置预设真正换引擎。仓库 README 说明：dsh 目前没有「选择压缩引擎」的开关，内置预设 standard / code / cordis 写死了包名 @deepseek-ai/dsh-compaction-basic。要用起来，按 README 三选一，都通过插件管理器安装（它会在 profile 目录里跑 pnpm）。示例里加了 --profile web，按自己的 profile 改。
方法 1：别名顶替内置引擎¶
内置预设会从 profile 的 node_modules 解析包名（优先级高于 Harness 自带安装）。把本包装到内置名字下面，standard / code / cordis 会自动加载，不用改预设文件：
dsh plugin --profile web add "@deepseek-ai/dsh-compaction-basic@npm:dsh-compaction-instant"
删掉这条别名依赖，就回到官方 basic。
别名安装不会被识别成 dsh.bundle（Harness 仍按自己目录里的官方包名解析，那个包没有 bundle 声明）。recall 工具和 /recall 需要自己写进 profile 的 cordis.patch.yml，新行放在 insert 列表里，文件热重载，不必重启。行名必须用别名包名：
- id: compaction-basic
disabled: true
- insert:
- id: compaction-instant
name: '@deepseek-ai/dsh-compaction-basic'
- id: tool-recall
name: '@deepseek-ai/dsh-compaction-basic/tool'
- id: command-recall
name: '@deepseek-ai/dsh-compaction-basic/command'
引擎行可选，主要给没有压缩配置的预设（如 minimal）做宿主兜底。
方法 2：直接安装，再复制一份预设¶
dsh plugin --profile web add dsh-compaction-instant
从 v0.1.1 起包内声明了 dsh.bundle，直接安装会自动成为 profile 层：禁用内置摘要行，插入本引擎和 recall 工具（见包内 cordis.patch.yml）。宿主不用手写 patch。
内置预设本身仍钉着 basic。用内置 cordis 预设（创作模式）开一个会话，让模型执行：
复制
standard预设，把它的压缩引擎行换成dsh-compaction-instant。
README 的流程是：agentPresets.copy 做本地副本，改压缩行的 name，用 standingKeyFor 校验挂载，需要的话再把 agent-presets 的 config.default 指到新预设。选择器里会多出一个预设，内置预设不动。
方法 3：直接安装，再手工改预设副本¶
同样先 dsh plugin --profile web add dsh-compaction-instant，然后复制内置预设，不要改 Harness 自带的预设文件：
mkdir -p "$DSH_HOME/.agent-presets/<id>"
cp <内置预设路径>/agent.cordis.yml "$DSH_HOME/.agent-presets/<id>/agent.cordis.yml"
在旁边写 preset.yml（name + description），再把副本里压缩组的引擎行改成 dsh-compaction-instant，隔离域保持不变：
- id: compaction
name: cordis:group
group: true
isolate:
compaction: true
toolResultPruner: true
config:
- id: compaction-instant
name: dsh-compaction-instant
- id: command-compact
name: '@deepseek-ai/dsh-command-compact'
toolResultPruner 必须和引擎在同一 isolate。真正的检验是 standingKeyFor 挂载成功，或直接用该预设开会话；列表里的 broken 只抓解析错误。
三种方法对照（摘自 README）：
| 方法 | 内置预设里的引擎 | 改预设文件 | 选择器多出预设 |
|---|---|---|---|
| 别名替换 | 自动（standard / code / cordis） | 否 | 否 |
| AI 复制副本 | 只有新预设 | 只改副本 | 是 |
| 手动预设 | 只有新预设 | 只改副本 | 是 |
每个上下文只能挂一个 ctx.compaction 实现；预设有独立隔离域，宿主实例和预设实例不会撞车。
典型用法¶
装好并让当前预设真正加载本引擎之后，用法和 basic 同一套入口。
1、自动压缩：默认 auto: true，在 agent/pre-step 看压力，在 agent/request-error 做溢出恢复。thresholdRatio 默认 0.5，比 basic 的 0.8 更早触发。
2、手动压缩：会话里执行 /compact。最近一段按 manualRetainRatio 原样保留。
3、回读：模型侧用 recall / search；人侧用 /recall <关键词或正则>。
4、看检查点：compaction/summary 事件带着编译后的条目本身，UI 可展开的检查点行显示的就是模型实际看到的内容。
常用配置（全部可选）。cordis 配置里不要写空数组想「关掉」白名单：schemastery 会给缺省数组键填 []，本引擎把空数组当成未设置并回退默认值。toolArgTools: [] 不会清空白名单。
thresholdRatio: 0.5
retainRatio: 0.05
auto: true
maxTokens: 8192
checkpointScale: 0.1
checkpointCap: 65536
textTokens: 512
userTextTokens: 1024
toolCallTokens: 128
includeReasoning: false
debug: true 会把每次编译的诊断写到 debugLogPath（默认 $DSH_HOME/compaction-debug.log）。
分词是字符规则，不是模型 tokenizer：连续英文字母算 1、连续数字算 1、中文每个字 1（你好，世界！ 为 6）。Harness 自带的 tokenMeter 仍用 字符数 / 4 + 块开销 做缩小检查和 /compact 用量报告，两套算法并存。
适用场景与注意事项¶
比较适合：
- 工具密集的编码会话，历史里大量
read/write/bash结果，摘要既贵又容易丢路径。 - 希望压缩确定、可复现，同一段历史每次编译结果一致。
- 需要在压缩后按
seq把原文找回来，而不是依赖模型「回忆摘要里写过什么」。
需要降低预期的情况：
- 以长叙述、讨论为主的历史，检查点是截断不是合并，密度可能不如 LLM 摘要。
- 默认
checkpointCap: 65536在超长工具会话上会丢掉大量旧条目；完整内容在日志里，模型当下看不见，除非recall。 - DeepSeek Harness 仍处于 developer preview，官方仓库写明会有破坏性变更；本插件对 peer 依赖钉在
@deepseek-ai/dsh-*的^0.1.0-rc.6，升级 Harness 后要重新验证能否挂载。
安装与安全：
- 插件在当前 dsh 进程权限下运行，等于信任这份源码。装前读仓库和 MIT 许可证，重要环境建议固定 commit，并先在一次性 profile 里试。
- 社区目录不是官方审计。目录页和 GitHub 都要打开核对，安装命令以目录页原文为准，启用步骤以仓库 README 为准。
- 每个上下文只能有一个压缩后端。别名安装和直接安装不要叠出两个
ctx.compaction。
小结¶
dsh-compaction-instant 把 dsh 的上下文压缩从「再调一次模型做摘要」，换成「确定性编译原文 + seq 回读」。工具密集会话上，仓库自己的日志显示压缩主要来自工具结果不占位和调用单行化；叙述型对话则要接受截断，并靠 recall / search 补回细节。
目录页：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-compaction-instant/
GitHub：https://github.com/KitDoesIt/dsh-compaction-instant
压缩能力缝说明：https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/compaction
