# dsh-image-gen

> Adds in-conversation image generation to DeepSeek Harness web client, supporting Google Gemini, OpenAI, and ByteDance Seedream, with a built-in local image gallery.

## Metadata

- Author: [@shanliuling](https://github.com/shanliuling)
- Repo: <https://github.com/shanliuling/dsh-image-gen.git>
- GitHub: [shanliuling/dsh-image-gen](https://github.com/shanliuling/dsh-image-gen)
- Stars: 100
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://github.com/shanliuling/dsh-image-gen#readme>
- Topics: `ai-agent`, `cordis`, `deepseek`, `deepseek-harness`, `dsh-plugin`, `gemini`, `image-generation`, `openai`, `plugin`, `seedream`
- Forks: 2
- Open Issues: 1
- Last push: 2026-08-19T16:46:32.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:shanliuling/dsh-image-gen
```

## Wiki

## 一句话定位
为 DeepSeek Harness (DSH) Web 端补上"对话内生图"原生能力，支持 Google Gemini、OpenAI（含兼容中转）与字节 Seedream（火山方舟）三家厂商，并自带本地生图画廊、全屏预览、复制与下载等交互。

## 核心能力
- 在对话中用自然语言触发图片生成，Agent 自动调用 `generate_image` 工具并把图片直接渲染到当前会话流
- 同时支持 Google Gemini、OpenAI / OpenAI 兼容中转、字节 Seedream（火山方舟）三家厂商，可在 Web 设置中随时切换
- 顶栏自带"画廊"Tab，按时间倒序汇总所有历史生成图片，支持按 Prompt 关键词搜索和按厂商筛选
- 图片结果接入 DSH 自身的 Attachment 与 Conversation 体系，重开历史会话仍能看到之前生成的图
- 鼠标悬停图片或进入画廊后，支持全屏大图预览、一键复制到剪贴板、本地下载、新标签页打开
- API Key 通过 DSH 自带凭据服务加密管理，前端只写不读，无明文持久化

## 技术实现
- **语言**: TypeScript（含 React 客户端）
- **关键依赖**: `@deepseek-ai/cordis`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-attachment`、`@deepseek-ai/dsh-credentials`、`react`
- **架构模式**: DSH Bundle 双面注入 — Host 面在 `src/index.ts` 用 Cordis `apply(ctx, config)` 注册 `generate_image` 工具 + 同源图片 HTTP 路由，Client 面在 `src/client/index.tsx` 向 `settings.plugin.item`、`tool.call.toolview`、`conversation.view` 三个槽位分别注入设置卡片、对话结果卡片和画廊 Tab；画廊元数据用浏览器 IndexedDB 本地持久化
- **入口文件**: `src/index.ts`（Host face，`lib/index.js`） / `src/client/index.tsx`（Client face，`lib/client.js`）

## 适用场景
想让 DSH Agent 在聊天中直接生成插画、概念图、博文配图的人。安装后只需填一次 API Key，再让 Agent 描述想要的画面，图片会出现在当前对话中并自动归入"画廊"供后续查找、复制、下载。

## 前置依赖与兼容性

| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | >=0.1.0-rc.5 | 由 `peerDependencies` 声明；需使用 web profile |
| Node | >=22.19.0（也支持 >=24.0.0） | 由 `engines.node` 声明 |
| Cordis | >=4.0.0 <5 | 插件 Host face 注入框架 |
| React | >=18.2.0 <19 | Client face 渲染依赖 |
| Schemastery | >=3.18.0 <4 | 配置 Schema 定义 |
| 平台 | 仅 Web | `dsh.client.platform` 显式声明为 `web`，不适用于 headless / desktop profile |
| 原生模块 | 无 | 纯 JS + 标准浏览器 API |

## 安装方式

```bash
dsh plugin --profile web add github:shanliuling/dsh-image-gen
```

## 配置项

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| provider | 字符串 | 选择生图厂商：`google`（Google Gemini）、`openai`（OpenAI 或兼容中转）、`seedream`（字节火山方舟） | `google` |
| googleModel | 字符串 | Google 端使用的模型名 | `gemini-3.1-flash-image` |
| googleEndpoint | 字符串 | Google Interactions 接口完整地址（含反代场景） | `https://generativelanguage.googleapis.com/v1beta/interactions` |
| openaiModel | 字符串 | OpenAI / 兼容中转端使用的模型名 | `gpt-image-2` |
| openaiBaseURL | 字符串 | OpenAI 兼容 `/v1` 接口地址（用于中转站/反代） | `https://api.openai.com/v1` |
| seedreamModel | 字符串 | 火山方舟 Seedream 模型名 | `doubao-seedream-5-0-260128` |
| seedreamBaseURL | 字符串 | 火山方舟 `/api/v3` 接口地址 | `https://ark.cn-beijing.volces.com/api/v3` |

API Key 不在前述 Config schema 中，而是由 DSH 凭据服务单独保存，前端只写入不读回明文，凭证名分别为 `GEMINI_API_KEY` / `OPENAI_API_KEY` / `ARK_API_KEY`。

## 常见问题

**Q: 安装后在哪里填 API Key？**

A: 打开 DSH Web（默认 `http://localhost:3080`），进入 Settings → Plugins → Image generation，展开卡片后选择 Provider 并填写对应 API Key 保存即可。Key 通过 DSH 凭据服务加密保存，前端不会显示明文。

**Q: 是不是必须给三个 Provider 都准备 Key？**

A: 不必，只需要给当前选中的那一个 Provider 准备即可；切换 Provider 后再补对应的 Key。

**Q: OpenAI Compatible 模式可以接哪些服务？**

A: 凡是提供与 OpenAI `/v1/images/generations` 兼容接口的服务都可以，包括各类中转站、自部署网关或火山方舟等同协议接入点，把 Base URL 改成对应服务的 `/v1` 地址即可。

**Q: 生成的图片存放在哪里？**

A: 图片二进制由 DSH 自身的 Attachment 服务持久化，可随历史会话重新打开；画廊使用的索引元数据（Prompt、Provider、模型等）保存在浏览器 IndexedDB，卸载插件或换浏览器不会自动同步。

**Q: 顶栏看不到"画廊"Tab 怎么办？**

A: 画廊 Tab 由插件注入到 `conversation.view` 槽位，安装完成后会自动出现；如果没出现，请确认当前是 web profile，刷新页面或检查插件是否被禁用。

**Q: 报错 "generate_image requires the XXX credential" 是什么意思？**

A: 当前选中 Provider 对应的 API Key 尚未配置，回到 Settings → Plugins → Image generation 填写并保存即可，错误信息中会带出对应的环境变量名（`GEMINI_API_KEY` / `OPENAI_API_KEY` / `ARK_API_KEY`）。

**Q: 一次能生成多张图片吗？**

A: `generate_image` 工具每次调用返回一张图，但 Agent 可根据需要自动连续多次调用，所有结果都会进入画廊统一管理。

**Q: 可以把生成的图片下载到本地吗？**

A: 可以。鼠标悬停到对话里的图片或画廊卡片，会出现工具条，点击下载图标即可保存为 PNG/JPEG 到本地。

## 上手难度
入门 — 装好之后只需要在设置里填一个 API Key，其余参数保持默认即可对话生图；切换厂商和调整模型都在同一个设置卡片里完成。

## 已知问题与限制
- 仅支持 Web profile：`dsh.client.platform` 显式声明为 `web`，headless / desktop profile 下无法加载
- 受 DSH 自身 `attachments.imageLimits.maxImageBytes` 上限约束，超过限制的图片会被插件主动拒绝并抛错
- 仅接受 `image/png`、`image/jpeg`、`image/webp`、`image/gif` 四种 MIME 类型的图片入库
- Google 端支持 `aspect_ratio` 与 `image_size`（1K/2K/4K）控制；OpenAI 与 Seedream 端只走 `size` 字段
- Google Gemini 官方接口在部分网络环境下连通性可能受限，可通过 `googleEndpoint` 配置反代或中转地址解决

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-image-gen](https://deepseek-plugin.org/plugins/shanliuling/dsh-image-gen)
Wiki generated by AI (model: `MiniMax-M3`)