dsh-image2-draw

一句话定位

在 DeepSeek Harness 中接入第三方 OpenAI Images 兼容中转服务，调用 gpt-image-2 完成文生图和图生图。配置只需 API Key 与接口地址两个字段，结果直接在聊天内显示并保存到本地。

核心能力

• 在 设置 > 插件 > 插件配置 中提供独立的「Image2 生图」配置卡片，集中管理 API Key、接口地址、模型、图生图端点与超时
• 提供 image2-generate 工具，支持一次按顺序生成 1~8 张图片，提示词含「竖版/横版/方图」等方向词时自动选择尺寸
• 提供 image2-edit 工具，基于 1~8 张 PNG/JPEG/WebP 参考图进行修改或重绘
• 生成图片以内置工具卡片显示，支持缩略图、点击放大、另存为，文件同时落到会话工作目录 outputs/image2/ 并自动编号不覆盖
• API Key 仅写入凭据存储（不回显），并对配置写入、响应大小、超时、参考图大小进行校验，避免上游 524/超时造成的重复计费

技术实现

• 语言: JavaScript（Node ESM 模块；宿主 lib/index.js 与客户端 lib/client.js 均为 JS，无 TypeScript）
• 关键依赖: @deepseek-ai/dsh-tools、@deepseek-ai/dsh-settings、@deepseek-ai/dsh-credentials、@deepseek-ai/dsh-attachment、@deepseek-ai/schemastery
• 架构模式: 双端插件。宿主半通过 installSettingsSection 注册命名空间 image2-draw 并用 ctx.tools.register 注册两个生图工具；客户端半通过 settings.plugin.item 槽位挂载配置卡片，通过 tool.call.toolview 槽位注入结果卡片。配置读写走插件自有 /image2-draw/{state,mutate,attachment} HTTP 路由，密钥走官方 credentials RPC
• 入口文件: lib/index.js（宿主）+ lib/client.js（客户端），由 cordis.patch.yml 通过 dsh.bundle.patch 自动注入 Web profile

适用场景

希望用 DeepSeek Harness 配合第三方中转服务生成图片的用户，特别是日常需要做海报、封面、参考图重绘，但官方默认未提供文生图/图生图能力时。配置只需要一个接口地址和一个密钥，不要求绑定特定服务商，也不需要复杂的环境变量。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:JuneLearn/dsh-image2-draw

配置项

常见问题

Q: 安装后需要做什么配置？

A: 打开「设置 > 插件 > 插件配置 > Image2 生图」卡片，填入第三方中转的 API Key 与接口地址（形如 https://example.com/v1），点击保存并等待界面显示「已保存」后即可在对话中使用。

Q: 生成图片保存在哪里？

A: 同时保存两处：聊天内的专用工具卡片（支持点击放大和另存为）以及当前会话工作目录的 outputs/image2/。文件命名为 image2-时间戳[-序号].png，重名会自动加序号，不会覆盖已有文件。

Q: 为什么 HTTP 524 或超时直接失败而不自动重试？

A: 插件故意不对 524 和超时做自动重试，因为上游中转可能已经生成了图片并完成计费，自动重试会产生重复费用。遇到这类错误请确认后再决定是否手动重试。

Q: 支持 macOS、Windows 和 Linux 吗？

A: 支持。本插件没有原生模块依赖，也没有操作系统限制，只要 Node.js 能跑起来就能用。

Q: API Key 是否安全？

A: API Key 只写入 DSH 的凭据存储（默认引用名为 IMAGE2_API_KEY），不在表单回显，也不会被插件状态接口返回；普通设置文档不会包含密钥。

Q: 与官方原生生图能力的关系是什么？

A: 互不影响。本插件基于通用 OpenAI Images 兼容协议工作，不绑定特定中转服务商；模型名、图生图端点、自定义尺寸与质量档位的支持程度取决于所选服务商。

Q: 如何升级和卸载？

A: 升级直接重新执行安装命令即可，DSH 会自动覆盖。卸载执行 dsh plugin --profile web remove dsh-image2-draw 并重启 dsh web，配置卡片与生图工具会一并移除。

Q: 大图或超时会自动缩放吗？

A: 不会。图生图单张参考图超过 4MB 或总计超过 32MB 会直接拒绝；参考图仅接受 PNG、JPEG、WebP（按文件魔数识别，不信任扩展名）；远程下载返回图上限 32MB。请在调用前自行压缩图片。

上手难度

入门 — 配置仅需一个 API Key 与一个接口地址，其余使用默认即可；首次安装后只需进入「设置 > 插件 > 插件配置」完成保存即可在对话中调用。

已知问题与限制

• 对 524 与超时不做自动重试，原因是上游可能已经生成了图片，重试会导致重复计费
• 文生图按 count 顺序逐张请求（每次 n=1），不并发；批量生成较慢
• 图生图 Node 端不自动缩放参考图，单张超过 4MB 或总计超过 32MB 直接报错
• 远程图片下载上限 32MB，超过会中断
• API 响应 JSON 上限 48MB，错误响应上限 64KB，超出会被拒绝
• 仅接受 PNG、JPEG、WebP 三种格式（用魔数识别），其他格式直接报错
• 工具结果不会把图片附件注入到 DeepSeek 模型上下文，避免不支持视觉输入的模型读到原始图片
• 模型名、图生图端点、自定义尺寸、质量档位的支持取决于中转服务商实现，遇到 HTTP 400/404 需要核对服务商文档

Unable to generate images directly in DeepSeek Harness? This plugin adds Image2 generation through a third-party relay that exposes an OpenAI Images-compatible API. Configure only a baseURL and an API Key, then use gpt-image-2 for text-to-image and image-to-image tasks in chat.

中文说明

Third-party service recommendation (referral link)

If you are looking for an OpenAI-compatible API relay, you can take a look at WPIronman API. This is my referral link, and I may receive a referral benefit if you register through it; any promotion or benefit is subject to the provider's current terms. This plugin is independent of that service and does not require any particular relay. Evaluate pricing, reliability, and privacy terms before choosing a provider.

New users can redeem the gift quota with code 99F509ABC6C38F77.

Related project

Need independent reasoning-effort controls for third-party models in DeepSeek Harness? See my other plugin: DSH Reasoning Settings. It configures reasoning levels, provider defaults, and API wire values for custom providers and models.

Features

• Adds an Image2 Draw card under Settings > Plugins > Configurable plugins.
• Requires only a baseURL and an API Key; the default model is gpt-image-2.
• Accepts a short base URL such as https://example.com/v1 and appends /images/generations automatically.
• Derives the image-edit endpoint as /images/edits, with an optional explicit editURL override.
• Provides image2-generate for 1-8 sequential text-to-image generations.
• Provides image2-edit with 1-8 PNG, JPEG, or WebP reference images.
• Supports adaptive portrait, landscape, and square sizes as well as validated custom dimensions.
• Displays generated images directly in the conversation with a dedicated tool card for thumbnails, zoom, and Save As actions.
• Resolves image attachments in the client card without injecting image content into DeepSeek model context that does not support vision input.
• Also saves images under outputs/image2/ in the current session working directory and numbers duplicate names instead of overwriting files.
• Stores API keys only in DSH credentials. Keys never enter the regular settings document and are never returned by the plugin state endpoint.
• Validates settings writes, response sizes, timeouts, and input images. HTTP 524 and timeout failures are not retried automatically, preventing duplicate charges when the upstream service has already generated an image.

Live demo

In-conversation result

Plugin settings

Installation

Prerequisites

• Install Node.js. DSH currently supports Node.js 22.19.x or version 24 and newer; Node.js 24 LTS is recommended. Node.js includes npm and npx.
• Install Git so the plugin can be fetched from GitHub.
• Install pnpm. Both methods require pnpm because dsh plugin invokes it in the profile directory to install or remove plugins.
• Your network must reach registry.npmjs.org and github.com. Configure a working network proxy if npm or GitHub is unavailable or unstable.
• Method 1 does not require a DeepSeek Harness source checkout. Method 2 additionally requires that checkout.

Check the basic environment first:

node --version
npx --version
git --version
corepack enable
pnpm --version

If corepack enable fails with a permission error, run it once from an Administrator PowerShell. Alternatively, use another option from the pnpm installation guide.

If downloads remain on a spinner or fail with ECONNRESET, ETIMEDOUT, or a GitHub connection error, set a proxy for the current PowerShell window. Port 7890 is only an example; replace it with your proxy's actual port:

$proxy = "http://127.0.0.1:7890"
$env:HTTP_PROXY = $proxy
$env:HTTPS_PROXY = $proxy
$env:npm_config_proxy = $proxy
$env:npm_config_https_proxy = $proxy

These variables only affect the current PowerShell window and disappear when it is closed.

Method 1: npx (recommended for regular users)

This method does not require a DeepSeek Harness source checkout or a global dsh installation, but Git and pnpm must already be available. On its first run, npx downloads @deepseek-ai/dsh and its dependencies, which can take several minutes:

npx --yes -p @deepseek-ai/dsh dsh plugin --profile web add github:JuneLearn/dsh-image2-draw

Start Web through the same package runner after installation:

npx --yes -p @deepseek-ai/dsh dsh web

Method 2: pnpm with the Harness source tree (recommended for developers)

Use this method if you already cloned deepseek-harness and want to run its source directly. First confirm pnpm is available:

pnpm --version

Enter the DeepSeek Harness source root. Install its dependencies once, then install the plugin:

cd D:\deepseek-harness
pnpm install
pnpm dsh plugin --profile web add github:JuneLearn/dsh-image2-draw

Start Web from that source directory afterward:

cd D:\deepseek-harness
pnpm dsh web

The package's dsh.bundle declaration adds the plugin to the Web profile automatically. Neither method requires editing cordis.patch.yml. Web listens on http://127.0.0.1:3080 by default; it uses another port only when the default is occupied or you explicitly select one.

Upgrade

Run the corresponding install command again to upgrade. No uninstall or profile-patch maintenance is required.

npx method:

npx --yes -p @deepseek-ai/dsh dsh plugin --profile web add github:JuneLearn/dsh-image2-draw

pnpm source method:

cd D:\deepseek-harness
pnpm dsh plugin --profile web add github:JuneLearn/dsh-image2-draw

Uninstall

npx method:

npx --yes -p @deepseek-ai/dsh dsh plugin --profile web remove dsh-image2-draw

pnpm source method:

cd D:\deepseek-harness
pnpm dsh plugin --profile web remove dsh-image2-draw

DSH removes both the dependency and its bundle layer. Restart dsh web; the Image2 Draw card and image-generation tools are removed.

Usage

1. Open Settings > Plugins > Configurable plugins > Image2 Draw.
2. Enter the API key supplied by your relay.
3. Enter the relay endpoint, for example https://example.com/v1.
4. Adjust the model, edit endpoint, or timeout if needed; the defaults normally work without changes.
5. Click Save and wait for the Saved status.
6. Start a new session and ask the model to call image2-generate, or provide reference image paths and use image2-edit.

Example prompts:

Call image2-generate to create a portrait cinematic poster of a future city at high quality.

Call image2-edit with D:\images\room.png and restyle the room with light Japanese wood while preserving the layout.

Support for gpt-image-2, image editing, custom dimensions, and quality levels depends on the relay implementation. If the API returns HTTP 400 or 404, check the provider's model name and Images endpoint documentation.

Image and request limits

• Text-to-image accepts a count from 1 to 8 and sends one upstream request at a time.
• Image editing accepts 1-8 reference images, up to 4MB each and 32MB total.
• Reference images must be PNG, JPEG, or WebP. Their format is detected from magic bytes rather than trusted filename extensions.
• Relative reference paths resolve from the current session working directory.
• The default timeout is 180 seconds and the configurable range is 1-3600 seconds.
• Generated results must be PNG, JPEG, or WebP. Remote image downloads are limited to 32MB.

Development

npm install
npm test

Compatibility

Built against the public dual-end plugin, settings namespace, credentials, tool registration, client slot, and WebServer lifecycle interfaces of DeepSeek Harness 0.1.0-rc.6. Harness is still in Developer Preview; if the plugin stops loading after an upgrade, check these interfaces and the dsh.client.inject declaration.

Acknowledgements

Parts of the in-conversation attachment and dedicated tool-card implementation were adapted from the MIT-licensed dsh-multimodal. See THIRD_PARTY_NOTICES.md for the complete third-party copyright and license notice.

License

MIT