前言¶
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。
總結¶
該插件通過替換模型可見歷史中的冗餘工具輸出爲存根，在不丟失原始日誌的前提下，有效減少了模型上下文的佔用，適合在處理長對話或複雜任務流時使用。
