dsh-image-size-guard
通过将历史记录中最早的图像替换为占位文本，确保模型请求不超过各提供商的请求体上限。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:qq744287383/dsh-image-size-guard#a9614cb618338244e8cf72beb9b02a2acb6d354fImage Size Guard 以 dsh-image-size-guard 发布，当前版本为 1.2.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文
A DeepSeek Harness plugin. It keeps model requests under a gateway's request-body ceiling by replacing the oldest history images with placeholder text — in one batch that lands the body on a low-water mark below the ceiling, so the following turns stay under it without rewriting history again.
Written for the agent2api gateway, whose 16 MiB request-body limit rejects a
conversation once its accumulated images grow past it. At that point the session
can never complete another request, and nothing in the Harness recovers it: the
adapter's own image budget defaults to 20 MiB and never trips, the gateway's 413
arrives as a non-retryable INVALID_REQUEST, and the session is stuck.
Every model request carries the whole history, and every image in that history is re-encoded into every request body. A long conversation therefore grows without bound, and eventually no request fits.
When a request for a guarded provider would exceed the budget, this plugin:
Every omission rewrites an old message, and a provider's prefix cache matches the longest common prefix — so each omission invalidates the cache from that image onward. Retiring exactly one image per turn means hitting the ceiling again on the very next turn and paying a full re-prefill every turn: the cheapest possible deletion is the most expensive possible cache behaviour.
Retiring a batch pays that cost once every few turns instead, for the same total number of images retired. Under a 10 MiB ceiling, eight turns of one 1 MiB screenshot each now retire six images in one go, leaving ~2.7 MiB and about five quiet turns; the minimal policy retired one image, landed on 9.3 MiB, and triggered again immediately.
Three numbers shape the batch:
targetTurns (default 5) — how many turns of growth one deletion should buy.minFillPercent (default 40) — the floor: a batch never drops the body below
this share of the budget, however large the growth estimate looks.protectedTurns (default 2) — the newest turns keep their images; they are
only retired when the request would otherwise exceed the ceiling anyway.A request that already fits is never trimmed, even when it sits above the low-water mark.
dsh plugin --profile web add dsh-image-size-guard
Not on npm yet, so install from a clone instead:
git clone https://github.com/qq744287383/dsh-image-size-guard
dsh plugin --profile web add ./dsh-image-size-guard
The bundle inserts its Host row and its Settings page. Restart the Harness once after the first install so the browser picks up the new client module.
Open Settings → Image size guard. The page lists one row per guarded provider and supports add, edit, remove, and enable/disable.
| Field | Meaning |
|---|---|
| Provider | The provider route name, such as agent2api. |
| Request limit (MiB) | The largest request body that provider accepts. Decimals are allowed (10.5). |
| Reserve (KiB) | Headroom kept free below the limit. |
| Placeholder size (bytes) | Bytes one omitted image is estimated to occupy. |
| Enabled | Whether the guard acts on this provider. |
Each row carries a switch on the right. Flipping it saves the row with only
enabled changed, so the limit never has to be retyped, and a disabled row stops
guarding immediately — its requests pass through untouched. The row also dims, so
a switched-off provider reads as off at a glance. The switch is a real
role="switch" button, so it answers to Enter and Space and reports its state to
screen readers.
Each size is edited in the unit its field names, so a value never has to be converted by hand: the default row reads 16 / 256 / 512. The stored values stay exact bytes; the panel converts on open and on save.
The page also offers the providers the LLM registry advertises that no row covers yet, so a new provider is one click away instead of a typed guess.
Saving writes the profile patch layer through configEditor.edit, which validates
with this plugin's own Config and reconciles the Loader. The guard and the panel
therefore read one source of truth, and a save takes effect without restarting the
Harness. Removing the last row is allowed: it means no provider is guarded.
The panel talks to POST /image-size-guard/limits. The Host admits each request
through connection.admit, so it carries the same Host/Origin checks and browser
session as the rest of the API.
The panel edits this row; the YAML below is the same value in file form.
- 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 | Default | Meaning |
|---|---|---|
providers | one agent2api row | Provider limit rows. Omit the field for that default; an explicit empty list guards nothing. |
providers[].provider | — | Provider route name. |
providers[].maxRequestBytes | 16777216 (16 MiB) | The gateway's request-body ceiling. |
providers[].reserveBytes | 262144 (256 KiB) | Headroom kept free below the ceiling. |
providers[].placeholderBytes | 512 | Bytes assumed for one placeholder block. |
providers[].targetTurns | 5 | Turns of growth one batch should buy below the ceiling. 0 disables batching and restores the minimal policy. |
providers[].minFillPercent | 40 | Lowest share of the budget, in percent, a batch may leave behind. |
providers[].protectedTurns | 2 | Newest turns whose images a batch leaves alone. 0 protects nothing. |
providers[].growthWindow | 8 | Turns sampled to estimate per-turn growth. |
providers[].enabled | true | Whether the guard acts on this provider. |
The budget a request is measured against is maxRequestBytes - reserveBytes. The
reserve exists because the estimate models the JSON body, not the provider
envelope or HTTP headers, which are invisible at this seam.
The omission is a durable image/offload record. Two implementations can exist,
and the plugin picks one at startup:
| Mounted executor | Who writes the record | Signal the attempt ends with |
|---|---|---|
@deepseek-ai/dsh-compaction-image-offload | the shipped executor | IMAGE_OFFLOAD_REQUIRED |
| none | this plugin | REQUEST_TOO_LARGE |
The shipped executor already listens for IMAGE_OFFLOAD_REQUIRED, so when it is
present the plugin only asks: it yields a finish chunk carrying that code and a
positive offloadImages count, and the executor writes the record and returns the
retry action. That keeps one implementation of the selection and its projection,
and follows the harness when its format changes.
When the executor is absent, the plugin falls back to its own record writer and
its own REQUEST_TOO_LARGE retry, so a profile without that bundle still works.
The presence test is the registered image/offload projection, which the executor
contributes on mount.
The signal is yielded, not thrown. A thrown error from an llm/stream
listener propagates out of llm.stream() and the agent loop re-throws it before
the agent/request-error waterfall runs, so the executor would never see it. A
finish chunk with an error reason does reach that waterfall; the adapter
produces the same chunk by turning a thrown IMAGE_OFFLOAD_REQUIRED into it.
The selection is recorded as the Session's own image/offload event, so it
survives resume, fork, and compaction, and it is visible to the token meter and
the GUI. The placeholder text the model sees is the adapter's standard "image
omitted" handle, which names the attachment and its recovery path.
The plugin contributes the image/offload projection only when the shipped bundle
has not already registered it; its definition is byte-compatible with that
package's, so the two can coexist and a session log written by either restores
under both.
system, messages, and tools. Adapter-specific fields
outside that set are covered by the reserve, not measured.dsh plugin --profile web remove dsh-image-size-guard
Session logs that already contain image/offload events keep replaying: the
shipped @deepseek-ai/dsh-compaction-image-offload bundle owns that projection,
and a profile without it falls back to this plugin only while the plugin is
installed. If you remove the plugin from a profile that has neither, restore the
bundle before resuming those sessions.
No build step and no dependencies: plain ESM on the Host, a plain browser module on the Client.
for test in test/*.test.mjs; do node "$test"; done
estimate — request measurement, growth-based low-water sizing, and the batch decision.config — the limit schema, defaults, and every rejection.offload — the durable image/offload projection and selection order.plugin — the guard's wiring: pass-through, omission, retry, failure paths.deference — both execution paths: ask the shipped executor, or do it alone.rpc — the panel endpoint: admission, methods, list/save/remove, rejections.mount — the endpoint mounts even when its carrier services arrive late.save-path — that a saved row survives the Loader's own validation.client — the browser bundle's exports and slot registration.client.render — the panel's real element tree, text, and form behavior.switch — clicking a row's switch asks the Host for the inverted state.toggle — that toggle round-trips through the Host and persists.Layout:
lib/index.js the guard: measurement, signal, retry wiring
lib/estimate.js request-body measurement, growth sizing, and the batch decision
lib/config.js limit schema, defaults, budget arithmetic
lib/offload.js the image/offload projection and selection (fallback path)
lib/rpc.js the Settings panel endpoint
client/client.js the Settings page
locale/{en,zh}.json
MIT