READMESource: main@2142a4f5
dsh-comfyui-agent
让 DeepSeek Harness 的 Agent 直接驱动你本机的 ComfyUI 干活：跑你画布里存好的工作流、把常用工作流存进库并用命名参数调用、按技能包了解工作流用法，产出的图片直接显示在对话里；v0.5 还提供批量参数扫描、多实例/远程安全、完整工作台面板、资产索引、节点缺失诊断与运行审计。
面向 DSH 0.2.x（@deepseek-ai/dsh-tools 0.2.2-rc.1 / cordis 4.x，兼容 >=0.2.0-rc.1）重写。社区的 dsh-comfyui@0.5.4 把 @deepseek-ai/dsh-settings 的 peer 范围锁在 ^0.1.x-alpha，在 0.2.x 上被判为不兼容（预发布版本号只匹配同一 x.y.z）。本插件不把 dsh-settings 当 npm peer 依赖；设置页通过宿主已有的 settings remote 读写配置。
八个工具
| 工具 | 作用 |
|---|---|
comfyui_status |
探活：ComfyUI 版本、队列长度、路径、可用模型清单、GPU/显存、实例列表与最近错误。先跑它确认连得上 |
comfyui_nodes |
搜节点类（filter/category）、查某个类的输入定义（class），或检查工作流缺哪些节点（missing，附安装建议）；detail:"brief" 省上下文 |
comfyui_workflows |
工作流入口：list 列出画布工作流与工作流库（附转换 warnings）；params 看可调参数（画布按 name、库按 id）；get 默认 brief 摘要，detail:"full" 出完整 API workflow；save 把画布/API 工作流存进库（自动生成命名参数与技能包）；export / delete 管理库条目 |
comfyui_run |
真正跑图。四选一：workflowId（工作流库 id，推荐；用 parameters 按名字传参）/ file（画布工作流名）/ template（txt2img、img2img、inpaint）/ workflow（自己写的 API 工作流对象）；支持 @last 复用上一张产出 |
comfyui_batch |
参数扫描/批量出图：sweep 每个键给一个候选数组，按笛卡尔积逐组提交（默认最多 12 组，硬上限 24），返回每组的 prompt_id、实际参数、种子与产出 |
comfyui_show |
action:"latest" 看最近产出（默认 1 张，最多 8 张）、action:"view" 按文件名取、action:"upload" 把本地图片传进 ComfyUI 的 input/（img2img 要用）、action:"list" 列资产索引、action:"delete" 移出索引 |
comfyui_queue |
队列与运行生命周期：action:"list" 看运行/等待；status 查 prompt_id（含 wait:false 提交的任务）；cancel 取消等待或中断运行；clear 清空等待队列；history 看最近完成/失败与产出文件 |
comfyui_skill |
读写工作流技能包：list 列出 SKILL.md 摘要；read 读 SKILL.md 并解除该工作流运行门禁；write / append / mkdir / delete 维护 references/assets 等资料 |
典型对话：
你：用 anima v2 那张画布出一张银发少女，然后把 step 改成 20 再出一张
Agent：comfyui_workflows {action:"params", name:"anima v2"} → 看到节点 765:709 是 steps
comfyui_run {file:"anima v2", inputs:{"765:709":{"value":12}}, savePrefix:"silver"}
comfyui_run {file:"anima v2", inputs:{"765:709":{"value":20}}, savePrefix:"silver20"}
工作流库与技能包（v0.3）
v0.3 起可以把常用工作流存进工作流库，之后不再靠“记住画布文件名 + 节点 id”运行：
comfyui_workflows {action:"save", name:"anima 银发", tags:"人物,anima", path:"E:/ComfyUI/.../anima v2.json"}
comfyui_run {workflowId:"anima-银发", parameters:{prompt:"silver hair girl", steps:20, seed:123}}
- 工作流库：默认存放在
$DSH_HOME/data/dsh-comfyui-agent/workflows.json（可用dataDir改）。save会同时生成命名参数和skills/<id>/SKILL.md模板；list同时列画布工作流与库条目。 - 命名参数：自动从工作流里识别提示词、宽高、步数、CFG、种子、采样器、加载模型等可调字段，名字稳定（
prompt/negative_prompt/width/height/steps/cfg/seed等）。comfyui_workflows {action:"params", id:"..."}可查全部参数；comfyui_run的parameters只接受这些名字，写错会直接报错并列出可用参数。 - 技能包：每个库工作流有
skills/<id>/SKILL.md，写清用途、参数表和运行示例；references/、assets/可按需放参考资料。工作流默认requireSkill:true，首次运行前必须comfyui_skill {action:"read", workflowId:"..."}（三级披露：先看摘要，再读全文，最后按需读资料）。 - 导入/导出：
comfyui_workflows {action:"save", path:"..."}支持画布 JSON 与 API JSON；{action:"export", id:"..."}返回完整记录，方便备份/迁移。
工作台（v0.4 起）
工作台把常用操作搬进 DSH 客户端，仍然不让浏览器直接接触 ComfyUI：
- 设置页：DSH 设置 → ComfyUI。服务器地址、API key、ComfyUI 目录、工作流库目录、超时/回显/上传边界都能在界面里改；
apiKey是密码字段，留空表示不修改，写入走宿主settings服务（带 revision 冲突检测）。 - 浮动工作台：右下角「ComfyUI」按钮，四个页签：
- 工作流：列出工作流库条目（名称、描述、参数数、格式），可运行、导入 JSON、导出、删除；
- 队列：每 2 秒刷新 running/pending，带进度条，可取消单条或清空等待队列；
- 资产：缩略图网格、Lightbox 大图/尺寸、上一张/下一张，视频/音频可点击打开；删除索引；
- 技能：列出技能包、读取/编辑 SKILL.md、保存与新建技能包。
- 同源 API：面板通过
/comfyui/api/{workflows,queue,assets,run,skills,status}与宿主通信；所有写操作都走 DSH 主进程。 - 媒体代理：
/comfyui/media?file=…&subfolder=…&type=…按文件名从 ComfyUI/view取媒体（支持 Range/206），浏览器只看到 DSH 的同源地址；ComfyUI 重启或清空历史后旧结果仍能打开。 - 资产索引：每次
comfyui_run完成后把产出记进$DSH_HOME/data/dsh-comfyui-agent/assets.json（与工作流库同目录），comfyui_show {action:"list"}可查；delete只从索引移除，不删除 ComfyUI 本机文件。
批量、多实例与诊断（v0.5）
- 批量/参数扫描：
comfyui_batch {workflowId:"anima-银发", sweep:{seed:[1,2,3], steps:[12,20,28]}}会按 3×3=9 组逐次提交；maxImages:0只看文件路径。 @last复用：上一条成功出图后，comfyui_run {template:"img2img", params:{image:"@last", prompt:"..."}}自动把最近一张产出作为输入；没有历史时会给出明确提示。- 多实例/远程：配置
instances后可用instance参数选择；非回环地址必须显式allowRemote:true，apiKeyEnv从环境变量读密钥。comfyui_status会列出实例、GPU/VRAM 与最近错误。 - 节点缺失诊断：
comfyui_nodes {action:"missing", workflowId:"..."}对比服务器object_info，列出缺的节点类与安装建议（只建议，不自动安装）。 - 运行审计：每次
comfyui_run/comfyui_batch成功或失败都追加$DSH_HOME/data/dsh-comfyui-agent/runs.jsonl，便于回溯。
安装
装到 ~/.dsh/profiles/desktop。
方式 A（免下载，推荐）：直接从 GitHub Release 装 —— pnpm 会把链接当 tarball 依赖下载（本机实测可行）：
dsh plugin --profile desktop add \
https://github.com/Nana7mi0721/dsh-comfyui-agent/releases/download/v0.5.1/dsh-comfyui-agent-0.5.1.tgz
方式 B（从源码打包，改代码时用）：
# 1) 打包
cd <这个目录>
npm pack --pack-destination dist # 得到 dist/dsh-comfyui-agent-0.5.1.tgz
# 2) 装进 profile（desktop profile 只在应用运行时也能装，但装完必须重启）
node "/d/Program/deepseek harness desktop/resources/runtime/cli/bin/dsh.cmd" \
plugin --profile desktop add <tgz 的绝对路径>
# 3) 确认 dsh.profile.bundles 里有 dsh-comfyui-agent（CLI 会自动加）
# 4) 重新启动 DSH 桌面端
装好后 dsh plugin --profile desktop list 里应能看到 dsh-comfyui-agent@0.5.1。
换版本时注意：add 之前如果旧版本的 tgz 已经被删掉（含"上次用 file: 装、文件后来被移走"的情况），
pnpm 会先解析旧依赖并报 ENOENT: no such file or directory, open '...0.1.0.tgz'；先
dsh plugin --profile desktop remove dsh-comfyui-agent 再 add 新的即可。另外 GitHub 直连在本机是间歇性的，
add 报 UND_ERR_DESTROYED / HEAD ... error 时重试一次通常就过（本机实测第 1 次失败、重试成功后装成 0.5.0）。
配置
安装时写进 ~/.dsh/profiles/desktop/cordis.patch.yml（也可以事后改，改完重启）：
| 字段 | 默认值 | 说明 |
|---|---|---|
baseUrl |
http://127.0.0.1:8188 |
ComfyUI 地址。ComfyUI 核心默认只听 127.0.0.1，换机器要加 --listen |
apiKey |
空 | 反代或鉴权插件要求的 API key；空串表示不带认证头 |
apiKeyHeader |
true |
是否发送 Authorization: Bearer <apiKey>；错误信息与日志会自动脱敏 |
allowRemote |
false |
是否允许连接非回环地址的 ComfyUI；默认只允许 127.0.0.1/localhost/::1 |
instances |
[] |
命名实例数组：[{id,name,baseUrl,apiKey?,apiKeyEnv?,apiKeyHeader?,allowRemote?}]；旧 baseUrl/apiKey 始终作为 id=default 的默认实例 |
apiKeyEnv |
空 | instances 子字段：从环境变量读取该实例的 API key；实例 apiKey 直接值优先于它 |
comfyuiDirs |
[] |
本机 ComfyUI 安装目录列表（多实例/整合包）；读 output/、input/、user/default/workflows/ |
comfyuiDir |
空 | 旧版单目录别名，等价于 comfyuiDirs[0]（兼容旧配置） |
dataDir |
空 | 工作流库与资产索引目录；空 = $DSH_HOME/data/dsh-comfyui-agent（Windows 为 %USERPROFILE%\.dsh\data\dsh-comfyui-agent） |
workflowsDir |
空 | 留空则用 <comfyuiDirs[0]>/user/default/workflows，不存在再试 <comfyuiDirs[0]>/workflows |
outputDir / inputDir / tempDir |
空 | 留空由 comfyuiDirs[0] 推断；本地/远程目录不一致时手动指定 |
requestTimeoutMs |
120000 | 单次 HTTP 请求超时（旧字段 timeoutMs 仍兼容） |
pollIntervalMs |
1000 | 等运行结果时的轮询间隔 |
runTimeoutMs |
900000 | 等一次运行跑完的上限（15 分钟；视频工作流建议 wait:false 或调大） |
toolTimeoutMs |
2400000 | 单个工具调用的上限（40 分钟） |
maxInlineImages |
4 | 一次运行最多回显几张图（maxImages 工具参数可覆盖） |
maxInlineImageBytes |
15728640 | 单张图回显的字节上限（15 MB），超过只给路径 |
allowUpload |
true |
是否允许 comfyui_show upload 上传本机文件 |
uploadRoots |
[] |
允许上传的根目录；空 = ComfyUI 目录 + 当前工作目录，越界与 .. 会被拒绝 |
工作原理
- 浏览器不直连 ComfyUI：所有请求都走 DSH 主进程（Node）→
http://127.0.0.1:8188。这样跨源/CORS、密钥下发、混合内容都不存在。ComfyUI 核心默认也没开 CORS，所以这条路径是必须的。 - 工作台也走同源 HTTP：设置页读
settingsremote，面板只 fetch/comfyui/api/*，图片/视频只引用/comfyui/media；浏览器永远拿不到 ComfyUI 的baseUrl或apiKey。 - 画布工作流（UI 格式）→ API 工作流是核心难点，转换器在
lib/graph.js：- 按
object_info的输入顺序对齐widgets_values，被连线覆盖的输入以links为准； - 展开子图（
definitions.subgraphs，内部节点 id 变成父id:子id）； - 直通
Reroute/mode:4（bypass）/PrimitiveNode/ Set-Get 命名对； - 处理「动态 widget」：
AspectRatioAdvanced.ResolutionState（一坨 JSON）、rgthreePower Lora Loader的lora_N、LoraManager 的loras； - 展开后做引用完整性检查和可达性剪枝：只保留能回溯到输出节点的部分（ComfyUI 会校验 prompt 里每个节点的必填输入，散落的节点会让整次提交被拒）；
- 转换结果里的
warnings/skipped会附在工具回复里，不会静默丢参数。
- 按
- 出图回显：产出文件经
/view?filename=…&subfolder=…&type=…按文件寻址取回（不依赖/history），用ctx.get('attachments').saveImages()存成会话附件（旧saveImage仅作回退），再以 attachment 引用回给模型。 - 超时分开：
requestTimeoutMs管单次 HTTP，runTimeoutMs管一次运行跑完。视频类工作流建议wait:false（只提交），再用resume:"<prompt_id>"收结果。
行为细节（实测）
- 产出清单给的是本机绝对路径，且按
type分目录：SaveImage落在ComfyUI/output/，PreviewImage落在ComfyUI/temp/（不要一律按 output 拼，那样给出的路径打不开）。 - 同一张图只回显一次：工作流里常见
SaveImage+PreviewImage各写一份（如anima v2 ttp的#46与#896），内容相同就合并报告，并注明「有 N 个产出与上面某张图内容完全相同」。判据是附件 id —— DSH 的附件库是内容寻址的，所以 id 相同即内容相同。 params只喂内置模板：workflowId/file/workflow运行时给params会得到明确提示（不静默忽略）；库工作流请用parameters按名字传参，画布/inline workflow 请用inputs按节点 id 覆盖，例如inputs:{"76":{"seed":123456}}（节点 id 见comfyui_workflows { action:"params" }）。savePrefix同样只对txt2img/img2img生效。params.image容错：input:xxx.png/input：xxx.png（全角冒号）/[input]xxx.png/ 带引号都会自动洗成xxx.png；如果这张图不在ComfyUI/input/里，会在提交前报错并提示先用comfyui_show { action:"upload" }上传，而不是等 ComfyUI 回一句Invalid image file。- 种子照实回报：
seed显式给了就是给了（0也算给了），回报里的种子等于真正提交的值；randomizeSeed:false时用画布工作流里存的种子。 - 回显上限：默认最多把 4 张图带回对话（
maxImages可调，上限 12）；显式给0就是「只给文件路径、不回显图」（不会被当成没给而回落到 4）。超出时会在回复里说明「这次产出 N 张图，只回显了 M 张」并列出其余路径。 - 画布工作流按子目录递归列出：ComfyUI 的工作流浏览器允许建文件夹，子目录里的工作流名字写成
子目录/名字，run/params/get都认这个写法（也接受带.json后缀）。 resume的文案：comfyui_run { resume:"<prompt_id>" }不参与建图，回复渲染成「完成：resume（用时 X 秒）」，而不是「（0 个节点）」。
已知边界
- 本机 ComfyUI 0.43.2 + 48 个自定义节点包，实测 10 个画布工作流全部能转换成功（详见
_research/）。 - 纯前端节点（Note、Fast Muter、没有服务端实现的 rgthree 开关）会被跳过；它们下游的连线若因此断掉，会在
warnings里说明。 - 只有连到输出节点的分支会参与运行；被 skip 的节点会列在回复里。
- 8 GB 显存（RTX 5060 Laptop）下别并发提交多个大工作流。
- ComfyUI 核心无鉴权；插件已支持
apiKey/apiKeyHeader对接反代或鉴权插件。要连局域网机器请自己确认网络可信。
排错
comfyui_status报连不上：确认绘世启动器已经点了「一键启动」，控制台里出现To see the GUI go to: http://127.0.0.1:8188。- 提交被拒并提示
required_input_missing：说明某个节点的必填输入没解析出来（常见于 bypass 链的中间节点），看工具回复里的warnings，用comfyui_nodes {class:"…"}查该节点真正要什么输入。 - 找不到模型：
comfyui_status会列checkpoints/diffusion_models/text_encoders/vae；本机没有 checkpoints，走的是UNETLoader + CLIPLoader + VAELoader路线。 - 工具没出现在对话里：看启动日志里有没有
comfyui-agent: 已注册 8 个工具。注册期抛错会让 8 个工具全部消失（cordis 只把这个插件标记为失败，不会影响其他插件）。
维护须知（改代码前必读）
DSH 0.2.x（当前 0.2.2-rc.1）的 @deepseek-ai/dsh-tools 对工具定义做严格校验，两条规则踩了就全废：
output.schema的根节点不能有required（items、oneOf分支同理）。 只有「属性」节点才允许required: true，它表示该属性在父对象里必填。 违规原文：JsonSchemaError: unsupported JSON schema: schema.required is not supported by the value schema DSL（注册期抛，8 个工具全注册不上）。- 工具返回值必须是 lossless JSON：对象里不能出现值为
undefined的键。 违规原文：ToolOutputError: "value" must be a lossless JSON object（每次调用都报错）。 本插件在lib/tools.js用defineJsonTool()包住defineTool()，返回前统一prune()掉undefined键。 另外parameters本身是「属性表」（{ filter: { type: 'string' } }），不要再包一层{type:'object', properties:{…}}。
改完别只跑离线测试台（它的 dsh-tools 是桩，不校验）。用真包验一遍：
mkdir -p /tmp/realtools && cd /tmp/realtools
npm i @deepseek-ai/dsh-tools@0.2.2-rc.1
mkdir -p node_modules/dsh-comfyui-agent
cp -r <这个目录>/lib <这个目录>/package.json node_modules/dsh-comfyui-agent/
node check.mjs # 真 defineTool 注册 8 个工具
node run.mjs all # 真跑 execute + 真 validateJsonSchemaValue 校验返回值 + render
三条踩过的坑（别重新踩）
- 不要对「自己刚提交的」
prompt_id做提交前硬判定。 ComfyUI 0.43.2 里，缓存全命中的任务约 10ms 就跑完：item 已从/queue弹出、/history条目却还没落盘， 这时两边都查不到。曾经用「先查存在性再轮询」的写法，导致连续第二次同参运行被误判成找不到 prompt_id=…。现在的做法是waitForCompletion(promptId, { assumeExists, graceChecks })： 严格判定只留给resume（用户给的 id 可能是假的，要求秒失败）；自己提交的任务容忍连续 5 轮不可见后才报错。 /history条目的形状（ComfyUI 0.43.x）：{ [id]: { prompt: [number, id, promptDict, extra_data, outputs_to_execute], outputs, status, meta } }，status.status_str是success/error，status.messages是数组；/queue则是{ queue_running: [[number, id, prompt, …]], queue_pending: [] }。 刚提交完立刻读/history拿到undefined是正常的（还没落盘/还在排队），要等运行结束再读。- DSH 启动时把插件模块载入内存：改
node_modules里的文件不会热更，本会话的真工具调用仍在跑旧代码。 验完 rig 要么重启 DSH，要么临时rm+cp同步安装副本再重启（同版本 tgz 无法靠pnpm install覆盖）。
测试台的语义局限
- 测试台里
saveImage的替身用原始 PNG 字节算 sha，而真 DSH 的附件库是内容寻址（按归一化后的图算）。 两个 PNG 哪怕像素相同，字节也可能不同（RGB vs RGBA、元数据、压缩级别），所以「同图去重」这条在测试台里测不出来， 只能在真机上确认。 - 测试台从磁盘重新加载源码，所以它才是改完代码后立刻可用的验证途径（真 DSH 要重启）。
开发与测试
npm test # node --test test/*.test.js（转换内核、配置/鉴权、队列、工作流库/技能包、资产/媒体/API、客户端与验收）
node --check lib/*.js
测试不依赖真实 ComfyUI 或网络；新增/修改 lib/graph.js 时至少跑 test/graph.test.js 与 test/acceptance.test.js。
仓库结构
lib/ 插件源码（纯 ESM，无构建步骤）
index.js 入口：配置 → BackendManager（多实例）→ 工具注册（挂在 cordis fiber 上）
config.js 唯一配置 schema（含 allowRemote/instances/apiKeyEnv）/ 解析与规范化
backend.js 多实例客户端管理（BackendManager / 远程门禁）
runtime.js 队列服务（list/status/cancel/clear/history）
errors.js ComfyUI 错误 → 可操作中文建议
tools.js 8 个工具的定义与执行（status/nodes/workflows/run/batch/show/queue/skill）
store.js 工作流库（workflows.json 原子写）
params.js 命名参数识别、schema 生成与写回
skillpack.js 技能包读写与路径防护
assets.js 资产索引（assets.json 原子写）
audit.js 运行审计（runs.jsonl JSONL）
api.js 面板 HTTP API（workflows/queue/assets/run）
media.js 同源媒体代理（/comfyui/media，Range 流式）
client.js DSH 客户端 bundle：设置页 + 四 tab 完整工作台面板
comfy.js ComfyUI HTTP 客户端（提交、轮询、取图、上传）
graph.js 画布工作流（UI 格式）→ API 工作流转换器
templates.js 内置 txt2img / img2img / inpaint 模板
cordis.patch.yml 安装时插进 profile 的 patch（插件 id / name / config 默认值）
dist/*.tgz npm pack 产物，可直接 `dsh plugin --profile desktop add` 安装
许可
MIT，见 LICENSE。
No comments yet. Be the first to write one.