前言¶

在開發 DeepSeek Harness 智能體時，長對話歷史和大量工具輸出容易導致上下文溢出。宿主原有的壓縮流程有時缺乏明確的收益判斷，或難以精細控制關鍵記憶與診斷信息的保留。下面介紹 dsh-ctxopt-compaction，一個在宿主原有壓縮流程基礎上增加收益判斷、有界摘要緩存、顯式記憶控制以及保留診斷信息的工具輸出裁剪插件。

插件簡介¶

dsh-ctxopt-compaction 是 DeepSeek Harness 的上下文壓縮插件，由維護者 chunsi-w 開發。當前版本爲 0.0.1。它不作爲獨立聊天服務運行，而是依賴宿主提供必要的依賴（包括壓縮引擎、工具裁剪、LLM、會話與 Schemastery）。插件通過 JavaScript 源碼提供功能，無需轉譯。

安裝與啓用¶

在宿主環境中啓用該插件，需要先獲取並打包源碼，然後通過宿主的安裝機制加載。

獲取與打包¶

git clone https://github.com/chunsi-w/dsh-ctxopt-compaction.git
cd dsh-ctxopt-compaction
npm pack

生成的包名爲 dsh-ctxopt-compaction-0.0.1.tgz。

Headless 加載¶

在已安裝依賴並構建完成的 DeepSeek Harness 目錄中執行以下命令，替換插件的絕對路徑：

pnpm dsh plugin --profile headless add file:/absolute/path/to/dsh-ctxopt-compaction
pnpm dsh --profile headless --dump-config

執行後檢查生成配置中是否包含 ctxopt-compaction 和 ctxopt-tool-result-pruner，並確認同層默認組件已禁用。

Web 加載¶

在 Web 環境中，僅安裝頂層 bundle 或直接傳入 cordis.patch.yml 不足以替換 standard 預設中的默認組件。需基於宿主的 packages/bundle/web-app/presets/standard.patch.yml 創建覆蓋配置。在 compaction 組內，將 compaction-basic 的 name 改爲本倉庫 src/engine.js 的絕對路徑，將 tool-result-pruner 的 name 改爲 src/pruner.js 的絕對路徑。

- id: compaction-basic
  name: /absolute/path/to/dsh-ctxopt-compaction/src/engine.js
  config:
    thresholdRatio: 0.4
    headroomTokens: 512
    retainTokens: 1400
    maxTokens: 1536
    compactionRetries: 1
- id: tool-result-pruner
  name: /absolute/path/to/dsh-ctxopt-compaction/src/pruner.js
  config:
    thresholdChars: 8192
    headChars: 4096
    digestChars: 1536
    tailChars: 1024

核心功能¶

插件主要包含以下五個組件與能力：

1. 壓縮收益判斷：按實際待替換歷史估算收益，排除未被替換的 system 消息；默認不足 512 估算 token 的片段跳過摘要調用。
2. 摘要質量與預算：摘要過短、超預算或節省不足時拒絕替換，保留原歷史；默認不額外重試退化摘要。
3. 摘要緩存：按會話、輸入、工具歷史、路由及配置區分緩存，限制條數、字節數和有效期。
4. 可控記憶：通過明確指令保存、更新、刪除鍵值事實與待辦，將當前狀態寫入壓縮 checkpoint。
5. 診斷保留：裁剪長工具輸出時，在頭尾之間保留預算允許的中段錯誤、文件、工單等診斷信息。

配置說明¶

插件通過配置文件控制收益判斷、緩存大小、記憶條目和工具裁剪參數。宿主 patch 會替換目標條目的整個 config，不會遞歸合併。

引擎配置¶

以下爲針對 32K 窗口的示例參數，其他數值爲本插件默認值：

thresholdRatio: 0.4
headroomTokens: 512
retainTokens: 1400
maxTokens: 1536
compactionRetries: 1

budgets:
  minRegionTokens: 512
  minSavingsTokens: 96
  checkpointReserveTokens: 128
  maxCheckpointTokens: 2048
  maxExtrasTokens: 384

cache:
  enabled: true
  maxEntries: 16
  maxBytes: 262144
  ttlMs: 300000
  failureTtlMs: 30000

memoryBlock: true
reminders: true
memory:
  maxItems: 8
  maxTodos: 4
  maxItemChars: 160
  allowedKeys: []

anchorValidation: true
degenerateGate: true
degenerateRetries: 0
economics:
  enabled: false

關鍵參數說明¶

• thresholdRatio / headroomTokens：控制宿主觸發壓縮的位置和窗口餘量，不是輸入的硬截斷上限。
• maxCheckpointTokens：用於計算摘要預算，需扣除 checkpointReserveTokens；最終 checkpoint 由宿主計量。
• cache.maxEntries / maxBytes：每個引擎實例的緩存條數和鍵/序列化載荷字節上限，不是進程 RSS。
• memory.allowedKeys：允許保存的鍵名白名單；空數組表示不限制鍵名。

工具輸出裁剪配置¶

裁剪器的獨立配置默認值如下：

thresholdChars: 8192
headChars: 2048
digestChars: 1536
tailChars: 2048
smartDiagnostic: true

headChars、digestChars、tailChars 分別控制頭部、診斷摘要和尾部預算，按 Unicode code point 計數。設 tailChars: 0 可關閉智能裁剪路徑的尾部保留。

記憶與待辦控制¶

在用戶消息中單獨寫入指令行，可控制記憶與待辦狀態。發送時不要放在代碼塊或引用內。

指令示例¶

MEMORY project=ATLAS
MEMORY schema=v3
TODO release=完成迴歸測試後發佈
MEMORY schema=v4
FORGET project
DONE release
MEMORY RESET

指令規則¶

• 同一個鍵再次賦值表示更新。
• 刪除、完成和清空的寫法見上。
• 鍵名區分大小寫，允許 1–64 個 ASCII 字母、數字、下劃線、點或連字符。
• 條數超限時淘汰較早更新的條目；單條值超出 maxItemChars 時跳過整條。
• 待辦只是摘要中的未完成狀態，不是定時提醒，不跨會話共享。
• FORGET 和 MEMORY RESET 只清除插件管理的當前狀態，不擦除原始聊天日誌或模型摘要裏的歷史敘述。

注意事項¶

1. 信息保留：壓縮仍由模型生成摘要，不能保證所有歷史信息都被保留。
2. 依賴要求：需要宿主提供 package.json 中聲明的 peer dependencies。
3. 運行方式：不能作爲獨立聊天服務運行。
4. 配置合併：宿主 patch 會替換目標條目的整個 config，不會遞歸合併。
5. 日誌查看：源碼路徑加載不會自動生成已安裝插件的管理卡片。可通過檢查宿主日誌中的 ctxopt decision、skip-small-region、summary-ready 等關鍵字判斷是否生效。
6. 性能依賴：延遲與 token 收益依賴實際輸入及模型服務，本 README 不承諾固定提升比例。