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
脚本做的事（幂等、改前备份、验证不过自动回滚）：
- 先 import 一次插件入口，ESM 语法错或依赖解析失败会当场暴露；
- 备份 profile 的
package.json 到 profiles\<profile>\_backup-dsh-qwen-paint-<时间戳>\；
- 写
dependencies["dsh-qwen-paint"] = "link:<本目录>"；
- 把
dsh-qwen-paint 加进 dsh.profile.bundles；
- 建 Junction
profiles\<profile>\node_modules\dsh-qwen-paint → 本目录；
- 复核三处都落了，没落就回滚。
官方首选路径是 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 客户端全文没有任何 <img> / loadImage；交付卡片只给「用默认程序打开」的入口 |
| 助手消息直接带图片 | ✗ | 附件子系统文档明说："当前生产适配器声明只输出文本，因此只有用户内容携带图片" |
① 正文 Markdown 图片  | ✓ | 官方设计：客户端 fileMediaUrl() 把本地绝对路径重写成 <base>/api/file?path=…，打到内核已认证的 /api/file 路由取字节，渲染成真 <img>。内核自带的 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 格子：运行中显示「正在用本机千问画图…」，
完成后自己 <img src="api/file?path=…"> 渲染，失败时显示错误原文。
另外 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 只渲染一个 <span> 座位，圆点与文字都在 useEffect 里用原生 DOM 挂，
并且注册前检查 React.useRef/useEffect 存在 —— 种子被裁剪过就安静跳过，绝不抛。
许可
MIT —— 见 LICENSE。你可以自由使用、修改、再分发（包括商用），
只需保留版权声明与许可声明。
致谢与来源
作者
@奇迹与你 ｜ https://github.com/wonderandyou/dsh-qwen-paint
