在开发基于 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 开发者提供了更精细的图片管理能力，适合需要处理大量图片、对图片大小敏感或需要严格保留策略的场景。