dsh-image-generation

English | 中文

Give your DeepSeek Harness agent a paintbrush. dsh-image-generation is an image-generation plugin for DeepSeek Harness: the agent describes an image in text, a settings-selected generation channel produces it through a pluggable backend, and the file paths are written to disk — all outside the model, so no image-capable model is required.

Why you want it

• DeepSeek can't draw — now it can. The harness model has no image output. This plugin runs the whole "create" outside the model and returns real file paths the agent can hand over (or verify).
• Multi-channel by design. The generate_image tool is decoupled from generation backends. The gpt-image-2 channel ships ready to use; adding Gemini, FLUX, or a local model is one generate() implementation + one registry line — the tool schema never changes.
• Normalized parameters. count, aspect_ratio, and quality are standardized across every channel; channel-specific knobs stay in the per-channel defaults of the settings section.
• Generated, then verified. Images are decoded to disk under generated/ and returned as paths; pair with analyze_image (the dsh-client-vision plugin) for generate-then-inspect workflows.
• Secret-safe. The API key lives in the harness credentials store (GENERATION_OPENAI_API_KEY) — never in settings files, logs, or the conversation transcript.
• Every preset, out of the box. Mounted on the host plane, so code, standard, cordis, minimal — every agent can generate.
• Sensible defaults. Default aspect ratio, quality, count, and output directory are configurable; the tool respects per-call overrides.
• Ready to ship. Prebuilt bundles included; three install paths (drop into the monorepo / pnpm publish / tarball).

Capabilities

Tool

Tool	What it does
generate_image	Generate 1–10 images from a text prompt through the configured channel. Parameters: prompt (required), count, aspect_ratio (1:1…2:3), quality (low/medium/high/auto), output_dir. Returns the written file paths + MIME types.

Settings (generation namespace)

Configured in Settings → Plugins → Plugin configuration → Image Generation:

Field	Meaning
Endpoint (baseUrl)	Domain + optional path prefix; /images/generations is appended. e.g. https://token.uzstudio.com/v1
Channel	The active generation backend (currently gpt-image-2).
Model	gpt-image-2
Output directory	Where images are written; empty uses <cwd>/generated.
Default aspect ratio / quality / count	Used when the tool passes no per-call value.
API key	Stored through the harness credentials service as GENERATION_OPENAI_API_KEY; the literal never leaves your machine.

Multi-channel architecture

model → generate_image(prompt, count?, aspect_ratio?, quality?)
          │  reads generation.channel
          ▼
  channels/<id>/generate()        ← one implementation per backend
          │
  gpt-image-2:  POST {baseUrl}/images/generations   (b64_json / url)
  gemini / flux / local: …       ← add yours here
          │
          ▼
  output.ts → decode + write to disk → {path, mime}[]

Adding a channel is deliberately small:

// src/channels/<id>/index.ts
export async function myGenerate(ctx, call): Promise<GeneratedImage[]> {
  // call.prompt, call.count, call.aspectRatio, call.quality, call.config, call.signal
  return await fetchYourGenerationApi(...)
}

// src/channels/index.ts — one registry line
export const channels = {
  'gpt-image-2': { label: 'GPT Image', generate: gptImageGenerate, maxCount: 10, ... },
  myChannel: { label: 'My Channel', generate: myGenerate },
}

The generate_image tool and its schema never change.

Installation (official — no repo modification)

dsh plugin add installs the packages into your profile; each package declares dsh.bundle, so the rows mount automatically — no patch rows, no repo edits.

Prerequisites

• Official DeepSeek Harness (0.1.0-rc.7 lineage), dsh and pnpm on PATH.

1. Get the packages (pick one)

a. From this repository (recommended until published to npm):

dsh plugin --profile web add \
  file:/path/to/dsh-image-generation/packages/tool-image-generation \
  file:/path/to/dsh-image-generation/packages/ui-image-generation

b. Tarball:

cd packages/tool-image-generation && npm pack
cd packages/ui-image-generation   && npm pack
dsh plugin --profile web add file:/path/to/deepseek-ai-dsh-tool-image-generation-0.1.0-rc.7.tgz \
                            file:/path/to/deepseek-ai-dsh-client-ui-image-generation-0.1.0-rc.7.tgz

c. npm registry (after publishing):

dsh plugin --profile web add @deepseek-ai/dsh-tool-image-generation @deepseek-ai/dsh-client-ui-image-generation

A [WARN] Issues with peer dependencies message is expected and safe to ignore — the peers come from your deployment's own bundles at runtime.

2. Verify

node -e "console.log(JSON.stringify(require(process.env.HOME + '/.dsh/profiles/web/package.json').dsh.profile.bundles))"
# should list dsh-tool-image-generation and dsh-client-ui-image-generation

3. Restart + configure

Restart the harness, then Settings → Plugins → Plugin configuration → Image Generation: set the endpoint, model, defaults, output directory, and your own API key (GENERATION_OPENAI_API_KEY), save.

4. Verify

Ask the agent to "generate an image of a …" — it should call generate_image and return written file paths under generated/.

Uninstall

dsh plugin --profile web remove @deepseek-ai/dsh-tool-image-generation @deepseek-ai/dsh-client-ui-image-generation

Alternative: build inside a harness fork

If you run a fork of deepseek-harness (not the official deployment), you can drop the packages into the monorepo instead:

cp -R packages/tool-image-generation <harness>/packages/vision/tool-image-generation
cp -R packages/ui-image-generation   <harness>/packages/client/ui-image-generation

Then add both to apps/cli/package.json (workspace:^), add ./packages/vision/tool-image-generation to tsconfig.host.json and ./packages/client/ui-image-generation to tsconfig.client.json, pnpm install, build (tsdown host + client passes), and restart.

Parameters

Parameter	Meaning	Default
prompt	Text describing the image to generate (required).	—
count	How many images to generate (1–10).	1
aspect_ratio	1:1 / 4:3 / 3:4 / 16:9 / 9:16 / 3:2 / 2:3 — mapped to OpenAI pixel sizes.	1:1
quality	low / medium / high / auto.	auto
output_dir	Directory for the written files; relative paths resolve against the session workspace.	generated/

Unsupported aspect ratios, qualities, or out-of-range counts fail loudly with a message naming the supported values — the tool never silently substitutes.

Quick start

1. Restart the harness.
2. The tool catalog now includes generate_image.
3. Open Settings → Plugins → Plugin configuration → Image Generation, set the endpoint, model, and your own API key, and save.
4. Ask the agent to "generate an image of a …" — it returns the written file paths.

Development

• This repository is a source distribution: the peer packages (@deepseek-ai/dsh-tools, …) resolve from your deployment. lib/ ships prebuilt, so npm pack works immediately.
• The tsconfig.json files are standalone; the harness monorepo's build pipeline (including the client-bundle tsdown.config.ts) applies in Option A.
• Never commit secrets. The API key stays in each machine's .credentials.yaml.

License

MIT