DeepSeek Harness 插件：dsh-comfyui-ctl 本地 ComfyUI 控制台

前言¶

DeepSeek Harness (DSH) 提供了插件化架構。當智能體需要直接操作本地 ComfyUI 實例時，通常面臨隊列管理、中斷任務、獲取歷史或上傳素材的困難。dsh-comfyui-ctl 是原生 DSH 插件，旨在填補這一空白，讓智能體能夠像操作本地進程一樣管理 ComfyUI。

它是什麼¶

這是一個由 liyi3068238601-oss 維護的聯網工具插件。它提供了一套工具集，允許 DSH 宿主（Cordis）與本地 ComfyUI 實例通信，實現隊列控制、歷史產出管理、模型盤點以及圖片上傳和生成。

核心邏輯封裝在零依賴的 ComfyClient 模塊中，不綁定 DSH，未來可複用於其他框架。

核心功能¶

插件註冊了 11 個工具，覆蓋 ComfyUI 的核心交互場景：

1. 隊列控制
   • comfyui_queue_get：查看運行中與待執行任務。
   • comfyui_interrupt：中斷當前正在進行的生成任務。
   • comfyui_queue_delete：清空隊列或刪除指定的待執行項。
2. 歷史與產出
   • comfyui_history_get：查詢歷史記錄（可按 prompt id 過濾）。
   • comfyui_output_list：列出產出文件（支持 auto/history/directory 模式）。
   • comfyui_output_get：按文件名獲取產出圖片（內聯返回）。
3. 模型與系統
   • comfyui_models_list：盤點模型（支持 checkpoints, loras, vae 等）。
   • comfyui_system_stats：獲取 ComfyUI 版本、Python 版本及顯存/內存狀態。
   • comfyui_nodes_list：列出節點類與擴展清單。
4. 上傳與生成
   • comfyui_upload_image：上傳本地圖片到 ComfyUI input 目錄。
   • comfyui_generate：提交 API 格式的工作流並等待結果。

安裝與啓用¶

安裝插件到 Web profile：

dsh plugin --profile web add github:liyi3068238601-oss/dsh-comfyui-ctl

安裝完成後重啓 DSH。插件包自帶 cordis.patch.yml，會以 comfyui-ctl ID 自動加入 profile，無需手動編寫 insert。

配置項¶

插件配置位於 Web profile 的 cordis.patch.yml 中。以下是常用配置項：

配置示例：

- id: comfyui-ctl
  config:
    baseUrl: 'http://127.0.0.1:8188'
    outputDir: 'C:\path\to\ComfyUI\output'
    allowedUploadRoots:
      - 'C:\Users\your-name\Pictures'

典型用法¶

1. 查看隊列與系統狀態¶

使用 comfyui_queue_get 查看當前任務，使用 comfyui_system_stats 檢查顯存佔用。

2. 提交生成任務¶

使用 comfyui_generate 提交 API 格式的 prompt。配置 wait: true 可同步等待結果。

示例 Prompt：

{
  "prompt": {
    "1": {
      "class_type": "KSampler",
      "inputs": {}
    }
  },
  "wait": true,
  "timeout_ms": 300000,
  "inline_images": true
}

如果不設置 wait，僅返回 prompt_id，後續可通過 comfyui_history_get 查詢狀態。

3. 盤點模型¶

使用 comfyui_models_list 獲取模型清單，支持 JSON 和純文本兩種響應格式。

適用場景與注意¶

• 適用場景：需要在本地運行 ComfyUI 的 DSH 智能體，用於隊列調度、生成任務管理和素材處理。
• 權限與安全：本插件僅讀/控制本地 ComfyUI 實例。請勿將 baseUrl 指向不受信任的遠程實例。
• 安全機制：上傳功能受到嚴格限制，必須配置 allowedUploadRoots。插件會對文件路徑進行規範化檢查，拒絕僞裝擴展名、超限文件及 .. 子目錄遍歷。
• 依賴要求：運行環境 Node 版本需 >= 22.19。依賴項包括 @deepseek-ai/schemastery 和 DSH 宿主（Cordis）。

結尾¶

dsh-comfyui-ctl 通過將 ComfyUI 的 HTTP API 封裝爲 DSH 工具，降低了智能體與本地繪圖工作流的集成門檻。開發者可直接在 cordis.patch.yml 中覆蓋配置，快速接入本地生成能力。

• 插件目錄頁
• GitHub 倉庫