@xiaoyuink/dsh-image-create

<br> <em>🎨 文生图 / 图生图 / 生成历史 / 一体化设置 —— 与 dsh-image-vision 同系列的 DSH 图像插件</em>

核心思想：在 DSH 里直接生图，不离开对话。插件通过宿主进程安全代理 OpenAI 兼容的图像生成接口（/images/generations 文生图、/images/edits 图生图），在侧边栏提供三栏生图工作台；同时把 generate_image 工具注册给 Agent——在对话框里让模型直接生图，结果自动进入面板历史。

🎯 与视觉插件互补

dsh-image-vision 负责「看懂图片」，本插件负责「画出图片」：生图面板的图生图参考图、历史记录里的图片，都能直接配合视觉插件精读。两者设置页 UI 完全一致，配置体验统一。

功能总览

• 文生图 / 图生图：提示词生图，或上传 PNG / JPG / WEBP / GIF 参考图做编辑（编辑模型自动走 /images/edits）。
• Agent 工具：注册 generate_image 工具，对话框里模型可直接生图；生成成功后自动写入面板历史。
• 可调参数：尺寸（预设 + 自定义宽×高，缺省自动补 1024）、清晰度（质量等级 + 自定义 PPI）、生成数量（1–4）、细节等级。
• 编辑模型自动回退：文生图模式下若选中的是编辑模型（id 含 edit），自动改用同供应商的生图模型，不再报 Missing required key: image。
• 多供应商 + 自动降级：配置多个供应商，激活项失败时自动尝试其他供应商。
• 结果操作：下载、全屏预览（缩放/切换）、复制优化提示词、一键把结果加入图生图。
• 持久化历史：图片保存在 ~/.dsh/plugin/dsh-image-create/images/，index.json 记录提示词与参数，最多保留 50 条；支持查看、恢复参数、删除、清空；面板历史区显示「图片保存于：实际路径」。
• 在线更新：检测 GitHub Releases，工作台内一键更新，重启后生效。
• 可视化设置页：多供应商管理、厂商模板、模型发现、总开关——渲染与视觉插件一致。

快速上手（如何使用）

安装插件

方式一：一条命令安装最新 Release（推荐，无需源码/依赖，始终是最新版）

dsh plugin --profile web add https://github.com/xiaoyuink/dsh-image-create/releases/latest/download/xiaoyuink-dsh-image-create-latest.tgz

上面的 URL 永远指向最新版本（/releases/latest/ 自动重定向到最新 Release 的资产），无需改版本号。若想安装指定版本，把 latest 换成版本号即可，例如： .../releases/download/v1.4.1/xiaoyuink-dsh-image-create-1.4.1.tgz

升级更简单：打开 DSH 设置 → 生图插件，插件会自动检测 GitHub 新版本并一键更新，无需手动改 URL 重装。

方式二：GitHub 仓库开发模式（link:，代码改动重启即生效，适合二次开发）

# 建议在 ~/.dsh 下新建 plugin 目录，统一存放插件本体
mkdir -p ~/.dsh/plugin
cd ~/.dsh/plugin

# 克隆仓库
git clone https://github.com/xiaoyuink/dsh-image-create.git
cd dsh-image-create
pnpm install
pnpm run build

# 添加到 DSH 配置（link: 协议）
dsh plugin --profile web add "$(pwd)"

💡 关于插件存放位置：开发模式建议将插件本体放在 ~/.dsh/plugin/ 目录下统一管理，也可以根据你的喜好放在任意位置，dsh plugin add 时指向该路径即可。

安装完成后重启 dsh web，然后按以下步骤开始使用：

1️⃣ 配置供应商

进入 DSH 设置 → 生图插件（或「设置 → 插件 → 可配置」卡片），点击 + 添加供应商：

1. 选择厂商模板（OpenAI / SiliconFlow / 阿里云 DashScope / 智谱 / 腾讯混元 / 火山引擎 / MiniMax / 阶跃星辰 / 零一万物 / OpenRouter 等），名称与端点自动填入；
2. 填入 API Key（建议 env:VAR 或 cred:REF 引用，见下文「API Key 安全」）；
3. 点击「获取模型列表」自动发现模型，或手动输入模型 ID；
4. 点击模型行的「使用」切换为当前激活模型（顶部「当前使用：供应商 · 模型」条实时显示）。

2️⃣ 开始生图

面板方式（推荐）

从 DSH 侧栏打开「生图插件」→ 输入提示词 → 选择尺寸/清晰度/数量 → 点击「开始生成」

• 文生图：直接写提示词生成；
• 图生图：切到「图生图」标签，点击/拖拽上传参考图（拖拽只进面板、不会误入对话框），再写修改描述。

Agent 方式

在对话框里对模型说：「帮我生成一张 xxx」

模型会自动调用 generate_image 工具生图，结果会同时显示在面板历史记录中。

3️⃣ 管理历史

• 历史列在面板右侧，点击可查看原图、恢复参数再生成；
• 支持单条删除、清空；图片保存在 ~/.dsh/plugin/dsh-image-create/images/（历史区顶部会显示实际路径）；
• Agent 在对话框生成的图片同样会出现在这里。

一、Agent 工具：generate_image

参数	必填	说明
prompt	是	详细的图片描述（风格、构图、色彩、光线、主体）
size	否	auto / 1024x1024 / 1792x1024 / 1024x1792 / 1536x1024 / 1024x1536，默认 auto
quality	否	auto / low / medium / high
n	否	生成数量（1–4），默认 1
detail	否	''（自动）/ standard / high（部分网关支持）
image	否	参考图 data URL，提供后走图生图

• 生成成功后自动追加到面板历史记录（与面板生成同一存储）。
• 文生图 + 编辑模型时自动改用同供应商的生图模型。
• 上游失败返回可读错误；多供应商配置下自动降级。

二、设置页面（DSH 设置 → 生图插件）

渲染与视觉插件设置页一致（供应商卡片浅灰头部、状态点、就地编辑灰色卡片、框式当前使用条）：

…