前言¶
在 DeepSeek Harness（DSH）里做智能体，常见需求是「让模型根据对话直接出图」，又不想把提示词和图片送去云端 API、也不想管理密钥和计费。云端文生图服务每条请求都走外网；自建 ComfyUI 可以本地化，但要在宿主里接工作流、把结果送回会话，仍然要自己做一层集成。
dsh-qwen-paint 把这条链路收成 DSH 插件：对话侧注册工具，本机 ComfyUI 跑 Qwen-Image 2.1（含官方 Turbo），支持文生图、多参考图编辑、局部重绘、元素移除与四向扩图；成品落盘并在聊天界面内联展示。默认出图数据流只发往本机回环地址，无需 API 密钥。
这是什么¶
dsh-qwen-paint 是面向 DeepSeek Harness 的模型推理类插件（当前版本 0.19.0，MIT 许可）。仓库由 TeacherEvaHung 维护；项目注明原作者为 @奇迹与你，优化版脉络来自 @yanfei0725。插件在 DSH 社区目录 SkillHub 收录，与 DeepSeek / 幻方无官方从属关系，属于社区「一切皆插件」生态中的独立条目。
一句话定位：在 DSH 里通过本机 ComfyUI 调用 Qwen-Image，完成本地图像生成与编辑，并把路径与预览回写给会话。
核心功能¶
下面按 README 与 package.json 中已核实能力归纳。
注册工具（7 个）¶
在 DSH 0.2.1-rc.5 上实测可注册并发以下工具（draw_image、list_available_models、check_acceleration、upscale_image、inpaint_image、remove_image、outpaint_image）：
| 工具 | 作用 |
|---|---|
draw_image |
按提示词本机出图；支持 1–16 张参考图（references），0 张为文生图 |
list_available_models |
列出 ComfyUI 目录下实际存在的 UNET / CLIP / VAE / LoRA 等 |
check_acceleration |
识别显卡与加速后端，可按白名单安装厂商加速包 |
upscale_image |
分块放大；可与 upscaleAfter 配置联动 |
inpaint_image |
蒙版局部重绘（裁剪 → 采样 → 回贴） |
remove_image |
按蒙版移除物体并补全背景 |
outpaint_image |
按 left / right / up / down 百分比四向扩图 |
推理链路与参考图规则¶
- 优先探测
qwen_image_2.1_turbo_*主模型，命中后走官方 Turbo：文生图 8 步 sigma，编辑 / 重绘 / 移除 / 扩图 9 步；CFG 固定1.0。可设officialTurboEnabled: false回旧链路。 - 参考图张数分档：0 张走
TextEncodeQwenImage21文生图；1–3 张走TextEncodeQwenImageEditPlus；4–16 张走TextEncodeQwenImage21的images.image_1…image_16；超过 16 张直接报错，不静默截断。 - 显存不足时可 OOM 自动回退（VAE 分块解码并重试）；低显存批量出图可走
serialBatch串行模式（默认auto）。
网络与权限边界¶
README 将网络出口分为两类，写作与排障时建议分开看：
- 出图数据流（提示词、参考图）默认只发往
comfyUrl与hipfireUrl，且lib/net-guard.js在默认配置下强制本机回环（127.0.0.1/localhost/::1）；配成非本机地址且未开allowRemoteComfy时插件会拒绝启动。出站统一经guardedFetch，redirect: 'error'。 - 加速包下载（可选）：
accelAutoInstall默认为true时，会经pip install --upgrade/git clone访问 pip 源与 GitHub，不携带提示词或图片；设为false可完全关闭，出图不受影响。
用户显式设置 allowRemoteComfy: true 后，才可将 ComfyUI 指向局域网或远程主机，此时提示词与图片会发往用户指定的地址。
环境要求¶
- DSH：
package.json声明兼容dsh >= 0.2.0-rc.2；维护者在0.2.1-rc.5（cordis4.0.5/ Node24.22.1）上做过加载与冒烟验证。 - Node：
>= 18.0.0。 - 本机 ComfyUI：需具备 Qwen-Image 2.1 相关模型与节点；README 说明 ComfyUI 可自启或由插件在出图时拉起，安装路径支持自动探测。
- 硬件：面向 NVIDIA / Intel Arc / AMD RDNA2·3·4 等做了加速适配说明；具体能否跑通取决于本机模型与显存，插件提供
check_acceleration做环境自检。
安装与启用¶
安装分「一键部署（含 ComfyUI 与模型）」与「只装插件本体」两条路径。下列命令均出自仓库 README，需在克隆或解压后的插件目录内执行（路径换成你本机实际位置）。
一键部署（推荐）¶
先做环境检测，再按需补 ComfyUI 与模型，并挂进 DSH profile：
node scripts/setup.mjs
node scripts/setup.mjs --check
node scripts/setup.mjs --verify
node scripts/setup.mjs --comfy D:\ComfyUI
node scripts/setup.mjs --tier full|lite
流程包括：自动查找 ComfyUI、将所需模型下载到约定目录并做 SHA256 校验、调用 install.mjs 写入 DSH profile。主模型可选「完整档」（官方 Turbo int8，约 6.8 GB）或「轻量档」（GGUF Q4_K_M，约 4.3 GB，需另装 ComfyUI-GGUF 节点）。
只装插件本体¶
若你已有 ComfyUI 与模型，只需把插件链入 profile：
node scripts/install.mjs
node scripts/install.mjs --profile web
node scripts/install.mjs --uninstall
node scripts/install.mjs --dry-run
README 给出的官方等价 CLI（desktop profile 须先完全退出 DSH）：
dsh plugin --profile desktop add link:<本目录>
脚本会做：校验插件入口可 import、备份 profile package.json、dependencies 写入 link:<本目录>、把包名加入 dsh.profile.bundles、建立 junction 到本目录。装完后必须彻底退出 DSH 再启动一次，工具清单仅在启动时装配。
若 Plugin Manager 因 pnpm 供应链报错无法联网安装，README 说明可直接用 scripts/install.mjs，不依赖包管理器拉取本插件（插件声明零运行时 npm 依赖）。
典型用法¶
对话中自然语言¶
装好并重启 DSH 后，可在聊天中直接描述画面，例如：
画一只在雪地里的柴犬，逆光，胶片颗粒，电影感
给我画一张 16:9 的赛博朋克雨夜街景，霓虹反射在积水上
助手会调用 draw_image。常用参数包括：
| 参数 | 说明 |
|---|---|
prompt |
必填，画面描述 |
size |
画幅比例，默认 1:1，可选 3:4、4:3、16:9 等 |
megapixels |
总像素（百万），默认 1.0 |
seed |
随机种子；同提示词 + 同种子可复现 |
references |
1–16 张参考图路径数组 |
多参考图 JSON 示例（0.19.0 起最多 16 张）：
{
"prompt": "角色站在场景中央，保持服装一致",
"references": ["角色A.png", "角色B.png", "场景.png", "构图.png"]
}
编辑类工具¶
| 工具 | 关键参数 |
|---|---|
inpaint_image |
image、mask、prompt |
remove_image |
image、mask、可选 prompt |
outpaint_image |
image、left / right / up / down（百分比） |
可对助手说「检查一下加速环境」，触发 check_acceleration 查看显卡识别与加速包就位情况。
输出位置与展示¶
默认出图目录遵循工作区约定（README 示例为桌面下的 千问1生图 文件夹，可用配置项 outputDir 修改）。插件通过系统提示词与客户端 tool.call.toolview 两种方式让生成图出现在会话中，并登记 deliverable 便于回放与用系统默认程序打开。
空闲约 5 分钟无出图任务时，可配置 autoShutdown / idleShutdownMs 自动关停由插件拉起的 ComfyUI，以降低常驻显存占用。
适用场景与注意¶
适合谁：已在或愿意在本机部署 ComfyUI 与 Qwen-Image 权重；希望在 DSH 智能体对话里完成文生图、参考图编辑、蒙版重绘与扩图；希望默认不把出图流量发到公网、也不使用第三方绘图 API Key 的开发者。
使用前务必注意：
- 插件以当前 DSH 进程权限运行，具备写文件、受限命令执行（加速包安装）与网络访问能力；安装前请阅读仓库源码、
MIT许可证及 README「权限与已知风险」章节。DSH STORE 侧该插件不满足「全自动准入」信号，通常走人工审核通道——这是功能所需权限带来的结果，而非实现缺陷。 - 默认
accelAutoInstall: true会在加载时访问外部 pip / GitHub；纯离线或内网环境请显式关闭。模型首次加载体积大（README 提及主模型约 13–14 GB 级加载），属正常现象，后续同模型任务会快很多。 - 社区目录页与 GitHub 星标为公开元数据（截至收录线索为 1 star），不作为质量或维护活跃度的唯一依据；版本与配置项以仓库
package.json与 README 为准。
结尾¶
dsh-qwen-paint 把「DSH 工具调用 + 本机 ComfyUI + Qwen-Image 2.1」收成一套可复现链路：七种绘图相关工具、Turbo 链路与多参考图分档、默认本机回环的网络_guard，以及可选的一键 setup.mjs 部署脚本。若你要在智能体工作流里本地出图而不绑定云端 API，可以从社区目录了解条目说明，再到 GitHub 仓库按 README 安装与自检。
- 目录页：https://www.skillhub.cn/plugins/TeacherEvaHung/dsh-qwen-paint
- 源码：https://github.com/TeacherEvaHung/dsh-qwen-paint
