ComfyUI 工作流面板 Natsubrei/dsh-comfyui-panel

dsh-comfyui-panel

在 DeepSeek Harness Web UI 里跑 ComfyUI：右侧面板放真正的编辑器，模型能读写工作流，也能发起运行。

安装

从插件市场装（推荐）。在 DSH 里打开 Settings → Plugins → Discover → Add index source，粘贴：

https://raw.githubusercontent.com/Natsubrei/dsh-comfyui-panel/main/market/index.json

ComfyUI Panel 卡片会安装整个 bundle；索引里每个版本都锁定一个确切的 commit，所以装上的版本一定经过测试。plugin_market 工具读的也是同一份索引，智能体可以列出索引、查看版本、直接安装，不用开浏览器。

用智能体或命令行装。 从市场卡片复制安装串，格式是 git+https://github.com/Natsubrei/dsh-comfyui-panel.git#<commit>。不带 commit 的 URL 会装默认分支，可能比索引里的发布版本更新：

dsh plugin --profile <name> add 'git+https://github.com/Natsubrei/dsh-comfyui-panel.git#<commit>'

dsh plugin 会链接或安装包，并把它追加到配置档的 bundle 列表。配置档已经在运行的话，重启 DSH；bundle 变更后，客户端需要硬刷新。

从 npm 装。 包已发布。npm 上不一定有索引里的每个版本，在意版本就用市场：

dsh plugin --profile <name> add dsh-comfyui-panel

然后配置上游，如果不是 127.0.0.1:8188 的话，再往下读面板本身。

功能

- 在 DSH 源下通过 /comfyui/ 提供真正的 ComfyUI 前端，走带鉴权的反向代理（HTTP + WebSocket）。
- 右侧边栏加一个 ComfyUI 标签页。标签页按会话隔离，可全屏使用；它用同源 iframe 加载 /comfyui/，第三方节点保留自己的 UI。
- 把 iframe 里的编辑器桥接到 Host：window.comfyAPI.app.app 一就绪，面板就定期序列化 UI 工作流，从实时节点构建语义投影（id、类类型、控件名与值、输入来源、选中项），向 app.graphToPrompt() 要 API 提示词，再把这三样 POST 到 /api/comfyui/state。
- 订阅内嵌编辑器自己的事件总线（app.api，一个 DOM EventTarget），把精简的事件流转发到 /api/comfyui/events（队列状态、execution_start、executing、progress、executed、execution_success / execution_error / execution_interrupted），Host 不用轮询就能看到运行。ComfyUI 把这些事件发给提交提示词的那个 socket，所以面板转发编辑器的连接，不自己另开一个。
- 在每个已同步工作流的会话的智能体上下文中注册十二个模型工具。其他会话看不到任何 ComfyUI 工具：
- comfyui_status —— 上游可达性、面板连接、工作流摘要、持久化后端、supervisor 状态，以及最近一次运行。
- comfyui_graph_read —— 语义投影：每个节点的 id、type、title、mode、widgets（name -> value）和 inputs（name -> "<sourceNodeId>:"）。layout=true 返回画布框以及重叠判定，full=true 返回原始 UI 工作流和 API 提示词。
- comfyui_run —— 提交已同步的 API 提示词并返回 prompt_id；可选等待历史记录。
- comfyui_progress —— 面板事件（当前节点、步骤进度、错误）、运行记录，以及实时的 /queue 快照。
- comfyui_edit —— 通过 Host → 面板命令通道，在打开的面板内添加、删除、移动、重连节点并设置 widget 值。一批操作按顺序应用，并返回操作后留下的节点数和连线数，因此半途失败的编辑在结果里可见。
- comfyui_screenshot —— 把面板的编辑器画布序列化为磁盘上的 PNG 并返回路径；用 read_image 打开它，就能看到用户看到的图。
- comfyui_node_info —— 缓存的 /object_info 查询，用于查类类型和输入名。
- comfyui_workflow_save —— 以某个名字保存已同步的工作流；重用名字会替换该槽位。
- comfyui_workflow_list —— 已保存的槽位，含节点数/连线数，以及每个槽位的创建时间和最后写入时间。
- comfyui_workflow_load —— 用已保存的工作流替换打开面板的图并同步；和 comfyui_edit 一样需要面板。
- comfyui_workflow_export / comfyui_workflow_import —— 从已保存的槽位（或会话的图）写出 UI 工作流 JSON 文件，或把一个文件读回槽位。路径按会话工作区解析，工作区之外的路径会被拒绝。
- 给这些会话加一行运行时上下文摘要，例如 ComfyUI: rev 14 · "deepseek-chan-emoji" · 9 nodes · 9 links · selected 7 · panel open. 引号部分是工作流的名字，只有图有名字时才出现。
- 一张图只用一个名字。保存或加载具名工作流时会给会话命名，面板栏会显示它；当 ComfyUI 的用户数据里存在 <name>.json 时，编辑器自己的标签页也会改名，这样面板和内嵌编辑器就不会再对「当前打开的是哪个工作流」各执一词。
- 通过 ctx.storageDomain（域 dsh_comfyui）持久化每个会话的工作流、API 提示词、投影和名字，因此 Host 重启不会丢失图。存储失败时降级为内存，不阻塞桥接。具名工作流存放在同一域的 workflows 表中。
- 从面板管理 ComfyUI 进程。Server 区域可以启动、停止、重启 ComfyUI，记住检出目录，还能启动与 DSH 一起使用。它接管已在运行的服务器，不会另起一个副本。无需配置配置档。

配置

插件包自带的补丁 cordis.patch.yml：

- insert:
- id: dsh-comfyui-panel
name: dsh-comfyui-panel
config:
upstream: http://127.0.0.1:8188
prefix: /comfyui

要改 upstream，就在你配置档的 cordis.patch.yml 里用同一个 id 覆盖这一行。补丁会替换整行 config，所以 prefix 也要一并重写。prefix 固定为 /comfyui：面板和 ComfyUI 前端都从这个路径推导 API 基址，换成别的值插件会加载失败。

upstream 指向 ComfyUI 服务器。优先用回环地址。代理转发前会剥掉 DSH 会话 cookie（dsh-auth-…），其余 cookie 和 Authorization 照常转发。只把它指向你信任的服务器。详见 SECURITY.md。

进程管理无需配置：打开面板的 Server 区域，指向 ComfyUI 目录（含 main.py 的文件夹；常见位置会自动识别），按 Start。命令由该目录推导（Unix 上是 .venv/bin/python，Windows 上是 .venv/Scripts/python.exe，否则用 python3 或 python），参数由配置的 upstream 端口推导，所以面板无法执行任意命令。目录和 Start with DSH 开关存在插件自己的 dsh_comfyui 域里，不在 DSH 配置档里。

进阶场景下，插件行仍接受 supervise 块，启动时优先使用：

supervise:
enabled: true
command: /opt/ComfyUI/.venv/bin/python
args: [main.py, --listen, 127.0.0.1, --port, '8188']
cwd: /opt/ComfyUI
restartDelayMs: 5000
maxRestarts: 5
probeIntervalMs: 20000
startTimeoutMs: 120000
logPath: /var/log/comfyui/comfyui.log

启用该块时 cwd 必填；缺值会让插件加载失败，而不是悄悄永不启动 ComfyUI。command 默认 python3，args 默认 main.py --listen 127.0.0.1。若 upstream 已能响应 /system_stats，就直接接管（state: external），不再另起进程。卸载插件只会停掉它自己启动的进程。

要求

- 运行中的 ComfyUI，前端为标准 comfyui-frontend-package 构建（相对路径 ./assets/...，api_base 由路径推导）。
- DSH Web 配置档挂载了 storage + storage-json + storage-domain（默认配置档已包含）。缺了它们，工作流只留在内存里。
- 面板依赖同源 iframe 和 window.comfyAPI.app.app。后者是 ComfyUI 前端暴露的旧版兼容垫片，不是稳定的公开 API。超出本里程碑的用法请锁定 ComfyUI 前端版本。插件实际用到什么、升级后如何重新推导，见 docs/comfyui-bridge.md；面板最后一次验证对应的是前端 1.57.1。当 ComfyUI 报告的前端版本与它不同时，面板会显示一条提示，并继续工作。如果服务器没有提供该字段，则不做处理。
- 接管一个已在运行的 ComfyUI（这样重新加载后 Stop 和 Restart 仍然可用）需要 Linux 的 /proc 或 lsof。两者都没有时，该服务器保持外部状态。从面板启动 ComfyUI 则不需要这两个工具中的任何一个。

不装 ComfyUI 也能试

仓库里附带了一个 mock 上游，因此不用 torch 也能测试 proxy/iframe/bridge：

node test/mock-comfyui.mjs

然后在会话里打开 ComfyUI 标签页，等待出现 Connected。mock 页面暴露一个单节点工作流。comfyui_run 应返回 p1。在 8188 端口启动真正的 ComfyUI 之前，先停掉 mock。

运行检查：

npm install # once: typescript and @types/node for the type check
npm run typecheck # checkJs over the plugin, the tests and the scripts
npm test # checks, host smoke, editor ops, hygiene, market index
npm run contract # real DSH runtime, needs ../deepseek-harness
npm run ui # live panel in a headless browser, needs a running dsh web
npm run shot -- workflow.json # render a workflow file to a PNG

npm test 覆盖 proxy、重定向、资源缓存、工作流桥和事件桥、会话级工具与摘要、投影回退、跨两个 Host 实例的持久化、编辑与已保存工作流的往返、由面板管理真实子进程的启动/停止/重启，以及 supervisor 的接管路径。
它会打印 host smoke test passed。当 ../deepseek-harness（或 DSH_ROOT）处有一份构建好的 DeepSeek Harness 检出时，contract 也会作为 npm test 的一部分运行；CI 里没有这份检出，所以 CI 会跳过它。contract 把插件挂载到真实的 Cordis 上下文、ToolRuntime、原生工具执行器、SystemPrompt 和 HostConnectionService 旁边，因此非法的 Fetch 路径或注册表拒绝的工具 schema 会在本地就失败，而不是等到安装时才暴露。npm test 和 npm run typecheck 就是 pre-commit 钩子运行的内容；重新加载和日志步骤见 AGENTS.md。不在这台机器上时，拉取请求能运行哪些内容，见 CONTRIBUTING.md。Host smoke 会绑定五个连续端口；设置 DSH_COMFYUI_TEST_PORT 可以平移这段端口，让两份检出同时跑测试套件。

npm run ui 是浏览器检查：它在无头 Chromium 里打开 GUI，把面板放进一个临时会话，然后断言面板可观察到的行为——编辑器能启动，计数器描述屏幕上的图，缩放不算编辑，改一个 widget 只让 revision 增加一次，编辑器事件能到达状态栏，Host 学到了编辑器的 socket id，Fit 能把图框进视野。它需要已安装 Chromium 系浏览器，但不会安装任何东西；见 test/ui/README.md。npm test 还会扫描目录树和整段历史都按机器相关路径处理，所以只要混进一个 home 目录，就会在发布前失败。

npm run shot -- workflow.json 把工作流文件渲染成 PNG，不需要 DSH 会话：它把图加载进真实的 ComfyUI 前端，按编辑器的方式取景，写出图片，并打印出重叠或间距小于 16 像素的框（出现这种情况时退出码为 2）。用它判断布局文件，或者用 comfyui_screenshot 处理面板里已经打开的图。

当前限制

- 编辑操作要求 ComfyUI 面板在同一会话中打开；命令通道是长轮询，面板在 iframe 内应用操作。comfyui_workflow_load 也有同样要求；save、list、export、import 只在已经同步或恢复过工作流的会话里，才能在面板关闭时工作。导出和导入按该会话的工作区解析路径，拒绝工作区之外的路径。
- 保存的工作流会替换整张图；没有合并、撤销，也没有按槽位的修订历史。保存同名会覆盖之前的内容。
- comfyui_edit 不校验图的语义；错误的编辑会在 ComfyUI 把图转换成提示词时被拒绝。
- 同步基于轮询（标签页可见时大约每秒一次）。
- 从未打开过面板的会话看不到 ComfyUI 工具。Host 重启后，持久化的会话会重新拿到这些工具；全新会话在第一次面板同步时拿到。
- 运行的 save/cancel 尚未暴露；comfyui_run 只负责排队。
- 面板是 iframe，不继承 DSH 主题 token；这是为 UI 工作流保真和第三方节点 UI 有意做的例外。
- 执行事件从编辑器自己的总线转发，所以进度和错误只在面板挂载期间存在；面板打开前启动的运行会显示队列条目，但没有步骤进度。
- 插件只是接管的 ComfyUI 在插件卸载后继续运行：那个进程不是它启动的，重载后它也分不清自己的幸存进程和你手动启动的服务器。想让它停掉，先从面板停止；插件自己拉起的子进程会在卸载时停止。
- 进程管理器分不清卡死的 ComfyUI 和正在长时间生成、不再响应 /system_stats 的 ComfyUI；健康检查重启应按工作负载调参。
- 插件无法接管的 upstream——叫不出名字的 pid，或从不同目录运行的进程——保持 external：插件从不停止它，面板隐藏 Stop/Restart。能接管的会拿到这些按钮，但插件卸载后仍继续运行（见上一条）。给 pid 命名需要 Linux /proc 或 lsof；Windows 可以从面板启动 checkout，那里已经在运行的服务器保持 external。
- iframe 与 DSH 同源，没有沙箱，所以自定义节点 UI 以 DSH 页面的身份运行。见 SECURITY.md。

设计说明

- UI 工作流始终是权威来源。 API 提示词由真实的 graphToPrompt() 生成；投影是一份只读视图，基于同一批节点构建，因此模型不会把另一份有损的图表示当作真相。
- 状态存放在插件里。 工作流通过一条领域 KV 记录在重启后存活（sessionId -> { workflow, prompt, semantic, revision, name, nameSource }，其中 nameSource 表示名字来自编辑器的工作流文件还是来自工具），最多保留最近更新的 20 个会话。模型只能看到投影和自己的编辑结果。
- revision 跟踪的是编辑，不是视口。 前端会把 extra.ds（缩放/平移）序列化进每个工作流，所以 Host 在比较和存储前先把它剥掉：滚动、缩放或调整面板大小都不会改变 rev，而真实编辑仍会推进它。
- 工具跟随会话。 注册发生在 agent.ctx 上，因此智能体作用域的工具列表和提示词上下文决定可见性；插件卸载时，通过同一条 effect 链完成注销。
- 不改核心，也不改 ComfyUI。 代理、对 comfyAPI.app.app 的 iframe 访问，以及命令通道，就是集成的全部。