@dsh-extension/dsh-generation-image

On-demand image generation for DeepSeek Harness (DSH) sessions.

中文文档

A DSH plugin that gives a DeepSeek session on-demand image generation:
the agent gets a generate_image tool that calls your own OpenAI-compatible
image URL + API key (POST /images/generations or /images/edits) and delivers
the generated image into the session.

• Text-to-image and image-to-image — generate from a prompt, or edit and
  combine one or more DSH image attachments through an OpenAI-compatible
  /images/edits endpoint.
• Bring your own image endpoint — OpenAI-compatible image services such as
  OpenAI, xiaoyaoapi, vLLM image models, or local gateways.
• The image lands in the session UI — generated bytes are durably saved as
  DSH attachments, surfaced as an assistant-side image message, and rendered as a
  clickable thumbnail in the conversation. Click it to enlarge, then
  download or close from the enlarged view.
• The text model stays safe — DeepSeek is a text-only model, so image blocks
  are rewritten to text markers for every text-model request (same mechanism as
  dsh-vision-bridge); the session
  log and UI keep the real image.
• Mirrors the proven GPT2Image request shape — stream: true,
  partial_images: 1, SSE image_generation.completed events (with a plain
  JSON fallback), the exact endpoint used by the GPT2Image app
  (https://api.xiaoyaoapi.cc/v1, model gpt-image-2).
• b64_json and url results both supported — channels that return the image
  inline (b64_json, SSE or plain JSON) work as before; channels that return a
  remote url (e.g. data[].url or url-carrying SSE events) are handled
  transparently by downloading the image bytes before saving the attachment.

How it works

agent calls generate_image(prompt, size?, quality?, count?, referenceImageIds?)
   │
   ▼
referenceImageIds omitted → POST {baseUrl}/images/generations (JSON)
referenceImageIds provided → attachments.readImage() → POST {baseUrl}/images/edits
                             (multipart, repeated image[] fields)
   │
   ▼
SSE (image_generation.partial_image / .completed → b64_json or url)
   or plain JSON (data[].b64_json / data[].url)
   │                        (url results are downloaded automatically)
   ▼
magic-byte sniff → attachments.saveImage() → durable image ref
   │
   ▼
tool result: text envelope + image block(s), plus an assistant-side display
message → the conversation renders a clickable thumbnail on the left
   │
   ▼
thumbnail click → built-in lightbox (enlarge) with 下载原图 (download) + close
   │
   ▼
deriveMessages() rewrites image blocks to text markers (text model never
sees image blocks); llm.resolveModelInfo admission bypass lets the messages
enter the agent.

Viewing generated images

The DSH Web UI renders every generated image as a thumbnail in the
conversation (an assistant-side image message). Multiple images in one message
are stacked vertically; click any image to open the enlarged preview:

• 下载原图 — the download button in the top-right of the enlarged preview
  saves the current full-resolution image to disk.
• 关闭 — the close button in the top-right (or clicking the mask).
• 左右切换 — with multiple images, the preview shows n / N and provides
  previous/next buttons on the sides.

No extra configuration is needed; the stacked display and preview controls are
enabled as soon as the plugin's client bundle is loaded (refresh the DSH web
page after upgrading the plugin).

Installation

Install from the npm registry (not a local checkout) — one command:

# if you already have the `dsh` CLI on PATH:
dsh plugin --profile web add @dsh-extension/dsh-generation-image

# or, if you have been using npx all along:
npx @deepseek-ai/[email protected] plugin --profile web add @dsh-extension/dsh-generation-image

The --profile flag targets the profile you boot (web is the browser UI
profile). Omit it or adapt it if your profile has a different name.

After a new client bundle is added, restart dsh web once so the UI picks it up.

Local development (like vision-bridge)

From a local checkout, link it into your profile like the sibling plugins, then
restart dsh web:

// ~/.dsh/profiles/web/package.json  →  dependencies
{
  "@dsh-extension/dsh-generation-image": "link:/path/to/dsh-generation-image"
}
// ~/.dsh/profiles/web/package.json  →  dsh.profile.bundles
"@dsh-extension/dsh-generation-image"

or, for a running instance, use the DSH super-injector:

dsh plugin inject /path/to/dsh-generation-image

Configuration

Configure it in Settings → Generation Image (DSH Web), or edit
~/.dsh/generation-image.json. The plugin ships with empty credentials by
default — you supply your own endpoint URL + API key (via the Settings page,
env vars, or the config file):

{
  "enabled": true,
  "baseUrl": "https://your-image-endpoint.example/v1",
  "apiKey": "sk-xxxx",
  "model": "gpt-image-2",
  "size": "",
  "quality": "auto"
}

• baseUrl — OpenAI-compatible image API root (.../v1); empty by default,
  the plugin normalizes it and calls ${baseUrl}/images/generations or
  ${baseUrl}/images/edits according to the tool arguments.
• apiKey / apiKeyEnv — empty by default, mutually exclusive. A directly
  entered key is synced to the DSH credential store and referenced as
  DSH_GENERATION_IMAGE_API_KEY.
• model — the image model id (default gpt-image-2).
• size — default size hint, empty by default = unrestricted: the model
  passes any size per call, or "auto" to let the API decide. No value is
  hardcoded or restricted.
• quality — default quality hint: auto (default; omitted from the request,
  the API decides) or any value the model/endpoint accepts.
• enabled: false disables the whole chain: no tool registration, no image
  rewriting, no admission bypass (native behavior restored).

Precedence (highest wins): Settings page (with schema defaults) →
environment variables → config file.

Environment overrides: DSH_GENERATION_IMAGE_BASE_URL,
DSH_GENERATION_IMAGE_API_KEY, DSH_GENERATION_IMAGE_API_KEY_ENV,
DSH_GENERATION_IMAGE_MODEL, DSH_GENERATION_IMAGE_SIZE,
DSH_GENERATION_IMAGE_QUALITY, DSH_GENERATION_IMAGE_ENABLED.

generate_image tool

• Arguments
  • prompt (required): a detailed description of the image to generate;
  • size (optional, unrestricted): pass any size the endpoint accepts
    (e.g. 1024x1024, 1024x1792, 1792x1024), or "auto"/omit to let the
    API decide. For true 4K use 3840x2160 or 3840x3840 — the current
    upstream max edge is 3840px; 4096 exceeds the limit and fails. The
    plugin's bundle patch also raises DSH attachment-local limits
    (normalizedImageMaxDimension: 4096, normalizedImageMaxBytes: 26214400)
    so saved 4K images are not compressed down to 2048;
  • quality (optional, unrestricted): common values are auto (default),
    low, medium, high, or any value your endpoint accepts;
  • count (optional, 1–4): how many images to generate (default 1). The
    upstream endpoint currently requires n=1, so the plugin automatically
    splits count > 1 into multiple n=1 requests. The DSH client renders
    multiple images in one assistant message stacked vertically.
  • referenceImageIds (optional): ordered, unique image attachment ids from
    the current conversation. Omit for text-to-image; provide one or more for
    image-to-image editing or combining references. The deployment's DSH image
    count limit applies.
• Behavior: calls the configured image endpoint → parses the SSE stream
  (or plain JSON) → sniffs the real media type from magic bytes → durably saves
  each image through the DSH attachment service → returns a text envelope plus
  one image block per generated image.
• Result: the generated image(s) appear in the session log and Web UI. The
  text model receives a text marker instead of the image block.
• Image-to-image usage: upload one or more images and ask to modify,
  restyle, or combine them. The bundled Skill extracts their attachment ids and
  passes referenceImageIds. If no reference exists, the agent asks for an
  upload instead of silently falling back to text-to-image.

Verify

npm test

The suite covers: tool registration gating, the image-API call (SSE + plain
JSON), multi-reference /images/edits multipart requests, attachment isolation,
canonical value + rendered output, nested run_code behavior,
image-marker rewriting (session log untouched), admission bypass on/off,
tool visibility after downstream filters, disabled behavior, and config/env
precedence.

Development

From a local checkout:

dsh plugin inject /path/to/dsh-generation-image

Search keywords

deepseek · deepseek-harness · dsh · plugin · image generation ·
text-to-image · image-to-image · img2img · generate image · gpt-image · OpenAI-compatible ·
images API · xiaoyaoapi · LLM agent

License

MIT