前言¶
DeepSeek Harness (DSH) 在构建智能体时，智能体在每一步都会重发整个历史记录。其中大部分是工具输出（文件读取、命令执行等）。这会占用上下文窗口。该插件释放模型可见历史中已不再需要的工具调用及其结果，用简短的存根替换它们。
插件概述¶
这是 DeepSeek Harness 的一个插件，用于上下文卸载。由 Hanochhu 维护，使用 MIT 许可证。它将模型可见历史中的工具调用及其结果替换为简短的存根，同时保留原始记录在会话日志中以便重放。
安装与启用¶
安装命令如下：
dsh plugin --profile web add dsh-context-offload
重启 dsh web 后，插件会自动挂载到 profile composition 并覆盖该 profile 下的所有 agent。
若要禁用而不卸载，可在 profile 的 cordis.patch.yml 中添加以下内容：
- id: context-offload
disabled: true
工作原理¶
插件通过两种路径实现上下文卸载：
1. 基于策略的批量释放：在 agent/pre-step 阶段，策略会检查当前累积的未卸载内容。当新产生的完整工具单元数量超过 retainUnits，或者累积的字符数达到 flushChars 时，会执行一次批量替换。每次批量替换最多替换 maxUnitsPerFlush 个单元，且每 flushEverySteps 步最多触发一次。
2. 模型主动卸载：插件提供了 offload_context 工具，允许模型在请求中主动卸载已完成的调用。该请求会在工具调用时记录，并在下一个步骤边界应用。
模型可见的历史中，每个被卸载的工具单元（包含助手消息和所有回答结果）会被一个 user/message 类型的存根替换。存根内容如下：
[tool context offloaded — 2 tool call(s) removed from model context; 39,045 characters released]
- bash(command=cd /Users/me/proj && ls -la && for d in */; do echo …)
- read(path=src/harness/loop.ts)
The original arguments and results remain in the session log. Re-read a file or re-run a command if you need the content again.
配置¶
所有字段均为可选。默认值如下：
| 字段 | 默认值 | 说明 |
|---|---|---|
enabled |
true |
设置为 false 时仅保留模型可见的工具调用。 |
retainUnits |
8 |
模型可见历史中保持完整内容的最近完整工具单元数量。 |
minUnitChars |
4000 |
小于此字符数的单元不值得替换。 |
flushChars |
20000 |
累积的可释放字符数达到此值才触发刷新。 |
flushEverySteps |
10 |
每隔最多这么多步触发一次刷新。 |
maxUnitsPerFlush |
40 |
单次刷新中替换的单元数量上限。 |
作用范围与限制¶
该插件通过 dsh.bundle.patch 挂载到配置文件中。默认情况下，它挂载到 profile composition 中，覆盖该 profile 下的所有 agent。
若需将其限制到单个 preset，不要启用 bundle 行，而是安装包以便 node_modules 能够解析，然后将配置添加到自己的 preset 复制中：
- id: context-offload
name: dsh-context-offload
必须启用以下两种方式之一，且不能同时启用。
该插件与 compaction-basic 上下文压缩插件配合使用，两者不冲突，且不会相互覆盖。
需要注意的是：
* 人类对话记录中不会显示被替换的内容，因为转录是从追加事件渲染的。
* 未完成的步骤或系统提示（surface node 0）不会被处理。
* 插件依赖 Node.js >= 20 和 DSH >= 0.1.5-rc.1。
总结¶
该插件通过替换模型可见历史中的冗余工具输出为存根，在不丢失原始日志的前提下，有效减少了模型上下文的占用，适合在处理长对话或复杂任务流时使用。
