前言¶
在 DeepSeek Harness (DSH) 的長上下文開發中，一個常見的問題是固定預留的輸出額度（例如 384K）與不斷增長的輸入文本發生預算碰撞，導致服務端在輸入尚未被壓縮時便直接拒絕請求。dsh-adaptive-max-tokens 是一個插件，旨在將固定的輸出預留變爲動態額度，通過根據上下文估算動態調整 maxTokens，在壓縮策略生效前釋放出被佔用的上下文空間。
插件定位¶
這是一個由 3289192-bot 維護的模型推理類插件。它運行在 DSH 的 Web profile 下，通過讀取宿主內存中的請求元數據和會話事件來計算剩餘空間，不主動聯網、不寫入文件、也不讀取憑據。該插件僅調整輸出額度，不改變模型的推理強度，也不增加模型的真實上下文容量。
核心功能¶
該插件主要解決以下具體問題：
- 動態調整 maxTokens：根據當前輸入估算、上下文容量和安全餘量計算允許的最大輸出長度。
- 壓縮後恢復額度：在壓縮策略生效後，重新按配置和當前模型的輸出上限計算，避免一直沿用之前縮小的數值。
- 中斷續聊保持校準：利用已有的 usage 記錄輔助估算，避免因單次無 usage 的回覆丟失有效的校準點。
- 識別並重試超限錯誤：對代碼中識別的上下文超限錯誤格式進行攔截，嘗試縮小輸出額度並重試一次；其他情況交回宿主處理。
- 路由兼容：在切換模型時，遵守當前路由和 agent 的顯式上限約束。
安裝與啓用¶
在安裝前，請確認當前 DSH 版本。該插件僅支持 0.1.6-alpha.1 或 0.1.7-rc.2。
1、檢查版本：
dsh --version
2、安裝插件：
dsh plugin --profile web add github:3289192-bot/dsh-adaptive-max-tokens#v0.1.0
安裝後，默認對該 profile 的 agent 請求生效。
3、重啓實例：
在任務空閒時重啓對應的 DSH Web 實例，再開始新會話。如果之前手動安裝過舊版，請先從自定義預設中移除或禁用舊的 adaptive-max-tokens.mjs 行，再啓用本包。
卸載命令：
dsh plugin --profile web remove dsh-adaptive-max-tokens
默認參數與計算邏輯¶
插件內置了一套默認參數用於計算輸出預算。以下是基於 1,000,000 上下文預算和 384,000 輸出上限的典型配置：
| 參數 | 值 | 說明 |
|---|---|---|
effectiveContextWindow |
1,000,000 | 配置的上下文預算上限，取它與適配器聲明值中的較小值 |
maxOutputTokens |
384,000 | 配置的輸出上限，同時受當前適配器和 agent 上限約束 |
safetyTokens |
32,768 | 爲估算誤差保留的空間 |
minOutputTokens |
16,384 | 期望最低額度，空間不足時仍會繼續收縮 |
pendingWeight |
1 | 待接收輸入的最低估算權重 |
log |
true |
輸出預算變化日誌 |
計算邏輯簡化爲：輸出額度 = max(1, min(輸出上限, 上下文預算 − 安全餘量 − 輸入估算))。
適用場景與限制¶
適用場景：需要處理長上下文對話，且希望減少因固定輸出預留導致的上下文溢出錯誤的場景。
重要限制：
1. 無法保證不溢出：插件基於估算計算，包含誤差。附件、新工具及大段新輸入可能超出估算，無法保證每次請求都不會超限。
2. 不增加容量：插件不增加模型真實上下文容量，也不修改官方壓縮策略或摘要參數。
3. 重試範圍：重試僅支持代碼中識別的上下文超限錯誤格式，未知格式直接交回宿主。
4. 隱私安全：插件僅讀取內存中的請求元數據和 usage 數據，不涉及憑據讀取，但啓用日誌後會記錄會話標識與錯誤信息。
總結¶
dsh-adaptive-max-tokens 是一個爲解決長對話中輸出預算衝突而設計的實用工具。它通過動態收縮和恢復機制，讓輸出額度讓位於輸入，配合官方壓縮策略使用，能顯著提高長上下文任務的穩定性。更多詳情與兼容性說明可查閱 GitHub 倉庫。
