前言¶

在 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

dsh-image-size-guard: Preserving Historical Images in Long Conversations Within Gateway Request Body Limits

前言¶

这是什么¶

核心功能¶

超限时做什么¶

为何批量替换，而不是每次只删一张¶

预算怎么算¶

两条执行路径¶

安装与启用¶

典型用法¶

图形设置¶

文件配置示例¶

适用场景与注意¶

结尾¶

精选优惠券

dsh-image-size-guard: Preserving Historical Images in Long Conversations Within Gateway Request Body Limits

前言¶

这是什么¶

核心功能¶

超限时做什么¶

为何批量替换，而不是每次只删一张¶

预算怎么算¶

两条执行路径¶

安装与启用¶

典型用法¶

图形设置¶

文件配置示例¶

适用场景与注意¶

结尾¶

精选优惠券

Related Articles