千问本地绘图 wonderandyou/dsh-qwen-paint

dsh-qwen-paint（绘图）千问

让 DeepSeek Harness 在对话里直接调用本机 ComfyUI、用千问 Qwen-Image 2.1 画图。
在聊天框说一句「画一只在雪地里的柴犬」，图就出来了 —— 全程 127.0.0.1，不出网、不花钱、不需要任何 API Key。

作者：@奇迹与你　｜　MIT 许可　｜　仓库：<https://github.com/wonderandyou/dsh-qwen-paint>

它是什么

一个 DSH 插件（host + client 两半），注册一个工具：

| 工具 | 作用 |
| draw_image | 按提示词调本机 ComfyUI 出图，成品落盘到「千问1生图」，并把绝对路径回给助手用于内联显示 |

- host 半边（lib/index.js）：注册工具、空闲 5 分钟自动关停 ComfyUI、挂只读状态端点。
- client 半边（lib/client.js）：给 draw_image 一张自绘卡片（图直接显示在工具行里）、在 composer 下方显示 ComfyUI 在线状态。

不改 DSH 安装目录、不改内核文件。

依赖

- ComfyUI 跑在 127.0.0.1:8188（本机：双击 D:\ComfyUI\启动ComfyUI.bat）
- 三个千问模型文件（共约 13.3 GB）：
- qwen_image_2.1_int8_convrot.safetensors（UNET，放 models\diffusion_models\）
- qwen3vl_8b_w4a8.safetensors（CLIP、type=qwen_image，放 models\text_encoders\）
- qwen_image_2.1_vae_bf16.safetensors（VAE，放 models\vae\）
- 不需要任何 Python 环境、不装任何第三方包 —— 插件本体是纯 Node ESM，零外部依赖。

安装

一键部署（推荐）：连 ComfyUI 和模型一起搞定

node scripts/setup.mjs # 检测 + 缺什么补什么
node scripts/setup.mjs --check # 只看差什么，绝不动任何东西
node scripts/setup.mjs --verify # 已存在的模型也重算 SHA256（最稳）
node scripts/setup.mjs --comfy D:\ComfyUI # 指定 ComfyUI 目录

它会：① 自动找 ComfyUI；② 把三个模型下到正确目录并逐个 SHA256 校验（校验不过的一律删除）； ③ 调 install.mjs 把插件挂进 DSH profile。

下载渠道：模型走 ModelScope 官方直连（阿里官方平台），上传者是 Comfy Org 官方组织自己的仓库，期望哈希取自该仓库文件列表 API 的 sha256。
ComfyUI 本体在 GitHub 官方 release，官方不公布哈希，所以脚本默认不自动下它，要下得显式加 --download-comfy（它会再问一次）。

断点续传：中途断了直接重跑，curl -C - 会接着下。

显卡：N 卡开箱即用，A 卡走 ROCm（0.1.1 新增）

脚本先看显卡再决定怎么装：N 卡用 ComfyUI 官方便携包；AMD Radeon 走 ROCm 路线 （AMD 官方 Windows wheels，装完还是 ComfyUI，插件本身不用换，模型也是同一套）； Intel 核显基本跑不动。

AMD 用户先 node scripts/setup.mjs --check 看计划，确认后 --yes 执行。
⚠ 三条必读：A 卡可能静默出错（跑完必须人眼看图）、别升 ROCm 10.0 （HIP 7.15 会破坏权重，脚本锁 7.2.1）、模型禁止商用。

完整说明见 INSTALL.md 的「AMD Radeon 用户」一节。

只装插件本体

node scripts/install.mjs # 装进 desktop profile（默认）
node scripts/install.mjs --profile web
node scripts/install.mjs --uninstall
node scripts/install.mjs --dry-run

脚本做的事（幂等、改前备份、验证不过自动回滚）：

1. 先 import 一次插件入口，ESM 语法错或依赖解析失败会当场暴露；
2. 备份 profile 的 package.json 到 profiles\<profile>\_backup-dsh-qwen-paint-<时间戳>\；
3. 写 dependencies["dsh-qwen-paint"] = "link:<本目录>"；
4. 把 dsh-qwen-paint 加进 dsh.profile.bundles；
5. 建 Junction profiles\<profile>\node_modules\dsh-qwen-paint → 本目录；
6. 复核三处都落了，没落就回滚。

官方首选路径是 DSH 自己的 Plugin Manager（plugin_manager 的 install_bundle，target = 本包绝对目录），或等价 CLI dsh plugin --profile desktop add link:<本目录>（desktop profile 必须先完全退出 DSH）。
本脚本是兜底路径，做的是等价的两件事。

装完必须彻底退出 DSH 再重新打开 —— 宿主侧工具清单只在启动时装配一次。
（DSH 是桌面端 Electron 应用，没有刷新页面这回事。）

用法

装好并重启后，在聊天框直接说：

画一只在雪地里的柴犬，逆光，胶片颗粒，电影感给我画一张 16:9 的赛博朋克雨夜街景，霓虹反射在积水上用同样的种子再画一遍刚才那张

助手会调 draw_image。可传的参数：
| 参数 | 说明 |
| prompt | 必填，画面描述（中文可以）。建议写完整一段：主体 + 细节 + 环境 + 光线 + 风格 |
| size | 画幅比例：1:1（默认）、3:4、4:3、2:3、3:2、16:9、9:16 |
| megapixels | 总像素（百万），默认 1.0。要更清楚就调大 |
| steps | 采样步数，默认 25，范围 1–60 |
| seed | 随机种子。同提示词 + 同种子 = 同一张图；不填则每次不同 |
| negative | 负面提示词。⚠ 千问模型 cfg=1，负面词基本不生效，一般别填 |

尺寸按 32 的倍数对齐（r32(v)=max(32, round(v/32)*32)），与 app.py 的算法一致： 1:1@1MP → 992×992；16:9@1MP → 1344×736；2:3@1MP → 832×1216。

出图落在哪

C:\Users\<你的用户名>\Desktop\千问1生图\（遵循工作区约定；也在会话工作区「桌面」之内，所以交付卡片和行内图片都能取到这个文件）。

命名：<提示词前若干字>_Qwen2.1_<宽>x<高>_<序号>.png，重名自动加 -2、-3。

图片是怎么显示在聊天框里的（原理，改之前务必看）

这一节是 2026-10-07 逐个查内核源码核过的，不要凭直觉改：

| 路径 | 能用吗 | 原因（都有内核源码依据） |
| ImageBlock（工具结果里返 {type:"image", attachment}） | ✗ | 客户端 imageCardModel() 开头就是 if (call?.name !== "read_image") return null —— 只认 read_image；其他工具的 image block 会被 generic 卡片用 JSON.stringify 当文本打印出来 |
| presentCall / presentResult | ✗ | ui-tool README 原文："Host presentCall and presentResult values never enter the Client." |
| presentationMeta 让图显示 | ✗ | 它确实会落到 tool/result 的 data.meta，但客户端只有 read_image 那张卡片读它、且只当路径标签用 |
| present 的交付卡片显示图 | ✗ | dsh-client-ui-deliverables 客户端全文没有任何 / loadImage；交付卡片只给「用默认程序打开」的入口 |
| 助手消息直接带图片 | ✗ | 附件子系统文档明说："当前生产适配器声明只输出文本，因此只有用户内容携带图片" |
| ① 正文 Markdown 图片 | ✓ | 官方设计：客户端 fileMediaUrl() 把本地绝对路径重写成 /api/file?path=…，打到内核已认证的 /api/file 路由取字节，渲染成真 。内核自带的 FILE_REFERENCE_PROMPT 就是这么教模型的 |
| ② 客户端自定义 toolview | ✓ 100% 确定 | tool.call.toolview 是 keyed 槽，文档原文"Any name is allowed, including tools registered by your package"；draw_image 这个 key 未被占用，注册它不遮蔽任何自带 UI |

本插件两条都做，互不依赖：

- ① host 侧用 ctx.systemPrompt.section({ name: 'qwen-paint:inline-generated-image', order: 9100, text: … }) 下一条指令，要求模型出图后在正文里内联展示（与内核 DELIVERABLE_FILE_REFERENCES 同一机制）。
- ② lib/client.js 注册 tool.call.toolview 的 draw_image 格子：运行中显示「正在用本机千问画图…」，完成后自己 渲染，失败时显示错误原文。

另外 host 侧仍会 append deliverables/presented（与官方 present 同一载荷）——这不是为了显示图，而是顺带给一个可点开/用默认程序打开的正式交付入口，且它能让记录可回放。

空闲自动关停（省显存）

要求："不要让 comfyUI 一直跑着，只要五分钟不生图 comfyUI 后端自动关闭。"

- 计时只在插件出过图之后才开始（lastActivityAt 初始为 null）。
→ 所以绝不会误关你自己打开的、正在「小鲸鱼生图」里用的 ComfyUI。
- 到点后还要过两关才动手：ComfyUI 仍在线，且 /queue 为空（有任务在跑就续期，绝不打断）。
- 只杀"监听该端口 且 命令行确实含 comfy 与 main.py"的进程；认不出来就跳过并记日志—— 绝不按端口盲杀。
- 关掉后计时复位；下次出图需要重新启动 ComfyUI（draw_image 会明确提示怎么启动）。

配置：idleShutdownMs（默认 300000 = 5 分钟）、autoShutdown（默认 true，设 false 就永不自动关）。

ComfyUI 在线状态提示（composer 下方）

在 composer 卡片下方（conversation.composer.dock 槽）显示一个小指示器：

| 圆点 | 含义 |
| 🟢 绿 | ComfyUI 在线；若正在空闲倒计时，会写「空闲 N 分后自动关闭」 |
| 🟡 黄 | ComfyUI 正在出图（/queue 非空） |
| ⚪ 灰 | ComfyUI 未启动 / 状态未知 |

它每 5 秒读一次 host 的只读端点 GET /api/qwen-paint/status.json （回退 /qwen-paint/status.json）。该端点：

- 只放行本机请求（Host 与远端地址都必须是回环），其余一律 403；
- 只回事实（online / busy / idleShutdownInMs / url），不含任何本地路径或密钥；
- 任何意外都回 200 + 可读原因，前端显示「未知」而不是报错。

该槽是 list 槽、replaceRisk: none，插件用自己的 id（qwen-paint-status）注册， 与自带的 stats pill 并存，不替换任何自带 UI。

故障排查

| 现象 | 原因 / 处理 |
| 说「画个图」，助手说没有这个工具 | 插件没生效 → 确认 profile 的 dsh.profile.bundles 里有 dsh-qwen-paint，然后彻底退出 DSH 重开 |
| 报「连不上本机 ComfyUI」 | ComfyUI 没启动。双击 D:\ComfyUI\启动ComfyUI.bat 或先开「小鲸鱼生图」（它会自动拉起引擎），等它起来再画 |
| 报「等 ComfyUI 出图超时」 | 首次出图要加载 7.26 GB UNET + 6.31 GB 文本编码器，第一次特别慢；本机实测 25 步 1MP 约 62–124 秒，首次更久 |
| 报 ComfyUI 报错：... + 节点校验详情 | 模型文件名对不上或节点不存在 → 对照上面「依赖」里的三个文件名，以及 ComfyUI 版本需支持 TextEncodeQwenImage21 / QwenImage21Cache（本机 0.37.0 内置） |
| 图出来了但聊天框只有文字 | 交付卡片依赖会话工作区能取到该文件；把 outputDir 设在会话工作区内（默认就在桌面「千问1生图」） |
| 显存不够 / 很慢 | RTX 5060 Laptop 8 GB，三个模型共 14 GB 必然换入换出。降低 megapixels（如 0.5）能明显加快 |

自测

node scripts/selftest.mjs

纯 Node，不联网、不需要真 ComfyUI、不出图、不占显存：起一个假 ComfyUI HTTP 服务器，把插件真跑一遍（探活 → 提交 → 轮询 → 取图 → 落盘 → 交付事件），另加尺寸/文件名/workflow 结构/失败分支/空闲关停边界/状态端点鉴权/客户端卡片渲染的断言（138 项）。

配置

改 cordis.patch.yml 里那一行的 config（这一层升级插件也不会被覆盖）：

| 字段 | 默认 | 说明 |
| comfyUrl | http://127.0.0.1:8188 | ComfyUI 地址 |
| outputDir | C:\Users\<你的用户名>\Desktop\千问1生图 | 成品落盘目录 |
| comfyOutputDir | D:\ComfyUI\ComfyUI\output | 先在本地取文件，取不到才走 /view |
| unet / clip / vae | 三个千问文件名 | 换模型时改这里 |
| steps / resolution | 25 / 1024 | 默认步数与编码分辨率 |
| timeoutMs | 600000 | 单任务超时（10 分钟） |
| idleShutdownMs | 300000 | ★ 出图后多久没再出图就自动关掉 ComfyUI（5 分钟） |
| autoShutdown | true | 设 false 就永不自动关 |
| idleCheckMs | 30000 | 空闲检查间隔 |
| statusCacheMs | 3000 | 状态探测缓存（客户端每 5 秒轮询一次） |

设计取舍（为什么这么写）

- 零外部依赖：不 import @deepseek-ai/dsh-tools。tools.register() 只强校验 output.schema 是标准 JSON Schema，而 parameters 的 spec→JSON Schema 转换是
defineTool() 做的、register() 不校验 —— 既然自己写成标准 JSON Schema 就够，
就不引入「装进 profile 后解析不到包」的风险（插件加载失败会让 DSH 起不来）。
- 用局部 root.inject 等服务，不用对象级 inject：对象级会把整个 apply 推迟到服务就绪之后，某个服务在老宿主里不存在时插件会永远不 apply 且不报错。
- workflow 照抄主人机器上已验证的那份（D:\ComfyUI\小鲸鱼生图\app.py 的 build_workflow），节点与连线一个字不改。
- 启动预热：插件加载时后台探一次后端，不在线就隐藏窗口拉起 （不 await、不阻塞 DSH 启动）；出图时还有一次兜底，所以预热失败也不影响出图。
- 空闲关停的计时起点有两个：预热确认后端在线时、以及你在界面里改档位时。
（⚠ 早先只有「出图成功」才算起点，结果重启 DSH 后一次图都没画就永远不关 —— 已修。）
到点还要确认它在线、/queue 为空（有任务就续期，绝不打断），并且只杀命令行确实像 ComfyUI 的进程 —— 宁可留着占显存，也不误杀别人的进程。
- 状态端点只放行本机、只回事实：{ok, online, busy, idleShutdownInMs, url}，不含任何本地路径或模型名（自测里有专门一条断言守着这条）。
- 客户端状态指示器用 React 座位 + 纯 DOM（照 dsh-reasoning-glow 的做法）： React 只渲染一个 座位，圆点与文字都在 useEffect 里用原生 DOM 挂，并且注册前检查 React.useRef/useEffect 存在 —— 种子被裁剪过就安静跳过，绝不抛。

许可

MIT —— 见 LICENSE。你可以自由使用、修改、再分发（包括商用）， 只需保留版权声明与许可声明。

致谢与来源

- 15 种流光的配色抄自「月匠」 —— 原样照搬、一个色标没改，仅作致敬与复用，相关权利归原作者；原作者若有异议，联系即删。
- 模型权重来自 Comfy Org 官方在 ModelScope 的仓库 （<https://modelscope.cn/models/Comfy-Org/Qwen-Image-2.1>）。
本仓库只记录官方 SHA256，不转存、不镜像任何权重文件。
- ComfyUI 是 comfyanonymous/ComfyUI 的作品，本插件只是通过它的 HTTP API 下任务。

作者

@奇迹与你　｜　<https://github.com/wonderandyou/dsh-qwen-paint>