@xiaoyuink/dsh-image-create

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

核心思想：在 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

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

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

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

• 总开关：开启后注册 generate_image 工具、Agent 播报与生图工作台；关闭后主界面「生图插件」面板与侧栏入口消失，工具与播报注销，对话框如同没有这个插件（设置页保留，可随时重新开启）。
• 当前使用条：顶部框式显示「当前使用：供应商 · 模型」。
• 多供应商管理：添加 / 编辑（就地替换） / 删除供应商，每个供应商下多个模型。
• 模型管理：模型行「使用 / 使用中」切换激活、删除；卡片内「+ 添加模型」就地展开（获取列表勾选 / 手动输入）。
• 厂商模板：选择后自动填入名称与端点。
• 模型发现：填端点 + Key 后「获取模型列表」，自动发现该端点全部模型。

三、API Key 安全

• 设置页 API Key 为密码框，保存后不再回显（GET /config 返回 ******** 占位）；留空保存 = 保留原 Key。
• 保存明文 Key 时自动写入 DSH 凭据服务（~/.dsh/.credentials.yaml），settings.yaml 只存 cred:IMAGEGEN_<供应商id> 引用；凭据服务不可用时拒绝保存，绝不落明文。
• 也支持 env:VAR 环境变量引用。
• 历史明文 Key 若已写在 settings.yaml，重新保存一次该供应商即可自动迁移为 cred:REF。

四、数据与安全

• 生成请求由 DSH 宿主进程代理，浏览器不直接连接上游 API：不暴露密钥、无 CORS 问题。
• 生成图片与历史索引保存在插件安装目录内：
  • 图片：~/.dsh/plugin/dsh-image-create/images/
  • 索引：~/.dsh/plugin/dsh-image-create/index.json
• 升级插件（重新 add 覆盖目录）前建议备份 images/ 与 index.json。
• 历史跨设备共享：连接同一 DSH 的浏览器/设备看到同一份记录。

五、配置数据结构（settings 的 image-create 段）

image-create:
  enabled: true                     # 总开关
  announceToAgent: true             # 是否向 Agent 播报插件能力
  providers:
    - id: p-1787158417469-sexa      # 供应商唯一 id（自动生成）
      name: SiliconFlow
      apiBaseUrl: https://api.siliconflow.cn/v1
      apiKey: cred:IMAGEGEN_p_xxx   # 凭据引用（明文存于 ~/.dsh/.credentials.yaml）
      models:
        - id: Qwen/Qwen-Image
        - id: Qwen/Qwen-Image-Edit
  active: "p-1787158417469-sexa:Qwen/Qwen-Image"   # 当前激活 "供应商id:模型id"

六、HTTP 路由

七、接口兼容性

detail 与自定义 ppi 为透传参数，部分网关支持；官方端点若不接受，引擎会自动去掉 ppi 重试。

目录结构

dsh-image-create/
├── package.json          # 声明 dsh.bundle.patch + dsh.client
├── cordis.patch.yml      # insert 插件行（挂载 bundle）
├── src/
│   ├── index.ts          # host 半：设置注册、generate_image 工具、路由挂载、播报
│   ├── routes.ts         # /api/dsh-image-create/* 路由（配置/生成/历史/更新）
│   ├── engine.ts         # 上游生成代理、多供应商降级、编辑模型回退
│   ├── history-store.ts  # 历史与图片持久化（~/.dsh/plugin/dsh-image-create/）
│   ├── protocol.ts       # 路由路径/类型/厂商模板
│   ├── updater.ts        # GitHub Release 更新
│   └── client/           # 生图工作台、设置页（与视觉插件一致）、侧栏入口
├── docs/images/          # 截图
└── images/               # 运行时：生成图片保存目录（+ index.json 历史索引）

更新记录

给维护者：发布 Release 时，除 xiaoyuink-dsh-image-create-<版本>.tgz 外，请再上传一份固定名资产 xiaoyuink-dsh-image-create-latest.tgz（内容相同），保证首页「一条命令安装最新 Release」的 releases/latest/download/ 链接始终指向最新的包。

• v1.5.0：适配 DSH 0.1.2-rc.1 —— schemastery 依赖迁移为 @deepseek-ai/schemastery；settings 注册改用当前 SettingsProvider.installSection（installSettingsSection/settingsNamespace 已从 dsh-settings 移除）；移除已不存在的 @deepseek-ai/dsh-client-runtime 客户端依赖（client bundle 改为外部依赖 react / dsh-client-ui-primitives，与视觉插件同款）；客户端 Context 类型改用 @deepseek-ai/cordis 并补齐 renderer / session-controller / conversation 类型声明；ImageAttachmentRef 品牌类型适配（attachmentId/mediaType 按当前 dsh-attachment 品牌化）。
• v1.4.1：设置页标题行右上角显示当前版本号（小字），检测到 GitHub 新版本时在标题行提示「有新版本」并提供一键更新。
• v1.4.0：生成图片持久化到 DSH 附件存储并渲染到消息（markdown 引用 + 图片块，超限自动压缩）；面板预览缩放鼠标锚定重构（消除滚轮缩放晃动）；生成后自动把图片插入对话；在线更新改用 GitHub Release tarball 安装（无需 npm 发布）。
• v1.3.0：设置页编辑供应商时「获取模型列表」支持已存密钥自动回查（修复 cred:REF 未解析导致 401）；候选模型按关键词标注「生图/非生图」，非生图模型禁选并支持人工纠错（⇄ 按钮翻转判定）；候选列表新增搜索框（不区分大小写）与双级排序（按名称/按是否生图，各可升/降序）；供应商卡片与卡片内模型支持拖拽排序（≡ 手柄，松手自动保存）；预设厂商下拉对已添加厂商置灰标注「已添加」防重复；添加供应商不再自动预填预设模型（须点「获取模型列表」勾选或手动添加）。
• v1.2.0：新增阿里云 DashScope 原生文生图接口支持（qwen-image-3.x 自动走官方 multimodal-generation 接口）；修复凭据保存时 set 丢失 this 导致 API Key 无法保存的问题；修复设置页切换模型后生图面板模型下拉不同步的问题。
• v1.1.0：多供应商与自动降级、模型发现、Agent 工具注册、设置页与视觉插件 UI 对齐、总开关（关闭后面板/工具/播报整体退出）、API Key 存凭据服务（cred:REF）、图片保存目录迁入插件安装目录并自动迁移旧数据、自定义尺寸/PPI/数量、编辑模型自动回退、Agent 生图写入面板历史、图生图拖拽不泄漏到对话框、历史区显示图片保存位置。

致谢

• dsh-image-vision — 同系列视觉插件；本插件设置页 UI、凭据存储机制与其保持一致，二者配合使用体验统一。

License

Apache-2.0