dsh-imagegen

一句话定位

为 DSH Web GUI 增加一个 AI 生图侧边栏，通过本机宿主代理调用 OpenAI 兼容的图像生成接口，提供文生图、图生图、生成历史和提示词模板库，所有请求与密钥都走本地、不暴露给浏览器。

核心能力

• 在 DSH Web GUI 侧栏提供「AI 生图」入口，呈现三栏工作台（参数、生成结果、历史）
• 支持文生图（输入提示词）与图生图（上传参考图修改），对接 /images/generations 和 /images/edits 端点
• 可调节尺寸、清晰度（low/medium/high）、生成数量（1-4 张）与透传 detail 参数
• 生成结果自动保存到本地历史（最多 50 条），支持查看、恢复参数、删除单条、清空全部
• 内置 441 个 gpt-image-2 提示词模板案例，支持搜索、分类筛选、复制提示词、一键回填到生图输入框
• 提供在线更新检查：发现 GitHub 新版本时在工作台顶部显示更新按钮

技术实现

• 语言: TypeScript + React 18
• 关键依赖: @deepseek-ai/dsh-client-ui-primitives（系统 UI 组件）、@deepseek-ai/dsh-settings（设置面板宿主）、@deepseek-ai/dsh-host-webserver（路由注册）、@deepseek-ai/dsh-system-prompt（系统提示词播报）
• 架构模式: 双端架构——宿主端（src/index.ts）注册 cordis 插件、挂载 API 路由、注册系统提示词章节；客户端（src/client/）通过 dynamically attached React 节点挂载侧栏面板与设置卡片，通过 /api/dsh-imagegen/* 同源路由与宿主通信
• 入口文件: src/index.ts（宿主端）、src/client/index.ts（客户端）

适用场景

适合已经在 DSH Web GUI 里日常工作的 Agent 用户，希望直接在 IDE 侧栏里把模型生成或参考图喂给 gpt-image-2，省去切换到 Web 控制台的步骤；也适合需要为 Agent 提供「会画图」能力的开发者，开启"向 Agent 播报"后，Agent 在系统提示词里就能调用该面板。

前置依赖与兼容性

安装方式

dsh plugin --profile web add @dickpy/dsh-imagegen

配置项

常见问题

Q: 安装后在哪里打开生图功能？

A: 装完重启 dsh web，左侧栏会出现「AI 生图」入口。第一次使用前需要打开「设置 → 插件 → 可配置」，展开「AI 生图」卡片，填入 API 地址和密钥，点保存。

Q: 必须使用 OpenAI 官方接口吗？

A: 不必。插件对接所有 OpenAI 兼容的 /images/generations（文生图）与 /images/edits（图生图）端点；只要你的服务提供这两个接口、并在响应里返回 data[].b64_json 或 data[].url，就能用。

Q: 生成请求需要带图片上传还是仅文本？

A: 两种都支持。文生图只需提示词；图生图需要在面板里拖入或选择一张参考图（PNG/JPG/WEBP/GIF），单张上限 10MB，超出会被前端拦截。

Q: 历史记录存放在哪里？

A: 全部保存在本机。图片落到 ~/.dsh/dsh-imagegen/images/，索引文件是 ~/.dsh/dsh-imagegen/index.json，最多保留 50 条，最早的会被自动淘汰。连接同一 DSH 实例的不同浏览器/设备共享同一份历史。

Q: 提示词模板库需要联网吗？

A: 模板案例列表（约 441 条）随插件一起打包，无需联网即可看到；每个案例的参考图按需从 vibeui.top 镜像拉取并缓存到 ~/.dsh/dsh-imagegen/template-images/，二次浏览不需联网，首次加载需要访问该站点。

Q: 插件会自动更新吗？

A: 不会自动更新。每次进入工作台会调用 GitHub Releases 接口检查最新稳定版本（结果缓存 15 分钟），发现新版本时面板顶部出现更新按钮；点击后由宿主进程执行 dsh plugin ... add @dickpy/dsh-imagegen@<version>，装完必须重启 dsh web 才能生效。

Q: 卸载后历史和缓存会一起清掉吗？

A: 不会。卸载插件后 ~/.dsh/dsh-imagegen/ 目录下的历史图片与模板图片缓存都保留在磁盘上，需要手动删除。

Q: 报错"上游接口响应超时（240 秒）"怎么办？

A: 图片生成是慢操作，上游返回超过 240 秒会被插件判定为超时（这是 240 秒上限）。建议先确认网络通畅，再尝试一次；如果上游限流或排队严重，等几分钟再试。

上手难度

入门 — 接口是标准 OpenAI 兼容协议，配置只需填两项（API 地址、密钥），日常工作台界面沿用 DSH 自己的 UI 规范，无需额外学习成本。

已知问题与限制

• 生成单图请求的超时为 240 秒，下载结果 URL 的超时为 60 秒；上游响应极慢时会被直接判定为失败
• 上游单接口一次只能返回 1 张图；需要 4 张结果时，插件会发 4 个并行请求，若上游限流可能部分失败
• detail 字段是透传参数，部分 gpt-image-2 网关支持；官方 OpenAI 端点若拒绝未知字段，请保持界面默认的"自动"（不发送）
• 历史最多保留 50 条，超出后最早的条目（含图片文件）会被自动删除
• 模板参考图单张上限 20MB；超过会被忽略
• 在线更新检查每次进入工作台仅触发一次，结果缓存 15 分钟；GitHub 抽风时插件会静默忽略，不会阻塞使用
• 路由层强制要求请求来自本机回环（loopback），同源 Origin，跨站请求会被 403 拒绝

DeepSeek Harness (DSH) Web GUI 的 AI 生图插件。它通过宿主进程安全地代理 OpenAI 兼容的图像生成接口，为 DSH 提供文生图、图生图编辑、生成历史、提示词模板库和一体化设置页。

默认模型为 gpt-image-2，也兼容提供 /images/generations 和 /images/edits 的 OpenAI 兼容端点。

效果预览

AI 生图工作台

三栏工作台将参数、生成结果和历史记录放在同一视图中；生成的图片可预览、下载，并从历史记录恢复参数。

四图结果布局

单图结果布局

提示词模板库

模板库提供 441 个 gpt-image-2 案例的展示图、分类筛选和完整提示词；打开详情后可以复制提示词，或一键回填到生图输入框。

独立配置卡片

在 DSH 的“设置 -> 插件 -> 可配置”中填写 API 地址和密钥。密钥只保存在宿主侧设置文件，浏览器端不会获取明文。

功能

• 文生图与图生图：输入提示词生成图片，或上传 PNG、JPG、WEBP 参考图进行编辑。
• 可调生成参数：尺寸、清晰度、生成数量和细节等级均可在界面中选择；未指定的参数保持自动。
• 结果操作：结果区固定为四分格：单图铺满，双图占上排，三图占三格，四图为 2×2；支持下载、全屏预览、可滚动缩放、前后切换、复制优化提示词，以及一键将当前图片添加到图生图。
• 持久化历史：保存提示词、参数和图片；支持查看、恢复、单条删除和清空，最多保留 50 条。
• 跨设备查看：历史保存在 DSH 宿主侧，连接同一 DSH 的浏览器或设备共享同一份记录。
• 提示词模板库：提示词框左下角可打开模板库，浏览 441 个 gpt-image-2 案例的展示图；支持搜索、分类筛选、查看完整提示词、复制，以及一键将模板回填到生图输入框。参考图通过宿主同源代理按需加载并缓存，也可手动缓存全部图片供离线浏览。
• 原生 DSH 体验：侧栏入口、主题适配和设置卡片均遵循 DSH Web GUI 的 UI 规范。
• 在线更新：插件会检查 GitHub Releases，发现新版本时在工作台显示在线更新按钮；安装完成后重启 DSH 即可加载新版本。

快速开始

前置条件：已安装 DSH（npm i -g @deepseek-ai/dsh）与 pnpm。 装完统一重启 dsh web，侧边栏即出现「AI 生图」入口，再到「设置 → 插件 → 可配置」填写 API 地址与密钥。

方式一：让 AI 帮你安装（最省事）

把下面提示词直接粘贴给 DSH（或 Codex / 其他 coding agent）执行即可：

用 dsh plugin --profile web add @dickpy/dsh-imagegen 安装 AI 生图插件（profile 名按实际修改），完成后重启 dsh web。

方式二：npm 安装（推荐）

dsh plugin --profile web add @dickpy/dsh-imagegen

dsh 会自动把插件注册进 profile 的 bundle 清单（无需手动改 cordis.patch.yml），重启 dsh web 即可。

方式三：聚合包（tarball）安装

从 GitHub Releases 下载发布产物 （如 dickpy-dsh-imagegen-1.0.9.tgz），然后：

dsh plugin --profile web add <下载路径>/dickpy-dsh-imagegen-1.0.9.tgz

重启 dsh web。

方式四：源码开发启动（最后的选择）

需要改插件源码时才用这种方式：

git clone https://github.com/dickpy/dsh-imagegen.git
cd dsh-imagegen
pnpm install
pnpm run build
dsh plugin --profile web add link:/绝对路径/dsh-imagegen

重启 dsh web；开发时可运行 pnpm run watch 持续构建，bundle 变更由 client-hmr 自动热更。

配置 API

打开 DSH 的“设置 -> 插件 -> 可配置”，展开 AI 生图 (dsh-imagegen)：

配置完成后，从 DSH 侧栏打开“AI 生图”即可开始使用。

接口兼容性

detail 是透传参数，部分 gpt-image-2 网关支持。官方 OpenAI 端点若不接受该字段，请保持界面中的“自动”。

数据与安全

• API 请求由 DSH 宿主进程代理，浏览器不直接连接上游 API，因此不暴露 API 密钥，也没有浏览器 CORS 问题。
• API 密钥保存在宿主侧 ~/.dsh/settings.yaml；设置桥会对密钥进行脱敏。
• 历史数据存放在 ~/.dsh/dsh-imagegen/：图片独立落盘，index.json 保存索引。
• 模板库的提示词快照随插件发布；展示图从 vibeui.top 通过本机宿主按需拉取，并缓存到 ~/.dsh/dsh-imagegen/template-images/。模板库仅在手动刷新或首次加载展示图时访问该站点。
• 插件通过专用 loopback 路由 /api/dsh-imagegen/settings/{describe,mutate} 访问设置，不需要修改 DSH 源码或依赖第三方命名空间白名单。

项目结构

开发

pnpm run typecheck  # TypeScript 类型检查
pnpm run build      # 构建宿主与 Web bundle
pnpm run watch      # 持续构建

📬 反馈与提问

• 遇到 Bug：请使用 Bug 报告模板 提交， 并附带插件版本、DSH 版本、安装方式与复现步骤（请勿在 issue 中粘贴 API 密钥）。
• 功能建议：请使用 功能建议模板 提交， 描述使用场景与期望效果。
• 安装 / 使用问题：先查阅本文档「快速开始」与「配置 API」章节。

许可证

Apache-2.0