文生图工具 ninjasle/dsh-imagegen

dsh-imagegen

给 DeepSeek Harness 接上文生图能力的插件：模型可以直接画图，图片直接显示在对话里；输入框上还会多一个按钮，点开就能改接口地址 / 模型名 / API Key。

- 默认后端 DashScope 的 Qwen-Image（qwen-image-3.0），也支持任何 OpenAI 兼容的 /images/generations 端点
- 提供 4 个智能体工具 + 1 个输入框按钮 + 1 张「插件」设置卡片
- 配置改动即时生效，不用重启进程

为什么需要它

llm-pi-ai 这类 LLM 服务商只串「文本进、文本出」的 chat 路由。qwen-image- 是图像模型，不是 chat 模型，把它配成服务商的模型只会得到：

404 Unsupported model qwen-image-3.0 for OpenAI compatibility mode.
400 The product is not activated, please confirm that you have activated products ...

文生图要走 DashScope 原生的 multimodal-generation 端点，所以本插件以工具的形式暴露能力，而不是伪装成一个 chat 模型。

安装

前提：DSH ≥ 0.2，配置档里已装载 @deepseek-ai/dsh-tools（默认就有）与 @deepseek-ai/dsh-settings（Web 配置档默认就有）。

已发布到 npm：<https://www.npmjs.com/package/@danenze/dsh-imagegeneration>

在 DSH 会话里让智能体安装，或直接调 plugin_manager 工具，三选一：

1) npm（推荐，版本可锁）
plugin_manager(action: "install_bundle", target: "@danenze/dsh-imagegeneration")

2) GitHub 源码
plugin_manager(action: "install_bundle", target: "github:ninjasle/dsh-imagegen")

3) 本地源码目录（绝对路径）
plugin_manager(action: "install_bundle", target: "/path/to/dsh-imagegen")

安装成功后：

- 配置档的 package.json 出现 "@danenze/dsh-imagegeneration": "0.3.0"（或 link: / github: 形式）
- dsh.profile.bundles 末尾出现 @danenze/dsh-imagegeneration
- 重启一次 DSH Web / 桌面端（宿主插件在启动时组装，没有热更）

npm 包名带 @danenze/ 前缀是因为 dsh-image-generation 这个无前缀名字已被别人占用，且 dsh-imagegeneration 被 npm 判为“与已有包过于相似”而拒收。

使用

1. 对话里直接说

「画一只戴围巾的橘猫」→ 智能体调 generate_image，图片落盘并作为附件显示在对话里。

2. 输入框上的按钮

输入框左下角工具行会多一个图片按钮（在表情按钮右边）。点开是一个浮层，可以直接改：

| 字段 | 说明 |
| 接口地址 | 例如 https://dashscope.aliyuncs.com，或你自己的代理 / OpenAI 兼容端点 |
| 模型名 | 例如 qwen-image-3.0-pro |
| 超时 | 单次生成超时（毫秒），默认 180000 |
| API Key | 只写不回显，存进 DSH 凭据库，不写进配置文件 |

保存后立刻生效（配置字段是 volatile 引用，loader 就地更新，不重载插件）。

同一张表单也会出现在 设置 → 插件 → 图片生成 里。

3. 用工具改

| 工具 | 说明 |
| generate_image | 文生图 / 参考图改图 |
| imagegen_models | 当前配置、可用模型、密钥来源（不回显密钥） |
| imagegen_config | 读当前生效配置 |
| imagegen_set_config | 改接口地址 / 模型名 / 超时 / API Key |

generate_image 参数：

| 参数 | 类型 | 说明 |
| prompt | string，必填 | 画面描述。具体写主体、动作、构图、风格、光线、配色；要出现文字就用引号写清楚 |
| model | string | 覆盖默认模型 |
| size | string | DashScope 用 10241024 形式，OpenAI 用 1024x1024；自动转换 |
| n | number 1–4 | 生成张数 |
| negative | string | 不想出现的元素（DashScope 用负向提示词，OpenAI 拼进 prompt） |
| refImages | string[] 最多 3 | 参考图 http(s) 地址，图生图 / 改图 |
| watermark | boolean | 是否加水印 |
| promptExtend | boolean | 服务端是否自动扩写提示词 |
| name | string | 文件名前缀 |

返回：图片写入 outputDir，同时存进 DSH 附件服务，最终以 text + image 内容块渲染，所以对话里能直接看到图。

配置项

cordis.patch.yml 里的 config，全部可在运行时改（credentialsFile 除外）：

| 键 | 默认 | 说明 |
| provider | dashscope | dashscope 走 multimodal-generation；openai 走 /v1/images/generations |
| baseURL | https://dashscope.aliyuncs.com | 端点根地址 |
| model | qwen-image-3.0 | 默认模型 |
| apiKeyEnv | DASHSCOPE_API_KEY | 从这个环境变量找密钥 |
| apiKey | 空 | 直接把密钥写配置里（不推荐，优先用凭据库） |
| credentialsFile | $DSH_HOME/.credentials.yaml | DSH 凭据文件路径 |
| credentialsKey | MULTIMODAL_GENERATION_API_KEY | 从凭据文件读哪个键 |
| outputDir | $DSH_HOME/imagegen | 图片落盘目录 |
| timeoutMs | 180000 | 单次生成超时 |

密钥解析顺序：调用参数 key > config.apiKey > 环境变量 apiKeyEnv > DSH 凭据服务（apiKeyEnv 与 credentialsKey 两个名字都试）> 直接扫 credentialsFile。

密钥不会出现在工具返回值、日志或配置文件里（apiKey 字段标了 role('secret')，跨线前被剔除）。

已知模型

qwen-image-3.0（默认）、qwen-image-3.0-pro、qwen-image-2.1-pro、qwen-image-2.0-pro、qwen-image-2.0。

列表只是提示——服务端支持但没列出的 id 也能直接传。

实现要点（给要改代码的人）

- 宿主侧（index.js）：defineTool 注册工具；Config 是真 schemastery schema，可编辑字段标 .volatile()，密钥标 .role('secret')；每次工具调用都重新摊平配置（cfg(config) 解包 volatile 引用），所以改配置无需重启。
- 客户端（lib/client.js）：手写的预打包 bundle（window.__ModuleLoader__.load 包装），往 conversation.input.left + conversation.input.overlay 注册按钮与浮层，往 plugins.item 注册设置卡片。表单用 @deepseek-ai/dsh-client-ui-primitives 的 SettingsFormModel，密钥走 ctx.remote.credentials.set()。
- 投递指令：插件向 ctx.systemPrompt 注册一条 section，要求模型出图后在回复正文里内嵌图片，避免「只在磁盘上生成了，用户看不见」。

踩过的坑

1. Config 必须是真 schemastery schema（带 ~standard.validate）。写成普通对象会让 cordis 的 resolveConfig 抛 Cannot read properties of undefined (reading 'validate')，整条 entry fiberPhase: failed，一个工具都不注册。
2. @deepseek-ai/schemastery 必须写进 dependencies。profile 用 nodeLinker: hoisted + autoInstallPeers: false，声明了才会进依赖树。
3. @deepseek-ai/dsh-tools 只在 runtime 树里，profile 侧解析不到，所以 index.js 用 createRequire 从多个候选目录找它，找不到再用动态 import。
4. volatile 字段解析后是引用对象，不是裸值。z.string().volatile() 拿到的是 { get() }，读配置必须解包，否则业务代码会拿到包装对象。
5. .volatile() 是方法，不是属性。写成 .volatile 会退化成一个 type: "is" 的坏节点，类型全丢。
6. 客户端组件不能用 jsx(Component) 少传 props。React 的 jsx runtime 会直接读 config.key，undefined 抛 TypeError，组件崩溃后被插槽监督机制静默移除（看不见、日志里也没有）。
7. 客户端 bundle 缓存是 immutable 的。改完 lib/client.js 要重启服务才重新算 rev，只刷新页面不够。

许可证

MIT