前言¶
DeepSeek Harness (DSH) 采用插件化架构，扩展智能体能力的方式是通过插件提供的工具集。在本地或集群环境中部署 ComfyUI 时，为了提升吞吐量，通常需要运行多个 ComfyUI 进程，每个进程对应一块 GPU。
现有的成熟插件 dsh-comfyui 主要针对单一端点设计，智能体在与该单一接口交互时，无法感知集群中其他节点的负载情况。这会导致所有任务堆积在负载最高的节点上，而空闲 GPU 却无人调度。dsh-zcode-farm 插件填补了这一空白，它让智能体能够“看见”整个 ComfyUI 集群，并提供负载感知的调度能力。
插件介绍¶
dsh-zcode-farm 是一个 DeepSeek Harness 插件，归属于“工作流”类别，由 BOWLUNA 维护。
它的核心作用是让智能体能够探测 ComfyUI 集群中所有实例的实时状态（GPU 利用率、显存余量、队列深度），并根据预设的规则将任务调度到最空闲的实例上执行，而不是盲目地将任务发送到已满载的单个节点。
核心功能¶
插件提供三个核心工具：
- comfyui_farm_status
查看整个集群的实时状态。返回数据包括每台机器的 GPU 信息、剩余显存、当前队列深度、正在运行的任务以及系统建议的下一个任务分配对象。 - comfyui_farm_pick
仅选择实例而不执行任务。支持按显存下限、队列上限、GPU 名称、排除列表进行筛选，并返回选择该实例的具体理由（例如：显存充足且队列为空）。 - comfyui_farm_run
执行负载感知的调度。可以自动选择最优实例（默认行为），也可以强制指定实例。支持接收原始 API 工作流或简单的文本生成请求。
安装与启用¶
通过 DSH 的命令行工具安装插件。安装后需要重启应用以使智能体获得新工具。
dsh plugin --profile web add dsh-zcode-farm
配置说明¶
在 DSH 的配置文件（YAML 格式）中声明插件实例及其参数。必须配置 primaryUrl 作为基准地址，并在 instances 列表中列出所有 ComfyUI 节点的地址。
配置示例：
- id: comfyui-farm
config:
primaryUrl: 'http://127.0.0.1:8188'
instances:
- { id: gpu-18301, baseUrl: 'http://127.0.0.1:18301', label: '5090 shard' }
- { id: gpu-18303, baseUrl: 'http://127.0.0.1:18303', label: 'Blackwell 102G' }
needVramGb: 8
maxQueueDepth: 3
queueWeight: 1000
probeTimeoutMs: 5000
probeRetries: 1
节点选择逻辑¶
系统采用两阶段筛选机制：
1. 过滤：剔除不可达的实例、剩余显存低于 needVramGb 的实例，以及队列深度超过 maxQueueDepth 的实例。
2. 排序：在候选实例中，根据公式计算得分：
score = freeVramGb - queueDepth × queueWeight
默认 queueWeight = 1000，这意味着队列深度对排名的影响远大于显存大小。如果希望“大显存优先”，可设置 queueWeight: 0。
使用示例¶
安装并配置完成后，智能体可以调用以下命令：
# 查看全站状态
comfyui_farm_status
# 挑选一个空闲实例
comfyui_farm_pick
# 执行任务（自动调度）
comfyui_farm_run
技术特点与依赖¶
- 零运行时依赖：插件仅使用 Node.js 内置的
fetch和AbortController，无需安装额外的 Python 或 C++ 依赖。 - 无工作流编辑能力：它不负责编辑 ComfyUI 的工作流图，这属于
dsh-comfyui的职责。它只负责“谁去跑”。 - 无本地性假设：插件将所有实例视为一个 URL 列表。无论是 SSH 隧道、局域网还是远程主机，处理逻辑完全一致。
- 探测重试机制：针对 SSH 隧道可能出现的抖动，探测失败时会自动重试，并在结果中返回尝试次数，便于智能体判断节点是否真正不可用。
生态关系¶
该插件与 dsh-comfyui（77★）是互补关系，而非竞争关系。
- dsh-comfyui：专注于工作流管理、技能包和画布编辑，与单一端点通信。
- dsh-zcode-farm：专注于集群感知、实例选择和负载调度。
两者可以共存，且互不依赖。dsh-comfyui 处理流程逻辑，dsh-zcode-farm 负责将生成的流程分发到具体的物理节点上执行。
注意事项¶
- Node.js 版本：要求 Node.js 版本 >= 20（根据 README 文档）或 >= 22（根据 package.json 引用）。
- 权限与安全：插件以 DSH 进程的权限运行，安装前请检查源码与许可证（MIT）。
- 工程规范：本项目遵循 ZCode 社区的一些工程规范（如双语文档校验、提交前的检查流程），但代码本身为自研，无代码继承关系。
总结¶
dsh-zcode-farm 解决了智能体在多 GPU 环境下的调度盲区。通过提供状态查看、实例筛选和负载调度三个工具，它让 DeepSeek Harness 代理能够高效利用本地或远程的 ComfyUI 集群资源，避免任务堆积在单一节点。
