dsh-compaction-cache

让 DSH 的压缩摘要调用带上和它替代的那一轮完全相同的请求参数，于是 provider 的前缀缓存继续命中——而不是把整段回放的历史按全价重算一遍。

DSH（DeepSeek Harness）插件 · 零依赖 · 零工具 · 零 UI · 免构建 · MIT

这是一个绕官方缺陷的临时补丁。 官方修好后（上游 deepseek-harness discussion #1944）请把它整包删掉。

English: README-en.md

---

它解决什么问题

dsh-compaction-basic 的 summarizeWithLlm 组装摘要请求长这样：

{ provider, model, messages, toolHistory, tools?, maxTokens: config.maxTokens,
  sessionId, purpose: 'compaction', signal }

它只从会话已固化的路由头里取了 provider / model，于是：

参数	正常一轮	压缩调用
reasoningEffort	max（会话档位）	不带 → 适配器回落 high	分叉
maxTokens	256000（适配器默认）	65536（config.maxTokens ?? headroomTokens）	必分叉

而 provider 侧的缓存键按请求信封分区，其中起决定作用的是思考档位（reasoningEffort， 实测归因见下）——档位一分叉，整段回放前缀全部 miss，压缩本身 （一次本来只该多付"指令那几个 token"的调用）变成全价重算上一整段上下文。

实测（1M 窗口，DeepSeek 路由，会话档位 max）

同一会话、同一条命令（手动 /compact，source: user）、同一条路由，唯一差别是有没有本插件 （修后那次紧跟在一次宿主重启之后——provider 缓存是服务端的，而"前缀命中 99.7%"本身就证明 重启后回放的前缀字节与重启前一致）：

	折叠区间	prompt	inputTokens	cacheReadTokens	命中	输出	墙钟
装插件前	113,767	150,320	132,528	17,792	11.8%	3,749	17.0 s
装插件后	170,026	223,920	560	223,360	99.7%	4,590	18.2 s

修后剩下的 560 token 新鲜输入 ≈ 那条追加在末尾的压缩指令本身（1802 + 534 = 2336 字符， ≈4.2 字符/token）——即整段回放前缀全部由缓存服务，这正是 summarizeWithLlm 的文档注释 所承诺的（"replay the conversation prefix … so the provider's warm prefix cache is reused"）。 同一会话的普通回合本来就是 149,632 / 149,837（命中 99.9%），修后折叠与它们回到了同一个缓存条目。

修前的形态也自洽：本机 216 个会话档案里今天之前录得的 51 次折叠，平均命中 23%，其中 40 次低于 50%， 且命中的那一截恒定在 ~17.3–18K（= 系统提示 + 工具 schema），与折叠大小无关——那是 "参数分叉的信封自己攒下的缓存条目"，永远轮不到普通回合刚写热的回放前缀。 这一现象早于任何第三方压缩插件存在：9-28 的第一次折叠就是 518,458 / 0（0.0%）。

归因：分叉的决定性字段是 reasoningEffort，不是 maxTokens

把 52 次带 request/header 前情的 LLM 折叠按"折叠信封 vs 该会话普通回合信封"分组 （折叠信封固定 = 不带 effort → 适配器回落 high，maxTokens 65536）：

分组	次数	平均命中	新鲜输入
effort 相同（会话档位 = high）	7	99.9%	448–589 token
effort 不同（会话档位 = max）	45	12.7%	5 万–66 万 token

那 7 次全命中里，maxTokens 依然是分叉的（折叠发 65536、普通回合发 256000）。 若 max_tokens 参与缓存键，这 7 次应当和另外 45 次一样全 miss——所以本 provider 的键不含它。

两个独立佐证：

• 同会话内切换档位（b2d7c860…，HD2SDK 会话）：10-01 15:38 → 10-02 16:55 的 5 次折叠在 档位 high 下命中 99.9%（in = 540 / 492 / 589 / 448 / 448）；档位切成 max 之后， 同一个会话、同一条路由的后续 27 次折叠里有 22 次落在 0.3–3.4%（in ≈ 50 万–66 万）， 例外只有两次过渡态（73%、71%）和下面的两次重试对。
• "中止后重试"的自然对照 ×2：10-06 22:13:56 与 10-09 19:03:46 各有一次 /compact 在 11–12 秒后被中止（This operation was aborted），随后重发同一条命令——重试那次 in=177 / cached=639,744、in=171 / cached=659,712（都是 99.97%）。 被中止的那次已经把这段前缀写进了分叉信封自己的缓存条目，重试立刻全中。 这证明分叉信封的缓存条目是存在且可用的：历史上的 miss 不是"压缩请求注定冷启动"，纯粹是信封不同。

结论：上游修法必须带上 reasoningEffort（或等价的思考档位字段）；对齐 maxTokens 是 防御性的（别的 provider 可能真的把它算进键），在本机实测里它不影响命中。

它做什么

挂在公开的 llm/stream 瀑布上，只对调用方自己打了 purpose: 'compaction' 标签的请求， 把上面两个参数补齐成路由头里的值：

reasoningEffort = header.config.reasoningEffort   // 仅当 options 未设置，且 header.adapterDefaults 未标记它
temperature     = header.config.temperature       // 同上
maxTokens       = header.config.maxTokens         // 无条件覆盖（摘要器总是强设它）

两条不同的规则来自缺陷的两半：mirror 类参数正常一轮本来就是让适配器物化的，摘要调用也一样， 所以只在"未被显式标记为适配器默认"时才注入；而 maxTokens 摘要器永远会覆盖成自己的值， 正常一轮永远不可能与它一致，所以必须对齐成路由值。

边界：只改标量参数，不碰消息列表；不碰任何普通请求；任何异常都被吞掉并照常 调用 next()——这个插件坏掉时只会退化成官方原样，绝不会阻断一次模型调用。

安装（只从 GitHub 分发）

本包不发布 npm、不进插件市场：它是对上游那个三行修复的临时补丁，官方修好后就该整包删掉， 不适合做成长期存在的包。package.json 里的 private: true 是刻意加的。

方式一 · 作为依赖写进 profile（github: 规格）：

// <DSH_HOME>/profiles/<profile>/package.json
"dependencies": { "dsh-compaction-cache": "github:deepseekv41flash/dsh-compaction-cache" },
"dsh": { "profile": { "bundles": ["…", "dsh-compaction-cache"] } }

本机实测（pnpm 11.22.0）：pnpm add github:deepseekv41flash/dsh-compaction-cache 解析到 0.1.0、 导入正常，private: true 不影响安装。profile 的依赖本来就是 pnpm 装的，所以这条规格可用。 （npm install github:… 在本机会被解析成 ssh://git@github.com/…，没配 SSH key 就是 Permission denied (publickey)——那是 npm 的 shorthand 行为，与包无关。）

方式二 · 本地 clone + link:（本机实测走的就是这条）：

git clone https://github.com/deepseekv41flash/dsh-compaction-cache
# dependencies 里写 "dsh-compaction-cache": "link:<clone 路径>"，bundles 里再加同名一项

本包带 dsh.bundle.patch，列进 dsh.profile.bundles 即自动装配；lib/ 是纯 JS、无构建步骤， clone 下来就能跑。不想用 bundles 的话，也可以在 profile 的 patch 层显式插入：

- insert:
    - id: compaction-cache
      name: dsh-compaction-cache

配置（全部可选）

键	默认	说明
enabled	true	总开关
log	true	每次对齐写一行 info
mirror	['reasoningEffort','temperature']	会话路由头里要镜像的参数名
alignMaxTokens	true	是否把 maxTokens 对齐成路由值

验证

npm test          # 20 项单测：镜像/适配器默认/幂等/冻结信封/缺服务降级/标签判定/挂载自证

生效后，宿主日志里会出现：

compaction-cache: aligned summarization envelope (reasoningEffort=max maxTokens=256000 (was 65536)) session=...

判据（对比修前）：下一次折叠的 compaction/summary.usage 里， inputTokens 从 ~13 万掉到几百、cacheReadTokens 变成六位数。

已知不确定处

• 归因已由 52 次折叠的自然实验定位到 reasoningEffort（见上）；仍未做的只剩主动单字段实验 （把 mirror 置空、保留 alignMaxTokens: true 再折一次）——但从数据看预期是"命中不变"。
• 上游的正确修法是整包继承路由信封，而不是逐字段打补丁。
• 一个只影响审计、不影响账单的坑：compaction/summary 事件里记录的 maxTokens 取的是 spec（config.maxTokens），不是实际发出的信封——所以事件里永远写着 65536。 判断本插件是否生效要看 usage 的 inputTokens / cacheReadTokens 分裂，不要看那个字段。

卸载

从 profile patch / bundles 里删掉那一行即可，重启即净——没有工具、没有落盘状态、不改任何包源码。 官方修复落地后应当卸载。

License

MIT