智能压缩时机 JoblessJoe/smart-compaction

DeepSeek Harness（dsh）插件，让模型自己决定何时压缩上下文，而不是被一个盲目的 token 阈值在任务中途打断。

- compact_now： 在模型知道安全的位置压缩，比如刚做完一项 todo。回合中途也能用。
- context_status： 给出真实 token 用量，对照会话实际的上下文窗口，模型不用再猜。
- 自动安全点压缩： 本地模型很少主动调用这类工具，所以插件还会自己动手：一旦某个 todo 项标记为完成、且上下文占用超过一半，就立刻压缩。不需要模型做决定。
- 无需配置，不改核心： 只基于 dsh 公开的压缩 API 构建。

npx @deepseek-ai/dsh plugin --profile web add smart-compaction
npx -p smart-compaction smart-compaction-mount-into-presets # web profile: mount into your presets

web 配置档会实时重载，不用重启。细节和边界情况见 Install。

为什么需要它

dsh 内置的压缩完全是反应式的：只要 token 压力越过固定阈值，自动触发器就在智能体步骤之间开火，根本不管那一刻是不是打断的好时机。它可能落在两个相互依赖的步骤之间——比如刚读完文件、正要根据刚读到的内容去改它——结果生成的摘要恰好丢掉了下一步最需要的上下文。

这个插件不改压缩怎么做，只改谁来决定何时做。它把工具交给模型，让模型凭自己的判断主动调用，而不是把决定权全交给一个盲目的 token 计数器。

它能做什么

两个工具，都无需参数。

compact_now

- 选出当前可压缩的最大一段对话历史——沿用 dsh 自身压缩已经保证的、工具调用配对安全的边界逻辑，重新实现仅针对 dsh 的公开 API（不改 dsh 核心，不依赖 compaction-basic 的内部实现）。
- 在调用 compactRegion() 之前，先往聊天里发一条「Compacting now」提示，而不是之后 —— 摘要调用会多一次模型请求，可能耗时很久（本地模型上要几分钟），没有这条提示，聊天看起来就卡在工具调用和它的结果之间。这条提示带上自己的 source kind 和 form: 'notice'（dsh-compaction-basic 自己的检查点消息和其他宿主生成的旁白也用同样的标记），因此会渲染成折叠的系统旁白，而不是像用户自己敲的，也不需要模型为它输出任何内容。
- 调用 dsh 自己的 ctx.compaction.compactRegion() 来真正执行压缩 —— 同一个摘要器，同样的持久化 compaction/start/compaction/end 日志事件，和会话里任何其他压缩一样的保证。
- 历史还不够多时，无害地空操作（"Not enough compactable history yet."）—— 模型可以放心试探性调用。空操作调用不会发提示。

context_status

- 只读 —— 从不修改会话，随时可安全调用。
- 报告当前 token 用量和这个会话所用模型的实际上下文窗口大小，例如 "~42,300 / 77,824 tokens used (54.3%)."
- 通过公开的 ctx.sessionProjections.stateOf() API 读取 dsh 自己的 contextPressure 会话投影（由 @deepseek-ai/dsh-token-meter 注册，挂载在 compaction-basic 所在之处）—— 和 Web UI 自己的上下文计量器读的是同一组数字。没有任何硬编码：上下文窗口数字来自这个会话实际路由到的模型，所以换不同模型、配置档、上下文窗口大小，它都无需改动而保持正确。
- 之所以存在，是因为没有它，模型对自己的上下文用量毫无可见性 —— 之前唯一的信号只是 compact_now 自己的描述里那句含糊的「如果对话感觉很长」。

自动安全点压缩

- 监听 todo_write。当某项翻转为 completed，就是一个完成的步骤：一个适合切分的安全位置。
- 如果那一刻用量已超过 safePointRatio（默认 0.5），下一步就在压缩后的历史上开始。提示相同，compactRegion() 路径也和 compact_now 相同。
- dsh 自己的 80% 触发保留作为兜底；这只是先一步到达，在一个干净的边界上。
- 这里失败绝不会中断本轮。它会记一条警告，然后兜底接管。
- 在你的配置档的 cordis.patch.yml 里调整或关掉它：

- id: tool-compact-now
config:
safePointRatio: 0.6 # or false to disable

工作原理

dsh 的压缩服务上有两个入口：compactNow()（人类 /compact 命令用的 —— 要求智能体处于空闲状态，否则抛 busy）和 compactRegion()（dsh 自己的自动步骤间触发用的 —— 在轮次中途也能正常工作）。工具的 execute()
它总是在回合中途运行——调用工具就是这个意思——所以 compact_now 建立在 compactRegion() 之上，而不是 compactNow()。

安装

装进你的 dsh web 配置档（下面的 web 是配置档名，换成支撑你会话的那个配置档）。从源码检出运行时，用 pnpm dsh 代替 npx @deepseek-ai/dsh：

npx @deepseek-ai/dsh plugin --profile web add smart-compaction

这条命令会安装包，并把它加进 dsh.profile.bundles。（本地没有 dsh 二进制？到配置档目录手动执行等价操作，比如 ~/.dsh/profiles/web/：先 pnpm add smart-compaction，再自己把 "smart-compaction" 加进那个 package.json 的 dsh.profile.bundles 数组。）

不用构建，不用重启：随包发布的 web 配置档支持热重载，插件会立刻出现在 Plugins 下。不支持热重载的配置档（tui、headless 等）会在下次启动时加载它。

在随包发布的 web 配置档上，还要再跑一次这条命令（原因见下文）：

npx -p smart-compaction smart-compaction-mount-into-presets

卸载： 先带 --remove 跑同一条命令，再执行 npx @deepseek-ai/dsh plugin --profile web remove smart-compaction。

依赖要求与预设隔离的配置档（如果 compact_now 提示没有配置压缩服务，读这一节）

compact_now 需要一个 compaction 服务，且从插件自身挂载的位置能够访问到——它在自己的挂载点读取 ctx.get('compaction')，没有更复杂的机制。大多数配置档模板会在宿主平面提供一个，上面那种普通的 bundle 安装就够了。但基于 @deepseek-ai/dsh-web-app 的配置档不一样：它们禁用了宿主平面的 compaction-basic 行，改由每个预设在隔离的 cordis realm 里挂载自己的私有实例（isolate: { compaction: true }）。cordis 的隔离严格向下生效——只有挂载为那个确切组的后代的插件才能看到它（vendor/cordis/src/service.ts）。宿主平面上的插件，包括按普通方式安装的这个插件，是那个隔离 compaction 的祖先，而不是后代，所以无论它在调用时读取服务的手法多巧妙，都永远看不到它。唯一的解决办法是再挂一份作用域受限的插件副本，作为同级行挂进同一个隔离组——它能与宿主平面的副本安全共存（dsh-tools 的作用域工具注册会在单独的层里遮蔽全局注册，见 packages/core/scope/src/store.ts 里的 ScopedLayers.merge）。

scripts/mount-into-presets.mjs（就是上面的 smart-compaction-mount-into-presets 命令）做的就是这件事：它扫描 $DSH_HOME/.agent-presets//agent.cordis.yml（你本地、归你所有的预设覆盖文件——绝不是 node_modules 下随包发布的只读预设），找出任何已经隔离了 @deepseek-ai/dsh-compaction-basic 的预设，并插入一行作用域受限的 smart-compaction 作为它的如果旁边还没有同类文件，就补一个。这个操作是幂等的；对于完全不使用预设的配置档，它什么都不做（只打一行日志说明）。它刻意不是安装脚本：安装过程绝不会自行改动你的预设。新增预设后重新运行即可；--remove 会把那些行删掉，每个文件都恢复成和之前逐字节一致。

如果做完这些，compact_now 仍然报 "no compaction service is configured on this profile"，那说明你的智能体预设在其作用域链里确实找不到 compaction-basic —— 加一个（参见 harness 仓库里的 docs/subsystems/compaction.md）。

context_status 需要挂载 @deepseek-ai/dsh-token-meter（它注册了本工具读取的 contextPressure 投影）。和 compaction-basic 不同，token 计量器即使在预设隔离的配置档上也刻意留在宿主平面（它持有一张进程级、按会话划分的投影表，不该随挂载哪个预设而来去），所以常规的宿主平面安装总能看到它 —— 这一个不需要打预设补丁。如果它压根没挂载，工具照样能干净安装，只是报告 available: false，不会报错。

告诉模型什么时候用它

这一点已经写进两个工具各自的描述里，所以开箱即用，无需任何设置：每个工具的描述都会告诉模型，在完成一个自成一体的步骤后（比如 todo_write 刚把某项标记为 completed）立刻检查 context_status，并在用量爬过大约 70-90% 后接着调用 compact_now。由于这两段描述每次请求都会自动发给模型，这个行为不需要改 AGENTS.md —— 不像这个插件的早期版本，那时完全依赖手写的 AGENTS.md 规则，结果（直接对照真实会话日志测量）基本没被自发使用过：光靠描述，信号强度不够。

话虽如此，常驻指令的分量还是比工具描述重，毕竟后者要在长长的工具目录里和所有其他描述竞争。如果你想进一步强化，把下面这段抄进你的 AGENTS.md（或者你的配置档注入的常驻指令里）：

把某个待办项标记为 completed 之后（绝不要在它还是 in_progress 时），调用 context_status。
不要只把数字和固定阈值比较 —— 那仍然是被动应对，而一个实际比预期更大的步骤，可能在步骤中途就冲过一个看起来还算宽裕的百分比。相反，要权衡剩余空间和下一个步骤实际会花掉多少（读一个大文件、看一段长 diff、派发一个子代理）；如果它明显装不下、没有富余，就立刻调用 compact_now，哪怕用量看起来还不高。早一点压缩不花什么代价；中途耗尽，丢掉的恰恰是那一步需要的上下文。作为硬性兜底，用量超过大约上下文窗口用到 70-80%，本身就足以成为压缩的理由。两个工具都可以放心试探性调用——context_status 只读，compact_now 在历史还不够多、无法压缩时不会做任何事。

把这件事和 todo 完成挂钩很关键：这是一个真实、已经被追踪的信号，表示「我刚做完一个自成一体的工作单元」，而不是让模型自己估算还剩多少活，或者猜一段对话「感觉是不是太长了」——这两件事它一般都做不好。context_status 用真实数字取代这种猜测。

这段代码刻意不把「用量超过 70-80% 就压缩」写成主要规则——只看阈值仍然是被动应对：某一步实际比预期大（大文件、长 diff、派发子代理），就可能在那一步进行中*直接冲过一个看起来很舒服的百分比，而这正是这个插件要避免的步骤中途打断。百分比只作为硬性兜底保留；主要检查是把剩余余量，和即将开始的那一步的体量做比较，只要看起来吃紧就提前压缩——在那一步之前，而不是进行中或之后。

从源码构建

需要 Node 22+。纯 JS，没有构建步骤——git clone、pnpm install，搞定。

git clone https://github.com/JoblessJoe/smart-compaction.git
cd smart-compaction
pnpm install
node test.js

test.js 是纯单元测试，检查范围选择逻辑（select-range.js）和上下文用量摘要逻辑（context-status.js）——不需要真实的 dsh/Ollama 会话。

配置

没有。这个工具不接受参数，除了安装之外不需要任何设置。

状态

compact_now 已针对真实 dsh 会话做过端到端验证，包括：

- 基本调用：工具加载，模型调用它，它选出一个合法的、边界安全的范围，并在回合中途驱动 compactRegion()，全程没有触发这个设计要避免的 busy 失败。
- 一对真实的工具调用/工具结果（todo_write，先标记 in_progress 再标记 completed）落在被压缩的范围内——配对保持正确，没有任何东西被拆开。
- 一个会话里连续三次调用 compact_now（其中一次是误触，在任务中途被 dsh 自己的重复调用防护拦下）——每次都干净完成，没有崩溃，没有 busy，也没有因为在一个已经含有更早一次压缩检查点消息的表面上操作而导致状态损坏。

排查问题： 如果工具返回类似 summarization produced no text summary content 的错误，那不是这个插件的问题——compact_now 选出了合法范围并交给 dsh 自己的摘要器，而摘要器什么都没返回。具体观察到的情况是：被压缩的范围里只有注入的样板内容（比如常驻指令），还没有真正由助手生成的文本——一旦范围里有了真实的对话内容，就稳定成功。如果它出现在范围含有真实内容也要看：先确认你模型的「思考」等级到底是真正强制执行的 token 预算，还是只是一句指令（比如 Ollama 的 think: low 并不强制执行——模型照样能把整个输出预算全花在隐藏推理上，最后不返回任何可见的总结文本）。不管哪种情况，这都是模型／摘要器一侧的问题，不是 compact_now 自己能控制的。

License

MIT

中文简介 · DeepSeek Harness (dsh) 插件：让模型自己决定何时压缩上下文，而不是在任务中途被固定的 token 阈值打断。提供 compact_now（在安全时机压缩，回合中途也可用）和 context_status（对照会话实际的上下文窗口显示真实 token 用量）；某个待办事项完成且上下文已用过半时，也会自动压缩。无需配置，不改动 dsh 核心。安装：npx @deepseek-ai/dsh plugin --profile web add smart-compaction，web 配置还需运行一次 npx -p smart-compaction smart-compaction-mount-into-presets（web 配置实时加载，无需重启）