Skip to content

dsh-compaction-vcc

Verified

dsh-compaction-vcc · v0.7.4 · MIT

LLM-free deterministic context compaction for DeepSeek Harness. A drop-in replacement for @deepseek-ai/dsh-compaction-basic that moves original tokens instead of summarizing them; anything cut stays recoverable verbatim through (seq N) pointers and recall

Install

dsh plugin add dsh-compaction-vcc

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Creators

Readme

dsh-compaction-vcc

你的长对话会被模型"总结"一遍。那份总结是模型编出来的——而模型随后会把它当成事实继续推理。

本插件把这个环节里的模型彻底拿掉。压缩变成确定性的文本处理:一百万个 token 的历史,毫秒级编译完,一次模型都不调,一个字都不改写。 每处省略都带 (seq N) 指针指回持久会话日志,随时可以用 recall 逐字取回。

装上即可替换官方引擎 @deepseek-ai/dsh-compaction-basic——同一处接口、同一套事件、同一套报错词汇,内置预设不用改任何东西。底层沿用 lllyasviel/VCC 的"对话编译"思路。

本项目由 tingfeng-droid 维护。 基于 TsFreddie/dsh-compaction-instant(MIT)——"对话编译"这一设计出自原作者,在此致谢。 原项目上游已归档。本分支继续维护并跟进宿主当前 API;改动明细见文末「版本历史」。

一句话说清它解决什么

上下文装满时,内置引擎会让模型把历史"总结"一遍。而让模型总结,它就会把记不清的细节用听起来合理的措辞补上——补出来的这些是编的。更麻烦的是很难发现:总结读起来通顺,模型随后就把自己写的总结当成事实前提继续推理。一个被改写的数字、一处被省略的前提,就足以让整条后续推理建立在错误基础上。对话越长,总结要覆盖的内容越多,丢信息的机会也越多。

为什么"保留原文"能避免幻觉

这是本项目最重要的设计取舍,值得单独说清楚。

LLM 摘要式压缩会制造幻觉。 让模型总结历史,它会把"我记不清的细节"用合理的措辞补上——这些补出来的内容是模型编的,不是事实。更麻烦的是它很难被发现:摘要读起来通顺、看起来合理,模型随后会把自己的摘要当成事实依据继续推理。一个被改写的数字、一句被"洗"过的话、一处被省略的前置条件,都可能让后续整段推理建立在错误前提上。

保留原文从根上断掉了这条路径。 本引擎压缩时只搬运原文,一个字都不改写:

  • 每处省略都带 (seq N) 指针,指回持久日志里的原始事件;
  • 模型可以随时用 recall 把被压掉的完整原文逐字取回;
  • 所以模型看到的永远只有两种东西:原文,或明确标注"这里省略了,去 seq N 拿"的指针——不存在第三种。

换句话说,摘要式压缩 = 原文被模型改写;本引擎 = 原文被原样归档,只是排版变紧凑了。 前者会安静地产生编造,后者在结构上就没有编造的空间。

这对长会话尤其关键:上下文越长,摘要要覆盖的内容越多,改写和丢失的机会就越多;而指针式归档的成本是每处省略几个字节,与历史长度几乎无关。

主要特性

  • 免 LLM——压缩过程完全不调用模型:没有摘要请求、没有推理等待、不花 token。它只是确定性的文本处理。本机实测:100 万个 token 的历史 → 153 ms(中文)/ 84 ms(英文),3 次取最优,全程不调模型。
  • 近无损——存档里只有原文;每处被省略的内容都有标记并注明出处(seq 序号),之前的存档会原封不动地保留。
  • 即时——把旧内容扫描一遍就完成;不联网、不调模型、不占 KV 缓存。
  • 完全兼容的替换——对外接口、事件、计费和报错方式都和官方引擎一致;内置预设不用改任何东西就能用(见"别名安装")。

示例

一段包含用户提问、助手回答 + 工具调用及其结果的历史,压缩后长这样:

[user]
please fix the bug
[assistant]
on it
* read "a.js" (seq 2 -> result 3)
[user]
next question

每个工具调用只占一行:白名单里的工具(toolArgTools)显示关键参数,其他工具只显示名字(* job_kill (seq 9 -> result 10)),hideTools 里列的工具完全不出现。工具结果不占位置——通过 -> result N 指针,用一次 recall(type:"result") 就能取回。较长的用户/助手文本按预算截断,并在末尾标注 ...(truncated from seq N);每处省略都写明了完整内容存在哪个事件里。

Recall:把丢掉的内容找回来

本包还配套了"找回"能力——同一会话内的回读,模型和人都能用。因为会话日志只增不改,编译器省略过的每一个字都还在,随时可取:

入口 模块 作用
recall 工具(给模型用) dsh-compaction-vcc/tool 按类型恢复原文:type:"seq" 配合 (seq N)/(seqs A-B) 标记,type:"result" 配合 result N 指针,type:"checkpoint" 配合 [checkpoint N] 序号——把原始内容一字不差地恢复到当前工具结果里
search 工具(给模型用,grep) dsh-compaction-vcc/tool 在整个持久日志里按关键词/正则搜索——包括被压缩掉的内容——返回带 (seq N) 指针的匹配事件,可直接交给 recall 取回
/recall 命令(给人用,grep) dsh-compaction-vcc/command `/recall <关键词
共享核心 dsh-compaction-vcc/recall + dsh-compaction-vcc/search seq 解析(12、3-7、seq 12 / seqs 3-7)、日志展开、预算、字段筛选;正则编译与命中展示

Recall 能取回一切:文本、推理过程、工具调用的完整参数、嵌套的工具结果;只在日志里出现过的事件会以带标签的原始数据展示;找不到的 seq 会明确报错。maxRecallTokens 预算(默认 16000)超限时会截断并标注来源、统计跳过多少;搜索限制展示条数(maxSearchHits,默认 50)。这两个插件是独立的一行,可以挂在任何压缩引擎旁边——它们只读日志,不依赖本引擎。

每个检查点开头还附了一段简短的 RECALL 使用指南,告诉模型怎么用 recall / search 找回被省略的内容。如果更早的检查点因为空间不够被省略,它不会无声消失:会留下一行 [checkpoint N](N 是压缩序号,1 = 最早),用 recall(type:"checkpoint", id:"N") 就能完整恢复。

和 dsh-tingfeng 配合:让规则和记忆也保持原文

把对话保成原文只做到了一半。长会话里还有两类文字会被摘要式压缩一起改写,而它们在上下文里的重要性高于一切:

  • 规则(工作区指令、工具契约);
  • 每轮注入的记忆(稳定事实、偏好、项目知识)。

LLM 摘要器会把这两类也压掉。而规则恰恰是「改一个字就等于改行为」的那种文本:「结论与证据冲突时改结论」被概括成「注意结论」,就成了另一条指令——而模型没法察觉自己被改写过。

dsh-tingfeng(与本引擎配套开发的记忆插件)补上了这一半:

  • 压缩之后逐字重发规则和记忆,注入块永远是原文,不会变成压缩过的转述;
  • 给注入块打上自己的 source.kind,本引擎据此能把「注入块」和「真实对话」区分开。

两个能力靠一个开关连起来:elideCheckpointInjectedBodies: true 让本引擎把旧检查点里那份过期的记忆/规则副本换成一行指针——因为记忆插件反正会重新注入一份新的。这个开关之所以安全,前提就是上面的标记:引擎能定位块边界,而不是靠猜。

compaction-vcc        对话保原文,省略的留指针可 recall
      +
dsh-tingfeng          每次压缩后逐字重发规则和记忆
      +
elideCheckpointInjectedBodies: true
      ↓
整条链路里没有摘要器 —— 上下文里没有任何文字被改写过

效果:压缩很多次之后,模型仍然能逐字引用你的规则、仍然分得清「你自己测的数」和「它自己推的数」、仍然记得哪些结论被推翻过。换成摘要式压缩,这三件事会一起塌成一段读起来很像事实的流畅文字。

关于 elideCheckpointInjectedBodies:默认关闭。0.7.3 修的正是这条路径上的数据丢失缺陷(块被截断丢了闭标签,范围一路吃到真实对话——一次抹掉 56,485 字符,其中约 4,000 是真对话)。已修复并有防回归测试,但这是唯一会走块边界的开关,开启前请固定在你实测过的版本。不装 dsh-tingfeng 就保持关闭。

配置

所有配置项都可选,括号里是默认值。

键 默认 含义
thresholdRatio 0.5 上下文用到多大比例时自动触发压缩(0.5 = 用到一半)
retainTurns 1 优先保留的完整回合数(自动压缩和手动 /compact 都按此规则;不突破上限)
retainTokens 20480 保留区 token 硬上限:向前补足完整回合时总量永不超出;若最近回合本身就超过它,只保留该回合内能装下的部分
auto true 开启自动压缩:监听 agent/pre-step 压力事件和 agent/request-error 溢出恢复
checkpointCap 393216 单个检查点的编译预算(估算 token):更小的会话近乎无损地保留,更大的内容则省略到该上限
maxTokens / checkpointScale 8192 / 0.1 已弃用——仅为兼容旧配置而接受,不再起作用:预算就是 cap 本身(无保底、无比例缩放)
textTokens 8192 每条助手文本的预算
userTextTokens 16384 每条用户文本的预算
toolCallTokens 128 每个工具调用单行的预算(这个永远不缩放——见下面的省略规则)
toolResultExcerptTokens 256 仅为兼容官方配置而接受;不起作用——工具结果本来就不占位置
includeReasoning false 是否在检查点里保留推理过程
stripNoiseXml true 是否去掉用户文本里配置的噪音标签
noisePatterns 见 compiler 噪音标签的正则来源,按 s 模式匹配
toolKeyFields 内置 额外的"工具名 → 参数里的关键字段"映射,用于单行展示
toolArgTools 见 compiler 白名单:这些工具的关键参数会显示在单行里(read/write/edit/glob/grep/bash/shell/web_search/skill/subagent/…);其余工具只显示名字
hideTools — 完全从检查点里去掉的内部管理工具
modelPolicies — 按 provider/model 单独覆盖 thresholdRatio/retainTurns/retainTokens
compactionRetries / maxOverflowRetries 1 / 1 重试次数,含义和官方引擎一样
summarizationProvider / summarizationModel — 仅为兼容官方配置而接受;不起作用——本引擎从不调用模型

recall 工具和命令插件各自接受 { maxRecallTokens?: 16000, maxSearchHits?: 50 } 配置。

Cordis 配置坑: 插件行的配置要经过 schemastery schema 校验,它的 ~standard 适配器会给每个没写的数组项注入 [](toolArgTools、hideTools、noisePatterns、toolKeyFields、modelPolicies)。本引擎把空数组当作"没设置",会回退到默认值——所以不写 toolArgTools 就自动用内置白名单(千万别用 toolArgTools: [] 想关掉它;空 = 默认)。debug: true 会把每次压缩的诊断写进 debugLogPath 指定的文件(默认 $DSH_HOME/compaction-debug.log)。

预算有两道保险:按 token 数限制,再按"预算 × 4"的字符数限制——所以再长的连续字符串(base64 大块、压缩过的文件)也绕不过去。工具调用永远是单行:不会缩放,预算不够时只压缩对话文本(每条最少留 32 token)。如果压缩结果还是超过预算,先删最旧的工具行([N tool/result entries elided: seqs a-b]),再删其余最旧的条目([N earlier entries elided: seqs a-b])——工具调用永远挤不掉对话。最新的内容总能保住。

设置命名空间(无界面)

引擎在任何装配了 settings 域的部署(标准 web/desktop profile 都有)上暴露一个用户设置命名空间(compaction-vcc)。可编辑子集持久化到 settings.yaml,叠加在插件行的 cordis 配置之上:

字段 含义
checkpointCap 单个检查点的编译预算(默认 393216)
auto 注册步骤间自动压缩
thresholdRatio 触发自动压缩的上下文窗口占比(默认 0.5)
retainTurns 优先保留的完整回合数(默认 1;不突破上限)
retainTokens 保留区 token 硬上限,补足回合或截取最近回合时永不超出(默认 20480)

其余字段(modelPolicies、toolArgTools、debug、debugLogPath、已弃用的 maxTokens/checkpointScale 等)仍只由 cordis 配置管理。设置层永远弄不坏引擎:每次设置写入都会先经过完整配置解析器的重新校验才会持久化;未暴露的配置字段保持组合层的值。没有 settings 服务时引擎行为与之前完全一致(只看组合配置)。

⚠️ 没有图形设置卡片。 0.2.0 起 dsh.client 声明已被整个删掉(原因见下方版本表)。上面的命名空间仍然存在、仍可通过 settings API 读写,但不会被渲染成界面控件——改这些值请直接编辑 cordis.patch.yml 的 compaction-vcc.config。

分词与多语言

分词器是简单的字符规则:连续的英文字母算一个 token,连续数字算一个,标点一个字符一个,空格免费,其他每个字符算一个。具体:

内容 Tokens
中文(你好,世界!) 每个字 1(共 6)
西里尔 / 阿拉伯文 每个字符 1
带重音拉丁文(café) 英文部分成组(caf + é)
Emoji(😀) 2(一个 emoji 占两个 UTF-16 单元)

所有截断都发生在字符边界——绝不会把一个 emoji 从中间切开(有 test/multilang.test.js 保证)。字符密度上限按 DeepSeek 官方换算(token_usage 文档):约每个非中日韩字符 0.3 token、每个中日韩字符 0.6 token。

另外,Harness 自带的 token 计量器(用于"压缩后必须变小"的检查、/compact 的用量报告)用的是另一套 字符数 / 4 + 固定开销 的估算,两套算法故意并存——详见设计说明。

保证

  • 即时——把旧内容扫描一遍就完成;不联网、不调模型、不占 KV 缓存。
  • 近无损——输出里只有原文;每处省略都有标记并注明出处 seq;之前的检查点原封不动保留。
  • 完全兼容的替换——接口、事件、计费(走同一个 ctx.tokenMeter)和报错方式与官方引擎一致,包括"压缩后必须变小"的检查(如果压缩完反而没变小,会被拒绝)。
  • 可选 pruner 兼容——和官方引擎一样会使用可选的 toolResultPruner 服务(它负责整理保留部分;被压缩的旧内容由本引擎自己处理)。

实测压缩率(真实会话、一条不丢)

数据来自真实会话日志(本项目的开发会话),编译时不丢弃任何一条——每条都保留,只做条目级截断和工具调用单行化。百分比是相对原文 token 数的比例。

负载 原文 tokens 编译后 保留 压缩
工具密集会话全量(3,181 节点:1,438 个工具调用 + 1,540 个工具结果) 2,523,012 226,205 9.0% 91.0%
另一个会话全量(864 节点) 685,088 62,705 9.2% 90.8%
同一个工具密集会话,最近 800 条消息 625,927 45,031 7.2% 92.8%
纯文本(同一会话去掉全部工具行) 160,963 109,945 68.3% 31.7%

压缩主要来自哪里(不丢条目的情况下):

  • 工具结果零成本——结果不产生条目,靠 -> result N 指针一个 recall 就能取回,这是最大的来源。
  • 工具调用一行化——每个调用压成一行(≤ 128 tokens,平均约 100)。
  • 思考过程不保留——reasoning 增量整体省略(有标记,不是悄悄丢)。
  • 对话文本近乎无损——纯文本对照组保留了 68.3%;文本上那约 1.5 倍压缩基本是剥掉 JSON 包装,外加只截断最长的几段。

预算扫描(同一个 252 万 tokens 的工具密集会话):默认 64K 上限下,编译视图约 5.6 万 tokens(原文的 2.2%)。只有把上限压到约 22.6 万 tokens 的"完全不丢"阈值以下才开始丢条目——代价是悬崖不是斜坡:

Cap 编译后 保留 条目数 被丢
8,192 8,243 0.33% 111 2,090
32,768 22,263 0.88% 232 1,969
65,536(部署默认) 55,737 2.2% 325 1,876
65,536 55,737 2.2% 325 1,876
131,072 131,047 5.2% 1,142 1,058
226,205(一条不丢的临界值) 226,205 9.0% 2,199 0

安装

下面三种方法都用 Harness 自带的插件管理器安装(包发布在 npm,名字 dsh-compaction-vcc;插件管理器会在 profile 目录里跑 pnpm,装完后宿主配置和每个 agent preset 都能找到它):

dsh plugin --profile web add <spec>

/compact 命令(dsh-command-compact)和用哪个引擎无关,任何安装方式下都照常工作。

⚠️ 先读这一段:装不对会「静默失效」

如果你的宿主挂载了 agent preset(standard / ptc / minimal / cordis 任何一个), 直接 dsh plugin add dsh-compaction-vcc 是不够的。

原因:每个 preset 用 isolate 挂在自己独立的 realm 里,preset 内那条 compaction-basic 会在它自己的 realm 内实例化一个引擎。本包插在宿主层的那一行 进不去 preset 的 realm(上游 leakedServices 强制要求压缩服务待在 isolate realm 里,从外部注入会直接报错)。

结果就是静默失效:

状态
recall / search 工具 ✅ 能用(工具注册是全局的)
/recall 命令 ✅ 能用
实际压缩 ❌ 还是官方 basic 在跑(调模型、出摘要)

判断依据只有一个——看 compaction/summary 事件的 provider 字段:

zstd -dc <session>.jsonl.zstd | python3 -c "
import json,sys
for line in sys.stdin:
    line=line.strip()
    if not line: continue
    o=json.loads(line)
    if o.get('type')=='compaction/summary':
        d=o['data']
        print(o['seq'], d.get('provider'), d.get('model'), 'llm=',d.get('llmStreamCall'))
"
  • provider = dsh-compaction-vcc / model = vcc-compiler → ✅ 正常
  • provider 是聊天模型(如 zlwb-pool-vision)、llmStreamCall: true → ❌ 还走的是 basic

0.3.0 起本引擎会自己在启动后做这项检查,发现 preset 没接管就在日志里打一条 明确的 warn,不再让你靠猜。开关是 warnOnPresetTakeover(默认 true)。

挂载了 preset 时,请用方法 1(推荐),或方法 2 / 3(要改动预设)。 没有挂载 preset 的宿主,直接装即可。

怎么知道自己有没有挂 preset?看 profile 的 dsh.profile.bundles 里有没有 @deepseek-ai/dsh-web-app(它插入了 agent-preset-registry,config.default: standard), 或运行 dsh --profile <name> --dump-config | grep -c "preset-"。

⚠️ 第二种静默失效:两份副本,一份新一份旧

只在你「换过安装方式」或「同一台机器试过多种装法」时会遇到,但它比上一条更难查。

两种装法用的是两个不同的包名:

装法 包名(node_modules/ 下的目录)
bundle 装法(dsh plugin add dsh-compaction-vcc) dsh-compaction-vcc
别名装法(add "@deepseek-ai/dsh-compaction-basic@npm:dsh-compaction-vcc") @deepseek-ai/dsh-compaction-basic

关键:这两个名字都可能真的在被使用,但它们不是一回事。

  • 别名(@deepseek-ai/dsh-compaction-basic)——宿主内置的每个预设 (preset-standard 等)都在自己的 isolate realm 里声明一行 { id: compaction-basic, name: "@deepseek-ai/dsh-compaction-basic" }。 预设只认这个名字。 别名装法就是用我们这份顶替官方那份。
  • 真名(dsh-compaction-vcc)——只是宿主层的 - id: compaction-vcc 条目在用它, 另外 recall / search 工具也从这里来。

⇒ 别名不是可有可无的残留。删掉别名 = 所有预设都退回官方 LLM 摘要。 而 recall / search 工具照样能用,所以看起来一切正常。

升级只覆盖你当前用的那个名字,于是出现一旧一新:

node_modules/dsh-compaction-vcc/                 ← 每次升级都更新
node_modules/@deepseek-ai/dsh-compaction-basic/  ← 停在第一次装进去的版本

2026-11-07 实证(一):两份副本,版本不同。 机器上 dsh-compaction-vcc/ 已是 0.7.0,@deepseek-ai/dsh-compaction-basic/ 还停在同一晚 19:59 装的 0.4.0。宿主加载的是 0.4.0,压缩产出与 0.4.0 离线编译逐字吻合 (129 条目),而 0.7.0 应产出 185 条目。排查时静态检查全绿(版本号、入口、 role === "tool" 分支都在),只有实际产出对不上。

2026-11-07 实证(二):矫枉过正,把别名删了。 同一台机器上「按实证(一)的办法删掉别名」之后,下一次压缩的 compaction/summary 事件里 provider 从 dsh-compaction-vcc 变成了 一个聊天模型(zlwb-pool-vision / deepseek-v4.1-flash),正文从 8 万字符的原文搬运缩成 5 千字符的 LLM 摘要——8.3 万 token 的对话被概括成一段话。 这就是上面那条:别名没了,预设回落到官方摘要引擎。

⇒ 正确做法不是删别名,而是让两份都更新到同一版本。

怎么查

第 1 步:看有多少份、各是什么版本。

find ~/.dsh/profiles/<profile>/node_modules -maxdepth 3 \
  -path "*compaction*" -name package.json 2>/dev/null \
  | while read f; do
      python3 -c "import json;d=json.load(open('$f'));print('$(dirname $f)', '→', d['name'], d['version'])"
    done

两行、版本相同 = 健康。两行、版本不同 = 有一份旧(不是删掉,是更新)。 只有一行 = 看你有没有挂预设(见下一节)。

第 2 步:看预设到底解析到谁。

cd ~/.dsh/profiles/<profile> && node -e '
const {createRequire}=require("module");
const r=createRequire("file://" + process.cwd() + "/");
try{
  const m=r("@deepseek-ai/dsh-compaction-basic/package.json");
  console.log("别名解析到:", m.name, m.version);
  console.log(m.name==="dsh-compaction-vcc" ? "✅ 预设会用本引擎" : "❌ 预设会用官方摘要引擎");
}catch(e){ console.log("❌ 别名解析不到 —— 所有预设都会退回官方摘要引擎"); }
'

第 3 步(最硬的判据):看下一次压缩的 provider。

zstd -dc ~/.dsh/sessions/<工作区>/session-<id>/session.v4.jsonl.zstd 2>/dev/null \
  | python3 -c '
import sys,json
for line in sys.stdin:
    try: o=json.loads(line)
    except: continue
    if o.get("type")=="compaction/summary":
        d=o["data"]
        kind="LLM摘要(NG)" if "llmStreamCall" in d else "VCC确定性编译(OK)"
        print(o["seq"], d["provider"], "|", kind)
'

provider 必须是 dsh-compaction-vcc。出现任何聊天模型名 = 跑的是官方摘要引擎。

怎么修

两份都更新到同一版本。别删别名。

TGZ=~/dsh-compaction-vcc/dsh-compaction-vcc-X.Y.Z.tgz
for D in dsh-compaction-vcc @deepseek-ai/dsh-compaction-basic; do
  T=~/.dsh/profiles/web/node_modules/$D
  mkdir -p "$T" && tar xzf "$TGZ" -C "$T" --strip-components=1
done

package.json 里两条 file: 依赖都指向同一个 tgz 即可:

"dsh-compaction-vcc": "file:.../dsh-compaction-vcc-X.Y.Z.tgz",
"@deepseek-ai/dsh-compaction-basic": "file:.../dsh-compaction-vcc-X.Y.Z.tgz"

别名那条不要写进 dsh.profile.bundles——它只是个顶替用的名字, 进去会让宿主把它当独立 bundle 再挂一次。

0.7.2 起本引擎会在启动时自检,发现同一台机器上还有另一份同名包时打印 warn;自检按包清单里的 name 字段判断,不按目录名——目录名和包名不一致 正是别名装法的常态。(0.7.1 的自检按路径字符串判断,会把健康的别名装法误报成 「没接管」,0.7.2 已修。)

一句话记忆:升级这个包之后如果「没变化」,先数 node_modules 里有几份、 各是什么版本,并且看下一次压缩的 provider。版本号对但行为是旧的, 多半是加载了另一份;provider 变成聊天模型,则是别名没了、预设退回了官方摘要。

方法 1 —— 顶替内置引擎(别名安装)

dsh plugin --profile web add "@deepseek-ai/dsh-compaction-basic@npm:dsh-compaction-vcc"

dsh 目前没法让你选压缩引擎,内置预设(standard、code、cordis)在配置里写死了包名 @deepseek-ai/dsh-compaction-basic。要让这些内置预设用上本引擎,就顶替内置插件:预设配置里的包名是从 profile 的 node_modules 解析的(优先级高于 Harness 自带的安装),所以把本包装到内置这个名字下面,所有内置预设就会自动加载本引擎——不动任何预设文件,预设以后升级也不受影响。

这样顶替是天然安全的:本引擎和官方引擎对外完全兼容——同一个 ctx.compaction 接口、完全相同的依赖注入列表(llm、tokenMeter、sessions)、相同的事件和报错方式,官方配置里的每一个键也都接受。把别名依赖删掉就恢复官方的引擎。

这种安装方式不会被识别成 bundle(Harness 会从自己的安装目录解析 @deepseek-ai/dsh-compaction-basic 这个名字,那里是官方包,没有 dsh.bundle 声明),所以没有任何自动化——需要把 recall 工具和 /recall 命令自己加进 profile 的 cordis.patch.yml(新行必须放在 insert 列表里;这个文件热重载,不用重启)。行名必须用别名包名(这种安装方式下只有它能解析);引擎行可选,只在需要给"没有压缩配置的预设"(如 minimal)提供宿主兜底时才加:

- 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'

方法 2 —— 直接安装 + 让 AI 复制一份预设(dsh 创作模式)

dsh plugin --profile web add dsh-compaction-vcc

然后用"预设创作"预设(内置的 cordis 预设,即「创造模式」)开一个会话,让 AI 执行:

复制 standard 预设,把它的压缩引擎行换成 dsh-compaction-vcc。

AI 会用 agentPresets.copy('standard', '<id>') 创建一份本地预设,在副本里改掉压缩行的 name,用 standingKeyFor('<id>') 校验能不能正常挂载,还可以通过改 agent-presets 行(config.default: <id>)把它设为默认。新预设会出现在 UI 选择器里;内置预设不受影响。

本包声明了 dsh.bundle,所以直接安装会自动注册成 profile 的配置层:自动禁掉内置的摘要引擎行、自动插入本引擎和 recall 工具(见包内 cordis.patch.yml)。宿主这边不用手动配置,只需复制预设。

方法 3 —— 直接安装 + 手动配置预设

dsh plugin --profile web add dsh-compaction-vcc
mkdir -p "$DSH_HOME/.agent-presets/<id>"
# 从你想作为基础的内置预设复制配置和元数据
# (预设列表里能看到每个预设的真实路径):
cp <built-in-preset>/agent.cordis.yml "$DSH_HOME/.agent-presets/<id>/agent.cordis.yml"
# 在旁边写 preset.yml,包含 name + description

然后手工编辑副本里的压缩组——只改一行 name,仍在同一个隔离域(realm)里:

- id: compaction
  name: cordis:group
  group: true
  isolate:
    compaction: true
    toolResultPruner: true      # pruner 必须和引擎在同一隔离域
  config:
    - id: compaction-instant
      name: dsh-compaction-vcc   # 原来是 '@deepseek-ai/dsh-compaction-basic'
    - id: command-compact
      name: '@deepseek-ai/dsh-command-compact'
    # ... 保留 pruner 行

规则:绝不改内置预设的安装文件;保留 isolate 隔离域;真正的检验是 standingKeyFor 挂载成功(或直接在预设上开一个会话)——预设列表里的 broken 标记只能发现解析错误。

方法 2 和 3 不需要任何宿主配置行:上面提到的 dsh.bundle 会自动注册好一切。

方法 内置预设里的引擎 要改预设文件吗 选择器里多出预设 安装成本
1. 别名替换 ✅ 自动(standard/code/cordis) 否 否 一条命令 + 手动 patch
2. AI 复制副本 只有新预设 副本 是 一句提示
3. 手动预设 只有新预设 副本 是 手动编辑

每个上下文只能挂载一个 ctx.compaction 实现(接口文档写明"每个上下文加载一个实现");预设挂载各自有独立的隔离域,所以宿主和预设的实例永远不会冲突。

开发

npm test        # node --test(编译器单元测试、配置校验、会话集成、引擎)
npm run check   # 对所有源码做 node --check

本包依赖很少:@deepseek-ai/schemastery 用于配置校验;其余依赖都是 Harness 自己提供的。src/compiler.js 刻意零依赖,没有运行中的 Harness 也能单独跑单元测试。

和官方引擎的区别

  • 不调摘要模型 → 压缩从几秒变成几毫秒;不花摘要的 token。
  • 不改写 → 事实、文件路径、命令、变量名都一字不差;模型继续用自己的话接着聊。
  • 确定性 → 同样的内容永远压缩出同样的检查点。
  • 之前的检查点原样保留,而不是重新摘要一遍(又快又无损)。
  • 手动 /compact 和自动压力压缩都会保留最近的一段原文(优先整回合,retainTokens 为硬上限:补足整回合时总量永不超出;若最近回合本身就超过上限,只保留该回合内能装下的部分)而不是压缩全部历史,正在聊的内容永远不会被收走;只有更早的部分进检查点。
  • compaction/summary 事件携带压缩后的条目本身——UI 里可展开的检查点行显示的就是模型实际看到的内容,外面包一层能自动变长的代码框(框线永远比内容里的 ``` 长,所以含 markdown 的消息也能整齐地显示成一个代码块),检查点开头还有一段简短的使用指南,告诉模型怎么用 recall / search 找回被省略的内容。
  • 权衡:对以长对话、叙述为主的历史,检查点的信息密度可能不如 LLM 摘要(长句是截断而不是合并)。正在进行的对话有逐字保留的尾部(retainTurns/retainTokens)兜底,其余内容都能通过 (seq N) 指针 + recall 找回来。

MIT 许可证。

版本历史

版本 状态 说明
0.7.4 ✅ 当前 仅文档与元数据。README 首屏改成先讲痛点、维护者声明下沉;package.json 描述改为说明它做什么,不再自称兼容补丁;keywords 补 dsh-plugin / recall;没有口径的「毫秒级」换成实测数字(100 万 token → 153 ms 中文 / 84 ms 英文,3 次取最优)。无代码改动。
0.7.3 — 修「块边界被撑大,把真实对话一起抹掉」。 elideCheckpointInjectedBodies 找记忆块范围时,只用「闭标签 + joiner」往后推进。一旦某个 <runtime-memory-file> 块被截断(...(truncated from seq N))而丢了闭标签,它就会一路吃到下一个块的闭标签,把夹在中间的真实对话当成注入体抹成指针。办公机实测:一次压缩抹掉 56,485 字符,其中约 4,000 是真实对话(占 7%)。修法是在吃块前先查块内有没有行首角色头([user] / [assistant] / [tool])——那是本编译器自己的输出格式,记忆块内部不会出现;一旦出现就说明已走出该块,就地截断。方向保守:宁可少抹,也不能把原话抹掉。新增 1 条防回归测试(回退修复会失败)。测试 163→164。
0.7.2 ✅ 可用 纠 0.7.1 的错误结论 + 修自检误报。 ① 0.7.1 的 README 说「两份副本并存就删掉别名」,这个结论是错的:别名不是残留,宿主每个预设都声明 { id: compaction-basic, name: "@deepseek-ai/dsh-compaction-basic" },预设只认这个名字。删掉别名后,实测 compaction/summary 的 provider 从 dsh-compaction-vcc 变成一个聊天模型(llmStreamCall 字段出现),8.3 万 token 的对话被摘要成 5 千字符。正确做法是两份都更新到同一版本,别删别名。README 整节重写。 ② preset-check 的 isEnginePath() 按路径字符串找 dsh-compaction-vcc,而别名装法把包放在 @deepseek-ai/dsh-compaction-basic/ 下,目录名里根本没这串 ⇒ 所有健康的别名装法都被误报成「没接管」。改为读包清单的 name 字段判断。 ③ 原测试 assert.equal(isVccRow(row, baseUrl), false, "basic does not resolve to vcc") 把 bug 写成了预期结果——测试环境没有别名目录,旧的路径判据压根没被执行。改为真造一个别名布局再断言,另补一条「官方真的会走到摘要引擎」的反向用例。测试 162→163。
0.7.1 ⚠️ 已被 0.7.2 取代 修「两份副本并存导致升级静默不生效」。 同一台机器上先用过别名装法、后来改用 bundle 装法时,node_modules/ 下会留下两份同名包(dsh-compaction-vcc 与 @deepseek-ai/dsh-compaction-basic),升级只覆盖其中一份,宿主可能加载旧的,表现为「版本号是新的、行为是旧的」,无任何报错。实证:0.7.0 与 0.4.0 并存,加载的是 0.4.0。新增 src/shadow-check.js 启动自检,发现另一份同名包且版本不同就 warn(同版本重复不报)。README 增「第二种静默失效」一节。⚠️ 两处错:清理步骤写「删掉别名」,而别名是预设唯一认得的名字,删了会让压缩整体退回 LLM 摘要;preset-check 自检按路径字符串判断,把健康的别名装法误报成「没接管」。请用 0.7.2。 测试 157→162。
0.7.0 ✅ 可用 审计后清理。 删掉 0.2.0 起就已失灵的 src/client.js(621 行 / 28.4 kB 死代码,dsh.client 声明既已删除,这个浏览器端就再无入口),包体 83.5 → 79.0 kB。README 里「浏览器设置卡片」那段与 0.2.0「前端已删」自相矛盾,已改为「设置命名空间(无界面)」。版本表补回 0.4.0–0.6.1 的缺档。另:package.json 的 exports["./client"] 与 check 脚本同步摘除。
0.6.1 ✅ 可用 两处修复,都会让宿主静默失效或冻结。 ① isCheckpointSource 认错了宿主的 source 形状:宿主 0.2.x 发的是 {kind:"compact-checkpoint"},代码判的是宿主旧版的 {kind:"plugin", plugin:"compact"},条件永远不成立 ⇒ 检查点处理分支从未进入,连带 recall(type:"checkpoint") 一直取不到检查点(修复前认得 0 个,修复后 5 个)。② parseSeqSpec 缺 Number.isSafeInteger 上界校验:recall(type:"seq", id:"9007199254740992") 会在 expandSelections 的 seq += 1 循环里同步死循环(2^53 上 +1 不改变数值),工具永不返回、定时器不触发、宿主必须重启。parser 与 expander 两层都已加防护,顺带拒绝 seq 0。另修三处「单个畸形节点炸掉整次编译」:content 为 null、数组含 null 块、content 非数组,原本都抛 TypeError 而整次压缩作废(宿主把错误吞成 warning,症状是「压缩就是不发生」)。测试 137→149。
0.6.0 ✅ 可用 检查点内注入正文清理(elideCheckpointInjectedBodies,默认关)。旧检查点里带着它编译时那份记忆快照与规则块,而每次压缩都会重新注入一遍 —— 那份副本就是纯重复。开启后把它换成一行指针,原文仍在 append-only 日志里可 recall。实测 90,877 → 46,290 字符(−44,737)。另加 elideSourceKinds(按 source.kind 丢弃注入型行)。
0.5.0 ✅ 可用 补齐 0.2.2 兼容面:tool-result 的 toolCallId 从 content[0] 移到 message 层后,-> result N 指针的映射预扫描一直没命中(静默丢失全部 result 指针,recall(type:"result") 因此失效)。同时整理 session-compat,两种 session 形状统一走一对访问器。
0.4.0 ✅ 可用 默认值改为「尽量保留原文」:userTextTokens 1024→16384、textTokens 512→8192、checkpointCap 65536→393216、retainTokens 5120→20480。实测(3524 节点 / 269 万 token 真实会话):50 万 shadowed 区间下对话正文保留率 22.0% → 98.4%,80 万区间 98.6%。关键:默认值改动同时修好了 preset 隔离场景——preset 的 compaction-basic 行本身不写 config,因此直接吃到新默认值,不必再改 preset。单条预算按实测最长条目(用户 4745 / 助手 4043 token)留 3.4x / 2x 余量,不再触发单条截断。checkpointCap 建议不超过模型上下文窗口的 40%(393216 ≈ 1M 窗口的 39%)。
0.3.0 ✅ 可用 修「预设场景静默失效」:宿主挂了 agent preset 时,preset 在自己的 isolate realm 里另有引擎实例,本包插在宿主层的那行进不去,压缩静默回落到官方 basic(工具却照常可用)。本版启动后自检 preset 接管情况并打 warn,开关 warnOnPresetTakeover。补 19 条 preset 场景测试。引擎行为未变,只是不再静默。
0.2.1 ⚠️ 已弃用 首次尝试加自检,但读错了字段名:compositionInventory() 返回的是 {entryId, moduleName, enabled},我按 {id, name, disabled} 读,结果永远判定「健康」——比不检查更糟,因为它假装检查过。另有四处上下文缺字段时抛 TypeError 的路径。请用 0.3.0。
0.2.0 ✅ 可用 把 dsh.client 声明整个删掉。 那张可选设置卡片会让宿主建一条永远激活不了的前端行,而激活失败会中止整个 web boot。这个引擎本来就不需要前端,所以前端没了。
0.1.9 ⚠️ 已弃用 想靠修正 dsh.client.inject 解决激活失败。import 通了,行还是没激活。bundle 装法起不来。
0.1.8 ⚠️ 已弃用 去掉了对宿主里不存在的包的 require。仍然是坏的。
0.1.7 ⚠️ 已弃用 第一个清单正确的版本,但 client.js 里 require 了宿主根本不带的 @deepseek-ai/dsh-client-runtime。bundle 装法起不来。
0.1.6 ⚠️ 已弃用 真实发布过,但清单是旧的:没有 engines.dsh、peer 写 ^0.1.0-rc.6,宿主会静默跳过。
0.1.5 ⚠️ 已弃用 清单问题同 0.1.6。
0.0.0-stage 调试残留 排查发布流程时产生的占位,不含代码,没人会装它。

上面记录的是两种完全不同的失效方式,表现天差地别:

  • 清单写错是静默的。 宿主把插件丢进 skippedBundles 然后继续跑,所以它看起来和正常安装一模一样,除非你去确认压缩真的跑了。

  • dsh.client 坏掉是响的、但也是致命的。 只要 package.json 声明了 dsh.client 且 platform: "web",宿主就必须为它建一条前端行,并且这条行必须能激活。没有降级路径:激活失败 = 整个 web boot 中止,应用起不来:

    web boot: 1 entry did not activate
    dsh-compaction-vcc: import failed | loading | pending (waiting for services: ...)
    

    而且它只在 bundle 装法(dsh plugin add)下触发。别名装法从不加载 dsh.client,所以那台机器上完全看不到这个毛病——0.1.7 到 0.1.9 就是这么发出去的。

如果你在 0.2.0 以下的任何版本,请升级。 三个坏版本已在 npm 上标记弃用。