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 仓库