dsh-jimeng —— 即梦(火山方舟 Seedream)生图插件

把「即梦（Seedream）文生图 / 图生图」带进 DeepSeek Harness —— 对话里说一句话，AI 就能画图。

DeepSeek Harness(DSH) 的生图插件：调用火山方舟 Volcengine Ark的即梦（Seedream）图片生成模型，支持文生图 + 图生图，提供两种使用方式：

1. 模型工具：对话里直接说「帮我画一只鲸鱼」，AI 会调用 generate_image / image_to_image 生图，图片落盘并直接显示在对话里。
2. 手动生图面板：设置 → 「即梦生图」分区，手动填 prompt（或选参考图）生图。

特性

• 🖼️ 文生图 generate_image + 图生图 image_to_image（参考图 1-10 张，支持本地路径 / URL / data URL）
• 👀 消息内直接看图：生图工具卡里直接渲染图片（点击看大图 / 下载 / 复制链接），不再是 JSON 文字；图片走会话附件通道（与内置 read_image 同一套机制）
• 🔽 模型下拉选择：内置常见 Seedream 模型下拉 + 「检测可用模型」按钮（自动探测 OpenAI 兼容平台的生图模型）+ 自定义输入兜底
• ⚙️ 可编辑 API 配置：Ark API Key、baseUrl、文生图/图生图模型、默认尺寸、水印开关、保存目录，持久化到 ~/.dsh/dsh-jimeng.json
• 🗂️ 图片落盘：生成图自动保存到 ~/.dsh/jimeng-images/，同时注册为对话附件直接显示
• 🔒 Key 只存 host：API Key 不暴露给浏览器明文（前端只拿到掩码）

界面截图

「即梦生图」出现在设置侧边栏「模型」下方：

设置面板（可编辑 API 配置 + 手动生图）：

模型下拉 + 「检测可用模型」（自动探测 Seedream 生图模型）：

生图工具卡里的图片预览（消息内直接看图，可点开大图 / 下载）：

首次使用：三步完成

1. 安装插件

dsh plugin --profile web add link:G:\DSHJob\plugins\dsh-jimeng

或手动：把 "dsh-jimeng": "file:G:/DSHJob/plugins/dsh-jimeng" 加入 web profile 的 package.json dependencies，并在 dsh.profile.bundles 里加 "dsh-jimeng"，然后 pnpm install。

2. 填写 Ark API Key

打开 设置 → 即梦生图，填入火山方舟的 API Key：

1. 登录「火山引擎控制台 → 火山方舟（Ark）」；
2. 左侧「API Key 管理」→「创建 API Key」，复制整串 API Key；
3. 粘进「API Key」输入框，点「保存配置」。

⚠️ 注意：要填的是「API Key 管理」里的 API Key，不是账号级的 AccessKey/SecretKey（AK/SK）。AK/SK 是签名鉴权，Bearer 用不了，会报 401。

3. 重启并生图

重启 DSH Web Host、刷新页面后，两种方式生图：

• 对话里直接说「帮我画一只鲸鱼」；
• 或到「设置 → 即梦生图」手动填 prompt 生成。

接入方式

• 端点：POST {baseUrl}/images/generations（OpenAI 兼容）
• 默认 baseUrl：https://ark.cn-beijing.volces.com/api/v3
• 默认模型：doubao-seedream-4-0-250828（统一文生图/图生图；图生图模型可单独填 modelI2i）
• 鉴权：Authorization: Bearer <API Key>

插件走 OpenAI 兼容的 images 接口，任何暴露该接口的平台都能用，只需改 baseUrl + 模型名 + key：

平台	baseUrl	模型示例	备注
火山方舟 Ark	https://ark.cn-beijing.volces.com/api/v3	doubao-seedream-4-0-250828	官方，即梦 Seedream
硅基流动 SiliconFlow	https://api.siliconflow.cn/v1	其 Seedream / Kolors 模型名	OpenAI 兼容
自定义中转	你的中转地址	中转提供的模型名	OpenAI 兼容

注意：如果用的是 Seedream 3.0，文生图/图生图是两个不同模型（doubao-seedream-3-0-t2i-250415 / doubao-seedream-3-0-i2i-250415），请分别在「模型(文生图)」和「模型(图生图)」里填写。Seedream 4.0 起统一为一个模型，可同时做文生图和图生图。

工具说明

工具	参数	说明
generate_image	prompt(必填)、size、n(1-4)	文生图
image_to_image	images(数组,1-10 张)、image(单张,兼容旧写法)、prompt(必填)、size	图生图 / 图像编辑（参考图：本地路径 / URL / data URL，顺序即提示词里的「图1、图2…」）

多张参考图（多图输入）

image_to_image 一次可以给 1-10 张参考图，列表顺序就是提示词里的「图1、图2…」：

• 模型侧：images: ["C:\\a.png", "D:\\b.png"]，提示词里写清各图职责，例如「把图2的鲸鱼放进图1的场景，配色参考图3」；
• 面板侧：设置 → 即梦生图 → 图生图，文件选择器可多选（缩略图带「图1/图2…」序号，可逐个移除），也可在 URL 框里每行填一个链接；面板会显示「已选 N / 10 张」，超限标红；
• 上限 10 张是服务端限制（实测第 11 张 → HTTP 400 ... number of reference images cannot exceed 10）。插件在本地就拦下并说明，超限请求根本不会发出去（也就不会计费）；
• 旧模型只吃单张：Seedream 2.x / 3.x / seededit 3.x 的 image 字段只接受单个字符串，给多张会被本地拦下并提示改用 4/5 系列；
• 零行为变更：只给 1 张参考图时，仍按旧版形态发送（4.x 数组、其余字符串），老用法不受影响。

兼容性

组件	要求
DeepSeek Harness	0.1.x（在 0.1.1-rc.2 验证）
Node.js	>= 20
图片平台	任何 OpenAI 兼容 /images/generations 服务

常见问题

生图报 401「API key format is incorrect / missing or invalid」

多半是 key 填错了：

1. 确认填的是「火山方舟 → API Key 管理」里的 API Key，不是 AK/SK；
2. 复制完整、别带空格/换行；
3. 确认账号已「开通火山方舟」；刚开通的话可以重新生成一次 key。

图生图报 400「invalid url specified」

旧版本插件把参考图发成了裸 base64 导致；升级到最新版即可（已改为发送 data:image/...;base64,... data URL）。

「检测可用模型」返回「未检测到生图模型」

火山方舟的 /models 接口主要返回对话模型；如果没检测到生图模型，直接用内置的 Seedream 下拉列表，或用「自定义」手动填模型名 / ep- 接入点 ID。

如何确认插件已载入

dsh --profile web --dump-config

配置中应当出现 name: dsh-jimeng。

如何卸载

dsh plugin --profile web remove dsh-jimeng

卸载后重启 DSH Web Host。

目录结构

dsh-jimeng/
├── package.json        # DSH bundle 插件元数据
├── cordis.patch.yml    # 插件挂载声明
├── index.js            # host 插件（工具 + HTTP API + 配置持久化）
├── client.js           # client 插件（设置分区 + 手动生图面板 + 工具卡图片预览）
├── tests/              # 预览逻辑与组件测试（见下）
├── assets/             # README 首图 + 界面截图
└── README.md

测试

图片预览这块有一条必须守住的契约：tool.call.toolview 是 keyed 槽，注册的条目一旦命中 工具名，owner 的通用卡 fallback 就不再生效 —— 组件必须自己覆盖全部状态（运行中 / 失败 / 结果里没有图片块 / 有图片），否则那些形态会渲染成一片空白。测试就是钉这条契约的。

# 纯逻辑（解析附件引用、路径、参数）+ 组件源码契约检查，24 项
node tests/verify-preview.mjs

# 多图参考的纯逻辑（形态决策 / 归一化 / 上限 / 面板契约），45 项
node tests/verify-multi-image.mjs

# 宿主半边的真模块测试：stub 掉 @deepseek-ai/dsh-tools，跑 apply() 并用 mock fetch
# 断言**真正发出去的 body.image**（零网络、零成本），24 项
node tests/verify-host-tools.mjs

# 一次跑完三条
npm test

# 组件 DOM 测试（需要 React + jsdom + @testing-library，走 DSH checkout 的测试环境）
Copy-Item tests/jimeng-view.client.spec.tsx G:\DSH\deepseek-harness\packages\client\ui-tool\tests\zz-jimeng-view.client.spec.tsx
cd G:\DSH\deepseek-harness
node .\node_modules\vitest\vitest.mjs run packages/client/ui-tool/tests/zz-jimeng-view.client.spec.tsx
Remove-Item packages\client\ui-tool\tests\zz-jimeng-view.client.spec.tsx

verify-host-tools.mjs 这类"把真实模块跑起来"的测试不是可选项：node --check 只查语法， 模块求值期的错误（例如把 export const X 写在 const X 之前 → TDZ ReferenceError） 会一路绿到真机上，插件只留下一句 failed to import。

许可证

MIT © 2026 Quqing-future