dsh-media-guard：DeepSeek Harness 圖片優化與智能保留插件

在開發基於 DeepSeek Harness (DSH) 的智能體時，處理多模態請求常遇到圖片 Payload 過大、重複圖片堆積、以及保留策略不清晰的問題。雖然 DSH 0.1.0-rc.8 提供了基礎的附件准入和移除機制，但開發者往往需要更精細的控制，例如在發送前壓縮圖片、按內容去重、優先保留特定圖片，並監控圖片處理狀態。dsh-media-guard 插件正是爲此設計，它在每次代理循環模型調用前，對提供者綁定的圖片視圖進行優化、保留策略執行和可觀測性上報。

插件定位與核心功能¶

dsh-media-guard 是一個爲 DSH 提供圖片優化、智能保留和可觀測性的插件。它運行在 llm/stream 流水線上，僅作用於代理循環構建的請求。插件不會修改持久化的會話日誌和原始附件，而是通過 DSH 的不可變附件存儲添加壓縮後的變體。

核心功能包括：

智能壓縮與去重：在每次模型調用前優化圖片視圖。插件會將過大的圖片壓縮爲 WebP 格式，並根據內容地址（content address）對圖片進行去重。
保留策略：優先保留當前輪次的媒體和用戶媒體，隨後纔是工具媒體。
溢出處理：對於仍然無法放入預算的媒體，插件會將其替換爲確定的“證據筆記”，包含哈希、大小、尺寸、來源和原因，而非編造的描述。
運行模式：默認運行在 protect 模式下。支持配置 observe（僅盤點和報告）和 optimize（壓縮但不外溢）模式。
可觀測性：通過報告 UI 和事件發射，提供圖片處理的監控能力。

安裝與啓用¶

插件通過官方命令安裝。安裝後需重啓配置文件。

dsh plugin --profile <name> add dsh-media-guard

安裝後，插件會自動在 DSH 首頁的狀態條中插入一行 media-guard 狀態。

環境要求：
插件需要 Node.js 版本 ^22.19.0 或 >=24.0.0。

配置說明¶

在配置文件的 cordis.patch.yml 中，通過 id: media-guard 行進行配置。

基礎配置¶

- id: media-guard
  config:
    mode: protect            # observe | optimize | protect
    log: false               # true 打印每一步投影的摘要
    budget:
      maxMediaBlocks: 8
      maxSerializedMediaBytes: 2097152
      maxDecodedMediaBytes: 1572864
      maxSerializedBytesPerImage: 524288
    adapterMaxRequestImageBytes: 20971520 # 鏡像適配器的設置（rc.8 默認爲 20MiB）
    profiles:                  # 針對不同路由覆蓋預算
      my-vision-gateway:
        maxSerializedMediaBytes: 12582912
        maxDecodedMediaBytes: 9437184
        adapterMaxRequestImageBytes: 12582912
    statusPollIntervalMs: 2000 # 狀態刷新間隔

配置項說明¶

mode：
- protect：壓縮圖片，並將溢出媒體外泄（默認）。
- observe：僅盤點並報告圖片狀態。
- optimize：壓縮圖片但不外泄溢出媒體。
budget：全局默認預算限制。maxSerializedMediaBytes 指序列化後的 Base64 字節數上限。
profiles：針對特定路由（provider route）的預算覆蓋。該配置優先級高於頂層 budget。
adapterMaxRequestImageBytes：鏡像對應適配器的請求圖片字節數上限。DSH 0.1.0-rc.8 的官方適配器默認限制爲 20 MiB。此值用於告訴插件當前適配器的安全上限，以便插件在該限制內進行優化，避免雙重清理。
enabled：設爲 false 可完全繞過插件。

注意事項¶

與 DSH rc.8 的關係：DSH 0.1.0-rc.8 已經提供了基礎的附件准入和 offloadRequestImages 功能來限制 Base64 payload。dsh-media-guard 的定位是優化、保留策略和可觀測性層，而非填補安全缺失。
數據完整性：原始附件和持久化會話日誌不會被修改，壓縮後的變體是新增的。
適配器行爲：在 observe 和 optimize 模式下，超預算的圖片會被保留，以便官方適配器（如 Pi AI 或 DeepSeek 適配器）執行其自身的 oldest-first 移除邏輯。只有在 protect 模式下，插件纔會確保最終的圖片選擇符合預算限制。
許可證：MIT 許可證。

該插件爲 DSH 開發者提供了更精細的圖片管理能力，適合需要處理大量圖片、對圖片大小敏感或需要嚴格保留策略的場景。