前言¶
在 DeepSeek Harness（DSH）里做智能体时，画图往往要单独接 SDK、自己处理返回 URL 和会话展示。上游有些接口给的是短时签名外链，翻回历史对话图就挂了。dsh-imagen 把「选平台 → 调模型 → 落盘 → 在对话里显示」收成一条插件链路，并在配置里切换火山方舟、OpenAI 兼容、Gemini，无需改代码。下面按定位、能力、配置与用法说明。
这是什么¶
dsh-imagen 是面向 DSH 的文生图 / 改图插件：模型在对话中调用工具 dsh-imagen，按配置对接一家图像 API，把结果写到当前工作区并在回复里以 Markdown 图片展示。
- 维护者：AlexMillerOvO
- 分类：模型推理
- 仓库：AlexMillerOvO/dsh-imagen
- 目录页：SkillHub 插件页
- 当前 package 版本：0.1.0，许可证 MIT
工作方式¶
调用关系可以概括为：
模型调用 dsh-imagen 工具
→ 按配置选一家接口 → 拿回图片字节
→ 落盘到当前工作区 generated-images/
→ 用一个 HMAC 签名的本地 URL
→ 在对话里显示成 Markdown 图片
插件不把上游外链直接丢给前端，是因为例如火山方舟返回的签名 URL 会在几小时后失效；本地存一份后，回看同一会话仍能看到图。
支持的接口¶
在 providers[].kind 上切换，三家含义如下：
kind |
平台 | 说明 |
|---|---|---|
ark |
火山方舟 Seedream | 豆包生图，URL 或 base64 返回都认 |
openai |
OpenAI Images 兼容 | 官方 gpt-image-*、各类中转站、兼容网关 |
gemini |
Google Gemini | gemini-*-image，原生 generateContent |
安装与卸载¶
资料写明：已通过插件管理器装进 desktop profile。源码改动后让宿主重新加载即可，不必重启整个 DSH——在对话里执行 set_plugin false → true，或重启 DSH。
卸载命令：
dsh plugin --profile desktop remove dsh-imagen
配置¶
配置文件：~/.dsh/imagen/config.json（建议权限 600，密钥只放这里）。
示例（节选）：
{
"version": 2,
"active": "ark",
"activeModel": "doubao-seedream-5-0-flash-260915",
"size": "2K",
"outputDir": "generated-images",
"providers": [
{
"id": "ark",
"kind": "ark",
"name": "火山方舟 Seedream",
"baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
"apiKey": "ark-xxxxxxxx",
"models": [
"doubao-seedream-5-0-flash-260915",
"doubao-seedream-5-0-260915"
],
"watermark": false
}
]
}
主要字段：active 为当前提供商 id；activeModel 为当前模型（不在列表则退到第一个）；size 可为 1K / 2K / 4K / 宽x高，空字符串表示交给上游；outputDir 默认 generated-images。每个 provider 需 id、kind、apiKey、models（至少一个），baseUrl 可不填则用默认地址。
换模型或尺寸可以不手改文件：输入栏右侧有「当前生图模型」和「图像大小」下拉，切换后会写回配置；也可在单次工具调用里用 provider / model / size 覆盖，不会改配置文件。旧版 v1 单 model 配置会在读取时自动兼容，首次保存后写成 v2。
三家配置差异（易踩点）¶
- ark：
size支持1K/2K/4K或宽x高；参考图放在请求体image数组（URL 或 data URL），不是 multipart。 - openai：官方尺寸多为
1024x1024等或auto，写1K/2K/4K会被换成auto；显式宽高才原样透传；改图走 multipart。 - gemini：无尺寸参数，
size被忽略；比例需写进提示词。
设置页¶
路径：设置 → 生图（在 workbuddy 项下面）。可增删提供商、填 API 与多个模型 id、设默认大小与输出目录；保存后每次出图都会重读配置，立即生效。API Key 输入框默认为空，留空保存表示不改动原 key；配置相关接口仅接受本机请求，外部 Origin 返回 403。
工具参数与典型用法¶
工具名：dsh-imagen。
| 参数 | 必填 | 说明 |
|---|---|---|
prompt |
是 | 完整画面描述 |
size |
否 | 1K / 2K / 4K / 宽x高 |
model |
否 | 本次临时覆盖模型 |
provider |
否 | 本次临时指定提供商 |
image |
否 | 参考图 1–8 张，本地绝对路径或 http(s) URL；纯文生图请省略 |
watermark |
否 | 本次是否加水印 |
用户在对话里说「画一张…」「按参考图改…」时，插件还会在系统提示里注册路由规则（dsh-imagen:routing，order 2940），引导模型在用户要新图或改图时调用本工具；仅讨论已有图片、或交付物是文字/代码/文档时不应调用。
生成文件路径：<当前工作区>/generated-images/imagen-<时间>-<随机>.png。预览地址形如 http://127.0.0.1:60682/api/imagen/preview/<令牌>，令牌由 ~/.dsh/imagen/preview.key 做 HMAC 签名。
本地不花钱自测：在仓库目录 npm test（15 个适配层单测）；node scripts/mock-ark.mjs 18080 起假方舟，在 config.json 增加指向 http://127.0.0.1:18080/api/v3 的 provider，调用时传 provider: "mock"。
适用场景与注意¶
适合在 DSH 桌面 profile 里需要对话内出图、多上游可切换、历史会话稳定看图的场景。插件以当前 DSH 进程权限运行，密钥落在用户主目录配置里；安装或启用前应自行查看仓库源码与 MIT 许可证。改 index.js / adapters.js 才需要重载插件；只改 config.json 不需重载。
常见上游错误：方舟 SetLimitExceeded / 安全体验模式需在控制台关闭或调限额；401 查 apiKey；404 核对模型 id 是否已在账号开通。
结尾¶
dsh-imagen 把三家图像 API 和 DSH 工具、本地预览、设置页串在一起，减少自建出图胶水代码。更多字段与 FAQ 见仓库 README。
- 目录页：https://www.skillhub.cn/plugins/AlexMillerOvO/dsh-imagen
- GitHub：https://github.com/AlexMillerOvO/dsh-imagen
