dsh-qwen-paint：面向 DeepSeek Harness 的本地圖像生成插件（優化版）

前言¶

DeepSeek Harness（DSH）支持插件化擴展。本插件爲 DSH 提供了本地圖像生成能力。它通過調用本機已安裝的 ComfyUI，執行 Qwen-Image 2.1 模型，完成文生圖與圖生圖任務。生成的圖像落盤保存，並在會話界面中直接呈現。插件的所有網絡流量嚴格限制在本機迴環地址（127.0.0.1），不依賴外部網絡，無需任何 API 密鑰。

插件定位¶

名稱：dsh-qwen-paint
所有者：yanfei0725
許可協議：MIT
核心價值：在本地利用 Qwen-Image 2.1 模型生成圖像，降低使用成本，保障數據隱私。

核心功能¶

插件主要包含以下功能模塊：

生成模式
- 文生圖與圖生圖：支持通過文本或參考圖生成新圖像。
- 生成後自動放大：設置參數後，生成完成後可自動進行分塊放大。
- 串行抽卡（排隊模式）：當顯存不足時，採用“提交一張→等待結果→落盤→再提交下一張”的模式，適合批量生成。
- 單次批量生成：支持一次提交生成多張圖像。
顯存與性能管理
- 顯存檔位：支持 auto、resident（全駐留）、standard、save（省顯存）、ram（權重放內存）、cpu 多種模式。
- 模型精度檔：支持 BF16、FP8、int8、GGUF。
- 文本控制檔：支持 turbo（8步/CFG 1.0）與 native（千問原生工作點）。
- 權重可調：支持主模型、LoRA、ControlNet 權重的調節。
- 通用 ControlNet 支持：通過 controlImage 參數傳入控制圖。
- SageAttention：支持性能模式與兼容模式，依賴 ComfyUI 全局開關 --use-sage-attention。
- RDNA3 FlashAttention：接入已安裝的 RDNA3 FlashAttention 節點。
- OOM 自動回退：顯存不足時自動切換 VAE 解碼爲分塊模式並重試。
生態聯動
- 記憶聯動：支持與 dsh-auto-memory 插件聯動，讀取記憶偏好。

使用方法¶

在 DSH 的配置或調用參數中設置以下項：

設置放大：設置 upscaleAfter 參數，例如設置爲 2。
設置串行：設置 serialBatch 爲 auto（默認）、on 或 off。
設置顯存模式：設置 vramMode，例如設置爲 ram 以將權重放至內存。
設置精度：設置 precisionTier，例如設置爲 BF16。
設置文本控制：設置 textControl，例如設置爲 native。
啓用 ControlNet：傳入 controlImage 參數，並確保 ComfyUI 中存在對應的 ControlNet 節點。
啓用 SageAttention：在 ComfyUI 啓動參數中添加 --use-sage-attention，插件內部可配置 SageAttention 模式。
設置 AMD 優化（可選）：在 ComfyUI 啓動參數中調整 AMD 專屬內核或異步卸載參數，需重啓生效。

依賴與安裝¶

插件運行依賴以下環境：
* DeepSeek Harness：版本需滿足插件兼容性要求。
* ComfyUI：需已安裝並配置好 Qwen-Image 2.1 模型文件。
* 模型文件：本地需存放 Qwen-Image 2.1 的對應權重文件（根據精度檔位要求）。

注意事項¶

網絡與安全：全部網絡流量限於本機迴環地址（127.0.0.1），不產生外部調用費用。
啓動參數：修改 vramMode、AMD 優化參數等涉及 ComfyUI 啓動的配置，必須重啓 ComfyUI 才能生效。
ControlNet：使用 ControlNet 時，必須同時滿足三個條件：ComfyUI 中探測到 ControlNetLoader 和 ControlNetApplyAdvanced 節點、在面板中選中了權重、傳入了 controlImage 參數。缺一不可。
AMD 平臺：BF16、FP8、ControlNet 在開發機（AMD）上未實測。AMD 專屬優化（內核/異步卸載）默認關閉，啓用需重啓 ComfyUI。
SageAttention：該功能依賴 ComfyUI 的全局開關 --use-sage-attention。如果啓用後 ComfyUI 啓動失敗，插件會在當前會話內自動關閉該功能並回退，避免反覆崩潰。
不實測聲明：SADA 節點類型、畫質/速度收益未做真機驗證。