@dsh-extension/dsh-generation-image

> 为 DeepSeek Harness (DSH) 提供按需图像生成能力。

   

English

这个 DSH 插件让 DeepSeek 会话具备按需图像生成能力：agent 获得一个 generate_image 工具，调用你自己的 OpenAI 兼容图像 URL + API Key （POST /images/generations 或 /images/edits），并把生成的图片送回会话。

• 文生图与图生图 — 可从提示词生成图片，也可通过 OpenAI 兼容

/images/edits 端点编辑或组合一张、多张 DSH 图片附件。

• 自带图像端点 — OpenAI、xiaoyaoapi、vLLM 图像模型、本地网关等兼容服务。
• 图片进入会话界面 — 生成的字节会通过 DSH attachment 服务持久化保存，

并以 assistant 左侧消息的形式放进会话，渲染成可点击的缩略图。点击可放大， 放大后可下载或关闭。

• 文本模型保持安全 — DeepSeek 是纯文本模型，因此每次文本模型请求都会把

image 块改写成文字标记（与 dsh-vision-bridge 相同的机制）； 会话日志与界面仍然保留真实图片。

• 沿用 GPT2Image 验证过的请求形态 — stream: true、partial_images: 1、

SSE image_generation.completed 事件（并兼容普通 JSON 响应），即 GPT2Image 使用的端点（https://api.xiaoyaoapi.cc/v1，模型 gpt-image-2）。

• 同时兼容 b64_json 与 url 结果 — 内联返回图片的渠道（SSE 或普通 JSON 的

b64_json）照常工作；返回远程 url 的渠道（如 data[].url 或 SSE 事件里的 url 字段）会自动下载图片字节后再保存为附件，无需额外配置。

工作原理

agent 调用 generate_image(prompt, size?, quality?, count?, referenceImageIds?)
   │
   ▼
未传 referenceImageIds → POST {baseUrl}/images/generations（JSON）
传入 referenceImageIds → attachments.readImage() → POST {baseUrl}/images/edits
                       （multipart，重复 image[] 字段）
   │
   ▼
SSE（image_generation.partial_image / .completed → b64_json 或 url）
   或普通 JSON（data[].b64_json / data[].url）
   │                        （url 结果会自动下载）
   ▼
magic bytes 识别格式 → attachments.saveImage() → 持久化图片引用
   │
   ▼
工具结果：文字摘要 + image 块，并追加一条 assistant 左侧展示消息
→ 会话中渲染为可点击缩略图
   │
   ▼
点击缩略图 → 内置灯箱放大，含「下载原图」+「关闭」
   │
   ▼
deriveMessages() 把 image 块改写为文字标记（文本模型永不收到 image 块）；
llm.resolveModelInfo 放行补丁让消息能进入 agent。

查看生成的图片

DSH Web 会把每张生成的图片渲染成会话左侧的缩略图（assistant 图片消息）。 点击缩略图即可打开放大的灯箱：

• 下载原图 — 本插件客户端在放大视图右上角注入的下载按钮，把高清原图保存

到本地。它作用于会话里的所有图片灯箱，因此上传的图片和截图同样具备下载能力。

• 关闭 — 内置关闭按钮（以及 Esc / 点击遮罩）。

无需额外配置；只要客户端 bundle 加载（升级插件后刷新一次 DSH 页面）即生效。

安装

从 npm 安装（而非本地检出）：

# 如果你已经有 dsh CLI：
dsh plugin --profile web add @dsh-extension/dsh-generation-image

# 或者你一直用 npx：
npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add @dsh-extension/dsh-generation-image

> --profile 指定你启动的 profile（web 是浏览器 UI profile）。名字不同就 > 改成你自己的 profile。 > > 新增 client bundle 后，重启一次 dsh web 让 UI 生效。

本地开发（与 vision-bridge 一致）

从本地检出把插件 link 进你的 profile，然后重启 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"

或在已运行的实例上使用超级注入器：

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

配置

在 Settings → Generation Image（DSH Web）中配置，或编辑 ~/.dsh/generation-image.json。插件默认不带任何 key/url（均为空）—— 端点 URL 和 API Key 由你自己填（Settings 页、环境变量或配置文件均可）：

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

• baseUrl — OpenAI 兼容图像 API 根地址（.../v1）；默认为空，插件会规范

化并根据工具参数调用 ${baseUrl}/images/generations 或 ${baseUrl}/images/edits。

• apiKey / apiKeyEnv — 默认为空，二者互斥。直接填写的 key 会同步到

DSH 凭据库，并以 DSH_GENERATION_IMAGE_API_KEY 引用。

• model — 图像模型 id（默认 gpt-image-2）。
• size — 默认尺寸提示，默认为空 = 不限制：模型每次调用可传任意尺寸，

或传 "auto" 让 API 自己决定；不会强制任何尺寸。

• quality — 默认质量提示：auto（默认，请求中省略该字段，由 API 决定），

或模型/端点接受的任意值。

• enabled: false 会禁用整条链路：不注册工具、不做图片改写、不启用放行补丁

（恢复原生行为）。

优先级（高者胜）： Settings 页（含 schema 默认值）→ 环境变量 → 配置文件。

环境变量覆盖： 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 工具

• 参数

- prompt（必填）：对要生成图片的详细描述； - size（可选，不限制）：可传端点接受的任意尺寸（如 1024x1024、 1024x1792、1792x1024），或 "auto"/省略让 API 决定； - quality（可选，不限制）：常见值 auto（默认）、low、medium、 high，或端点接受的任意值； - count（可选，1–4）：生成几张图片（默认 1）。 - referenceImageIds（可选）：当前会话中有序且不重复的图片附件 id。文生图时 省略；图生图或组合多张参考图时传入一张或多张，数量受当前 DSH 图片策略限制。

• 行为：调用配置的图像端点 → 解析 SSE 流（或普通 JSON）→ 用 magic

bytes 识别真实格式 → 通过 DSH attachment 服务持久化每张图 → 返回文字摘要 加每张图一个 image 块。

• 结果：生成的图片出现在会话日志与 Web 界面；文本模型收到的是文字标记

而非 image 块。

• 图生图用法：上传一张或多张图片后，直接要求修改、换风格或组合。内置 Skill

会读取图片 marker 中的附件 id 并传入 referenceImageIds；没有参考图片时会先 请用户上传，不会静默退化为文生图。

验证

npm test

测试覆盖：工具注册开关、图像 API 调用（SSE + 普通 JSON）、多参考图 /images/edits multipart 请求、附件隔离、规范化返回值与渲染输出、嵌套 run_code 行为、图片标记改写（会话日志保持不变）、放行 补丁开关、下游工具过滤后的可见性、禁用行为、配置/环境变量优先级。

开发

从本地检出：

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

搜索关键词

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](./LICENSE)