前言¶
在 DeepSeek Harness（DSH）裏跑帶截圖、識圖的多輪智能體時，每次模型請求都會帶上完整會話歷史；歷史裏的每一張圖都會在請求體裏重新編碼。對話輪次一多，請求體體積會持續增長，直到超過上游網關的單次請求體上限。以 README 中提到的 agent2api 爲例，其上限爲 16 MiB：一旦累積圖片把請求撐過這條線，網關會以不可重試的 INVALID_REQUEST（例如 HTTP 413）拒絕請求，會話後續再也無法完成一次正常調用；Harness 適配器側默認的圖片預算（20 MiB）往往不會先觸發，問題會直接卡在網關層。
下面介紹社區插件 dsh-image-size-guard（維護者 qq744287383，GitHub：qq744287383/dsh-image-size-guard）。它在請求即將超限時，用佔位文本批量替換會話裏最舊的歷史圖片，把請求體一次性壓到上限以下的低水位，並在設計上儘量降低對 provider 前綴 prompt cache 的反覆擊穿。插件在 SkillHub 目錄中歸類爲「模型推理」。
這是什麼¶
dsh-image-size-guard 是 DeepSeek Harness 插件（npm 包名 dsh-image-size-guard，當前資料中版本 1.2.0，MIT 許可證，要求 Node >=22）。一句話定位：按每個 provider 配置的請求體上限，在超預算前測量真實請求體，批量「退休」最舊的歷史圖片 occurrence，用佔位內容代替，並通過終止當前嘗試、讓 agent 循環重試的方式，使下一次從會話表面重建的請求體真正變小。
插件主要面向 README 描述的 agent2api 網關 16 MiB 請求體限制場景；配置面板支持爲 LLM registry 裏出現的任意 provider 路由名單獨設限與開關。
核心功能¶
超限時做什麼¶
當某次發往已啓用 guard 的 provider 的請求會超過預算時，插件會：
- 測量請求體大小，並使用適配器緩存的 request-image 版本，保證統計的是實際會發送的圖片字節；
- 計算需要替換多少處「最舊的圖片 occurrence」：一次批量退休足夠多，使請求體落在上限以下的目標低水位（結合近期每輪增長估算），並默認保留最近若干輪裏的圖片；
- 以終端失敗結束本次嘗試，由 agent 循環重試；
- 重試從會話表面重建請求，此時 omission 已寫入會話，下一次測量對應更小的 body。
已經能放進預算的請求不會被裁剪，即使當前體積仍高於低水位線。
爲何批量替換，而不是每次只刪一張¶
README 說明：每省略一張舊消息裏的圖都會改寫歷史；provider 的前綴 cache 匹配最長公共前綴，從該圖起往後的 cache 都會失效。若每輪只刪一張，很容易下一輪再次頂到上限，並每輪付出完整 re-prefill。批量退休則在相同總刪除量下，把 cache 失效成本攤到更少次數上。README 在 10 MiB 上限、每輪約 1 MiB 截圖的示例中對比了「最小策略」與批量策略的行爲差異。
決定批量大小的三個主要參數（可在 YAML 與設置頁配置）：
targetTurns（默認5）：一次刪除期望換來多少輪的增長空間；minFillPercent（默認40）：批量後請求體佔預算的最低比例下限；protectedTurns（默認2）：最新若干輪圖片默認不參與批量退休，除非不刪就會超限。
另有 growthWindow（默認 8）用於採樣近期輪次以估計每輪增長。將 targetTurns 設爲 0 會關閉批量策略，回到「最小刪除」行爲。
預算怎麼算¶
實際對照的上限爲 maxRequestBytes - reserveBytes。reserveBytes 用於在 JSON body 估算之外留出餘量，因爲 provider 信封或 HTTP 頭在該 seam 不可見。
兩條執行路徑¶
圖片 omission 會寫成持久的 image/offload 記錄。啓動時插件根據是否掛載 executor 選擇路徑：
| 掛載的 executor | 誰寫記錄 | 結束嘗試時的信號 |
|---|---|---|
@deepseek-ai/dsh-compaction-image-offload |
官方 executor | IMAGE_OFFLOAD_REQUIRED |
| 無 | 本插件自身 | REQUEST_TOO_LARGE |
有官方 executor 時，插件只發出帶 IMAGE_OFFLOAD_REQUIRED 與正數 offloadImages 的 finish chunk，由 executor 寫記錄並返回重試動作；無 executor 時插件自行寫記錄並用 REQUEST_TOO_LARGE 重試。README 強調：信號是 yield 出來的，不是 throw（後文截斷處起仍屬同一設計說明）。
插件 bundle 會向 Harness 注入 Host 行與 Settings 客戶端模塊（dsh.client 平臺爲 web）。
安裝與啓用¶
官方 README 給出的安裝方式如下。資料註明尚未發佈到 npm 時，可用本地 clone 路徑安裝（安裝前請自行審閱源碼與 MIT 許可證；插件以當前 dsh 進程權限運行）。
從 registry 名稱安裝（README 原文）：
dsh plugin --profile web add dsh-image-size-guard
尚未在 npm 上時，從 clone 目錄安裝：
git clone https://github.com/qq744287383/dsh-image-size-guard
dsh plugin --profile web add ./dsh-image-size-guard
bundle 首次安裝後會插入 Host 行與 Settings 頁。首次安裝後需重啓 Harness 一次，以便瀏覽器加載新的 client 模塊。
典型用法¶
圖形設置¶
打開 Settings → Image size guard。頁面按 provider 一行一條，支持增刪改與啓用/禁用。右側開關只保存 enabled 變更，無需重填限額；關閉後該 provider 請求原樣透傳，行會變暗。開關爲 role="switch"，支持鍵盤與讀屏。
各字段按界面單位編輯，保存時寫入精確字節；默認行示例爲 Request limit 16 MiB、Reserve 256 KiB、Placeholder 512 bytes。頁面還會列出 registry 中尚未配置行的 provider，便於一鍵添加。
保存通過 configEditor.edit 寫入 profile patch，由插件自帶 Config 校驗並協調 Loader，無需重啓 Harness 即可生效。面板請求 POST /image-size-guard/limits，經 Host 的 connection.admit 做與其他 API 一致的校驗。
| 字段 | 含義 |
|---|---|
| Provider | Provider 路由名，如 agent2api |
| Request limit (MiB) | 該 provider 允許的最大請求體，可小數（如 10.5） |
| Reserve (KiB) | 上限以下保留的空檔 |
| Placeholder size (bytes) | 每張被省略圖片佔位塊估算佔用字節 |
| Enabled | 是否對該 provider 啓用 guard |
文件配置示例¶
與設置頁等價的 YAML 片段（README 原文）：
- insert:
- id: image-size-guard
name: 'dsh-image-size-guard'
config:
providers:
- provider: agent2api
maxRequestBytes: 16777216
reserveBytes: 262144
placeholderBytes: 512
targetTurns: 5
minFillPercent: 40
protectedTurns: 2
growthWindow: 8
enabled: true
| Key | 默認 | 含義 |
|---|---|---|
providers |
含一行 agent2api |
各 provider 限額行；省略則用默認，顯式空列表表示不 guard 任何 provider |
providers[].provider |
— | Provider 路由名 |
providers[].maxRequestBytes |
16777216（16 MiB） |
網關請求體上限 |
providers[].reserveBytes |
262144（256 KiB） |
上限以下保留字節 |
providers[].placeholderBytes |
512 |
單張佔位塊假設字節 |
providers[].targetTurns |
5 |
一次批量期望支撐的輪數；0 關閉批量 |
providers[].minFillPercent |
40 |
批量後佔預算的最低百分比 |
providers[].protectedTurns |
2 |
最新若干輪圖片受保護；0 不保護 |
providers[].growthWindow |
8 |
估計每輪增長的採樣窗口 |
providers[].enabled |
true |
是否啓用 |
刪除全部行是允許的，表示不對任何 provider 做 guard。
適用場景與注意¶
適合誰： 在 DSH Web profile 下、經 agent2api 等帶嚴格請求體上限的網關做多輪識圖/截圖對話的開發者；需要在不手動清會話的前提下，自動把歷史圖片「 offload」爲佔位文本、避免會話永久 413 的場景。
注意：
- 插件會改寫會話歷史中較舊消息裏的圖片呈現方式；被替換的圖片以佔位文本形式留在上下文中，模型不再看到原圖像字節。
- 批量策略是在「少次 cache 失效」與「一次刪更多舊圖」之間的權衡；若與
@deepseek-ai/dsh-compaction-image-offload同 profile 共存，優先走 executor 統一寫image/offload的路徑。 - DSH 生態強調「一切皆插件」；SkillHub 目錄（https://www.skillhub.cn/plugins/qq744287383/dsh-image-size-guard）是社區索引，與 DeepSeek / 幻方無官方從屬關係。安裝第三方 bundle 前請閱讀倉庫源碼與許可證，並確認與本地 Harness 版本、Node 版本（>=22）匹配。
結尾¶
dsh-image-size-guard 解決的是長對話裏圖片反覆進請求體、最終撞上網關請求體上限後會話無法繼續的問題：測量真實 body、批量省略最舊歷史圖片、借重試讓下一輪請求真正變小，並在參數上控制低水位與 prompt cache 行爲。
- 目錄頁：https://www.skillhub.cn/plugins/qq744287383/dsh-image-size-guard
- 源碼與 README：https://github.com/qq744287383/dsh-image-size-guard
