dsh-image-guard：DeepSeek Harness 圖片預算管理插件

DeepSeek Harness (DSH) 的理念是“一切皆插件”。在多模態會話中，客戶端通常按字節或像素計算圖片預算，而上游模型（如 vLLM）往往按張數限制輸入（--limit-mm-per-prompt.image）。字節預算無法阻止因圖片過多導致的 400 錯誤，且 DSH 的 compact 壓縮會重發相同的歷史記錄，導致重複失敗。dsh-image-guard 旨在解決這一問題。

核心功能¶

該插件運行在 DSH 的 fetch 鏈路首層，主要處理“請求發送前”和“錯誤重試”兩個階段。

保留最新 N 張，其餘替換爲標記：插件會保留最新的 keepRecent 張圖片，其餘圖片被替換爲可識別的標記（包含文件名、路徑或指紋）。被裁剪的圖片不會無聲丟失，模型或 agent 需要時可再次獲取。
解析上游上限：當上遊因圖片數量返回 HTTP 400 時，插件會從錯誤消息 At most N image(s) 中解析上限 N，並按 N−1 張重試；解析到上限後，同進程內後續請求將直接按 N−1 張發送，不再觸發 400。
節省視覺 token：每張被裁剪的圖片淨省約 930 token（實測上限 972 − 標記開銷約 40）。設置頁實時顯示累計節省量。
不修改會話歷史：僅修改即將發出的請求體（使用 structuredClone 的副本），前綴緩存保持有效，關閉插件即恢復原有行爲。
始終保持在 fetch 鏈首：插件攔截 globalThis.fetch 的賦值，配合 200ms 看門狗與鏈上探針兜底，確保它始終位於 dsh-net-proxy 之前，避免代理模式下的繞過問題。

安裝與啓用¶

本插件目前尚未發佈到 npm，也未被任何插件市場目錄收錄，無法在 DSH Desktop 的 GUI 插件市場中搜索到。需手動安裝。

命令行 profile¶

dsh plugin --profile <name> add github:mafeis/dsh-image-guard

注意：desktop profile 由 Electron 持有，啓動器拒絕對其執行插件管理請求。

DSH Desktop 手動安裝¶

DSH Desktop 加載名爲 desktop 的 profile，位於 ~/.dsh/profiles/desktop/。需手動編輯 manifest 並安裝依賴。

編輯 ~/.dsh/profiles/desktop/package.json，在 dependencies 中加入：

    "dsh-image-guard": "github:mafeis/dsh-image-guard"

在同一文件的 dsh.profile.bundles 數組中追加 "dsh-image-guard"（該字段不存在則在 dsh 字段下新建）：

    "dsh": {
      "profile": {
        "bundles": ["dsh-image-guard"]
      }
    }

安裝依賴後重啓 DSH Desktop：

    cd ~/.dsh/profiles/desktop && pnpm install --prefer-offline --ignore-scripts

配置與調試¶

配置文件位於 ~/.dsh/image-guard.json，修改後支持熱更新，也可在設置頁或通過 /_dsh/image-guard 路由修改。

常用配置項¶

字段	默認值	說明
`enabled`	`true`	總開關，關閉後完全透傳
`keepRecent`	`12`	保留最新的圖片張數，其餘替換爲標記
`maxRetries`	`3`	400 後的降級重試次數
`learnLimit`	`true`	是否從 400 響應中解析上游上限
`dryRun`	`false`	僅觀察，不修改任何請求
`markerLang`	空	標記語言，留空跟隨宿主界面語言，`zh` / `en` 爲固定值
`placeholder`	空	標記模板，留空則使用生效語言的默認模板
`pathMode`	`basename`	`full` / `relative` / `basename` / `none`，決定路徑顯示方式
`tokensPerImage`	`972`	估算節省量所用的單張圖片視覺 token 數
`verbose`	`true`	是否輸出日誌

調試步驟¶

先觀察再啓用：在設置頁打開 dryRun，此時僅記錄將被裁剪的圖片，不修改任何請求。
檢查鏈路接入：設置 → 圖片守衛 → 診斷。應顯示守衛已接入 fetch 鏈，且鏈上探針計數持續增加。
查看狀態：~/.dsh/image-guard-status.json 中的 chatPosts 開始增長。

標記機制¶

被裁剪的圖片會被替換爲標記。根據圖片來源不同，標記內容不同：

有路徑（默認）：[圖片已省略 #1 · 01-race-start.png · 需要時按文件名在工作區內搜索後讀取]
僅有附件元數據：[圖片已省略 #1 · 01-race-start.png · 內聯圖片 sha256:bf23bcd3 (image/png 1280x720 618 KiB) · 無原文件路徑，已無法取回]
遠端 URL：[圖片已省略 #1 · race.png · https://…/race.png · 需要時可重新訪問該地址]

已知限制¶

僅控制張數：不壓縮、不縮放圖片；字節預算不在處理範圍。
首次 400：上限只能從 400 響應中獲知，首次請求仍會出現一次 400。
僅針對歷史圖片：最新 N 張按原樣發送（含字節）。
內聯圖片無法恢復：已內聯且無路徑的圖片無法取回，標記會明確說明。
依賴當前形態：依賴 DSH 當前的請求形態，形態不匹配的請求會透傳。

結語¶

dsh-image-guard 通過攔截請求鏈路，解決了 DSH 客戶端按字節預算而上游按張數限制導致的多模態會話中斷問題。通過解析錯誤並動態調整圖片數量，實現了會話的連續性。

目錄頁：dsh-image-guard
GitHub：mafeis/dsh-image-guard