上下文压缩 hardes11/dsh-squeeze-command

dsh-squeeze-command

昂贵模型会话的每一轮都会重新发送其完整历史记录。/squeeze 会将其压缩到你选定的预算范围内。

npm version
License: MIT
DSH Plugin

一个用于 DeepSeek Harness 的斜杠命令，可按需压缩会话的上下文——摘要由廉价的 flash 层级路由撰写，而非你正在付费的模型。

之前 / 之后

/squeeze status
Surface: 331 messages, ~371,000 tokens — OVER budget by 271,000 (budget 100000). Summarizer: ollama/glm-5.3-flash:cloud. Read-only; nothing was changed.

/squeeze
Squeeze mode activated (target 100000 tokens, ~371,000 now; summaries via
ollama/glm-5.3-flash:cloud). The model will pick ranges; the summarizer
writes the checkpoints.

... the model reviews its context, marks compressible ranges,
flash summarizers write the checkpoints in parallel ...

Squeezed 3 span(s) (~74,963 tokens shadowed). Surface now 116 messages, ~97,445 tokens.

/squeeze status
Surface: 44 messages, ~45,780 tokens — under budget (100000 by 54,220).

它的作用

- 削减你重新发送的内容。 在空闲会话上执行一条命令即可将其降到预算以内——而且每份摘要都由你配置的廉价路由撰写，而非运行对话的前沿模型。
- 不会丢弃任何内容。 每次压缩都会在表层留下一个检查点；原始消息仍保留在仅追加的会话日志中——/squeeze map 让你可以浏览它们。
- 防止压缩后的混乱。 每份检查点摘要都以一行明确的 Span end-state:（每个任务的 COMPLETED/PENDING）结尾，压缩结果还携带一份根据未压缩尾部计算出的可信未完成工作摘要——这样模型就不会在没有完成状态的情况下重新进入摘要所描述的工作。
- 仅在你要求时触发。 没有阈值，没有自动触发，并且在代理轮次进行中时拒绝运行。
- 无需派发代理。 摘要委派已内置——你运行一条命令，其余一切都在其中完成。

/squeeze compress toward contextBudgetTokens (preset config)
/squeeze 60k one-off token target (also plain: /squeeze 60000)
/squeeze status read-only: message count, token estimate, budget, summarizer
/squeeze map read-only: interactive HTML map of every checkpoint
/squeeze help full usage guide

/squeeze map —— 查看压缩做了什么

/squeeze map 将会话日志重放为一个自包含的 HTML 页面（写入你的临时目录并在浏览器中打开；无 LLM 调用，不修改任何内容）。在已压缩的会话上，它会显示：
- 每次 /squeeze 调用对应一条时间线泳道（根据提交时间戳重建）——每个检查点条都可点击。
- 事件密度直方图——哪些历史区段仍活跃在表层，哪些被遮蔽在检查点内部。
- 检查点表格，包含每个检查点的存活比率（摘要 token 与遮蔽 token 之比）。
- 之前 / 之后——检查点所替换的原始消息，与代替它们的摘要并排展示。
- 表层时间机器——original、after squeeze N（每次调用一个）和 current 按钮：精确展示模型的工作集在每个时间点的样子。

它同样适用于从未被压缩过的会话（全活跃直方图、完整记录——这是对一次压缩将会处理什么的有用预览）。

squeeze map demo

（合成演示数据——用 node tools/squeeze-explorer.mjs --demo 重新生成。）

同样的视图也可作为独立脚本用于任何会话日志，无需挂载插件：

node tools/squeeze-explorer.mjs ~/.dsh/sessions//session-/session.jsonl.zstd

安装

1. 将包克隆到你的 DSH commands 目录：

git clone https://github.com/hardes11/dsh-squeeze-command.git ~/.dsh/commands/dsh-squeeze-command

2. 在你的 profile 的 resolver manifest 中注册它——DSH 从 profile 的 node_modules 解析裸插件名，因此 manifest 条目加上符号链接即可将其放到那里：

// e.g. ~/.dsh/profiles/web/package.json — substitute your profile
"dependencies": {
"dsh-squeeze-command": "link:../../commands/dsh-squeeze-command"
}

ln -s ../../../commands/dsh-squeeze-command ~/.dsh/profiles/web/node_modules/dsh-squeeze-command

3. 在某个 preset 的 compaction 组中挂载它（~/.dsh/presets//agent.cordis.yml）：

- id: command-squeeze
name: 'dsh-squeeze-command'
config:
contextBudgetTokens: 100000
summarizerProvider:
summarizerModel:

4. 重启 DSH，然后运行 /squeeze status。如果它打印出一行预算信息，说明该命令已生效。（即使未配置，status 也能工作——它会告诉你缺少什么。）

配置

| 字段 | 默认值 | 含义 |
| contextBudgetTokens | —（裸 /squeeze 必填） | 裸调用的目标值 |
| summarizerProvider | —（必填） | 摘要路由的 provider key |
| summarizerModel | —（必填） | 摘要路由的模型 id |
| summarizerReasoningEffort | null | 摘要器调用的 effort 固定值；仅当该路由的 effort 映射声明了该值时，才固定为例如 low |
| summarizerConcurrency | 5 | 最大并行摘要器调用数 |
| maxSpanInputTokens | 30000 | 每个 span 的摘要器输入上限 |
| maxSummaryTokens | 2048 | 每个摘要的输出上限 |
| minSpanTokens | 200 | 值得建立检查点的 span 下限 |
| maxSnapSteps | 5 | 平衡边缘吸附预算 |
无效值（零、负数、非整数）会在插件加载时以具名字段错误失败，而不是在压缩时失败。

摘要器路由应使用廉价、快速的模型——flash 级别的模型是最佳选择：密集摘要并非推理密集型工作，而且各跨度可并行运行。该插件与提供商无关；在你的 DSH 设置中注册的任何路由都可以使用。

兼容性

- DSH： peerDependencies 为通配符——宿主提供 @deepseek-ai/dsh-compaction 和 @deepseek-ai/dsh-llm。可跨 API 代际工作（0.1.1 的急切 session.events 数组和 0.1.2 的 snapshotEvents() 均已处理）。
- 标准 DSH Bundle： cordis.patch.yml（仅插入、独立行）+ 带有 compatibility.dshReleases 的 dsh 清单块（声明了 0.1.1 和 0.1.2-rc.1——两者均已通过实际运行验证）。
- Node： >= 22（engines）。
- 摘要器路由： 与提供商无关——DSH 设置中注册的任何提供商均可。

安装前值得了解的注意事项：

- 仅手动。任何内容都不会自动触发，绝不。
- 当智能体回合或压缩处于活动状态时会拒绝执行。
- 一次压缩会使提示缓存失效（它会重写上下文前缀）——请在一个已空闲足够久、缓存反正已过期的会话上运行它。
- 被压缩的跨度在表面上会被检查点消息替换——可见的转录会发生变化，尽管会话日志保留原始内容。

原因

使用昂贵模型进行的长对话会淹没在输入 token 成本中：每一回合都会重新发送整个历史记录，而输入成本占主导——而非思考成本。每一回合都向前沿模型发送 30 万 token 的对话是预算杀手；提供商提供的缓存前缀折扣（提示缓存）只能在前缀保持稳定时缓解这一问题。

/squeeze 会将上下文收缩到你选择的预算，并采用一种刻意为之的分工：对话模型（无论昂贵与否）只负责挑选哪些跨度需要压缩——一个小而廉价的决策——而配置的摘要器路由负责撰写检查点摘要，因此压缩永远不会付出前沿模型的价格。

工作原理

/squeeze 要求模型标记可压缩的范围（一次工具调用）。一个廉价路由并行撰写摘要。检查点按顺序提交，原始内容保留在会话日志中。成功压缩后，一次额外的廉价路由调用会将未压缩的尾部消化为一份追加到工具结果中的未完成工作重述——历史摘要永远不会凌驾于它之上。

实现说明

- 模型挑选的跨度边界会向外对齐到工具配对平衡的切分点；会与已规划邻居重叠的跨度会被裁剪到空闲子区间（完全覆盖或拆分的跨度会随一条消息一起丢弃）。
- 摘要生成以有界并行度（summarizerConcurrency）运行，不持有任何锁；每个检查点随后通过其自身紧凑的同步括号（compaction/start → compaction/summary → surface replace → compaction/end）提交，遵守压缩能力的单锁契约。没有任何代码路径会让括号悬空。
- 触及令牌上限的摘要会失败关闭——被截断的检查点永远不会被接受。

开发

npm ci # .npmrc pins legacy-peer-deps for the rc-tagged peer closure
node smoke.mjs # 59 behavior checks against real Session objects, no LLM needed

/squeeze -h 和 --help 可作为 help 的别名使用。

许可证

MIT