前言¶
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 集羣資源，避免任務堆積在單一節點。
