ComfyUI API与自定义节点：从可运行工作流到可靠生产链¶
ComfyUI界面适合看见节点如何连接，API适合重复执行已经稳定的流程。二者不是高低级关系：当你还在理解模型、输入和节点职责时，界面更透明；当同一套工作流已经人工验证，需要为多个镜头替换有限参数时，API才开始节省劳动。
本篇不要求你立即部署或下载模型。《回声舱》的工作流、参考和媒体多数仍是教学规格，不能因为项目中出现JSON和提示文件就声称已经在本机或AutoDL跑通。
一、先理解节点图中的数据流¶
节点图不是一张“越复杂越专业”的海报，而是一组有类型的输入和输出。加载模型节点提供推理所需组件；文本、图片、音频等节点提供条件；采样或生成节点把条件与模型组合；解码、预览和保存节点把内部表示转成可见文件。连线表示数据依赖，不表示镜头叙事顺序。
初学者应先能回答五个问题：哪一个节点决定模型版本；哪一个节点接收首帧或主体参考；正向与限制性描述在哪里；时长、尺寸、帧率和种子由谁控制；最终文件由哪个节点保存到哪里。若仍需逐个点击猜测，就不要急着用API批量提交。
相同名字的节点可能来自不同扩展，输入字段也可能随版本改变。截图只能帮助识别大致布局，不能作为机器可执行的唯一备份。真正的可恢复基线需要工作流文件、依赖清单、模型标识、自定义节点版本和一次已验证输出的记录。
二、界面工作流与API工作流不是同一个文件语义¶
界面保存的工作流主要服务于再次打开和编辑，往往包含节点位置、颜色和界面状态；API格式主要表达服务器执行所需的节点、输入和引用。某些版本可以直接导出API格式，但仍要实际检查：节点编号是否稳定，输入图像路径怎样传递，保存节点是否存在，扩展节点是否能在目标环境加载。
API工作流中，每个节点通常以标识为键，记录类类型和输入。输入既可以是文字、数字和布尔值，也可以引用另一个节点的某个输出。这里最危险的错误不是JSON语法，而是“字段存在但语义错了”：把秒数写进帧数字段、把首帧接到普通图像参考、把保存前缀当作绝对路径，服务器都可能接受却产生错误结果。
因此先为工作流建立补丁清单，只允许修改少数已知字段，例如提示文本、种子、输入图名、输出前缀和经过验证的时长参数。模型节点类型、连线和保存结构属于冻结基线，不应在批量循环中临时改写。补丁工具遇到未知节点或字段必须拒绝，而不是“尽量猜一个相近字段”。
三、建立实验环境与生产环境¶
comfy-lab用于升级、安装节点、替换权重和验证新工作流；comfy-prod只运行已经冻结的组合。这两个名字可以对应两个目录、两个虚拟环境或两个远端实例，重点是风险隔离。不要在一部长片进行到一半时更新所有自定义节点，再期待旧工作流保持完全相同。
生产基线至少记录：操作系统和GPU环境、Python与核心框架版本、ComfyUI提交或发布版本、自定义节点来源与版本、模型文件名与校验和、工作流版本、关键设置和验证日期。仅记录“最新版”无法恢复，因为最新版会移动；仅记录模型显示名也不足以区分不同权重文件。
升级流程分四步：复制生产基线到实验环境；用小型测试资产运行代表性工作流；比较加载、速度、输出规格和视觉差异；人工决定是否提升为新生产基线。旧生产环境至少保留到新基线完成一轮真实任务。回退不是失败，而是版本管理的正常能力。
四、提交、排队、历史和输出是四个状态¶
API客户端把工作流发送给服务器后，第一份响应通常只说明请求是否被接收，并返回任务标识。它不证明GPU已经开始，不证明所有节点执行成功，更不证明文件已经写完。客户端必须用任务标识查询队列或历史，识别完成和节点错误，再从历史记录中定位真实输出。
一个可靠状态机可以包含：prepared表示输入和工作流已验证；submitted表示服务接受任务；running表示任务正在执行；completed表示服务器报告结束；downloaded表示输出已回传；verified表示文件可读且技术规格通过；reviewed表示人完成观看；approved表示被指定用途采用。状态只能依据对应证据前进。
服务器返回node_errors为空，最多说明提交时没有发现这类节点错误。运行中仍可能显存不足、依赖崩溃、输入丢失或输出节点失败。反过来，终端出现异常文字也不必立刻判定整个任务失败，应以该任务的历史、输出和文件检查为准。诊断要绑定任务标识和时间，不能从一大段混合日志中随意挑一句。
五、输入上传与路径边界¶
本地客户端和远端ComfyUI不共享同一文件系统。Windows上的D:\film\frame.png对AutoDL Linux服务并不存在；API需要先上传、挂载或把文件放入服务器允许的输入目录，再在工作流中引用服务器认识的名称。把本地绝对路径直接写进JSON是最常见的小白错误之一。
上传后记录原文件校验和、服务器名称和任务用途。若服务会自动改名，必须使用返回值更新任务副本，不从界面猜测名称。对首帧、尾帧、主体参考和音频参考分别记录职责，禁止因为文件都在输入目录就交换使用。
输出路径同样受服务器规则约束。保存前缀用于组织任务，不应接受..或任意绝对路径。下载时把服务器文件名映射到本地镜头ID和版本，先写临时文件，核对大小和校验后再移入正式候选目录。网页错误页、登录页或中断内容也可能以二进制形式下载，扩展名不能证明媒体类型。
六、参数补丁要保护工作流结构¶
最安全的批量策略是“基线工作流加任务补丁”。每次运行从只读基线生成独立副本，根据白名单修改字段，再保存任务快照。不要让第一轮修改后的JSON成为第二轮输入，否则微小变化会在循环中累积，最终无法解释某个候选来自什么基线。
补丁前验证节点类型与预期一致。例如编号42今天是文本编码节点，升级或重新导出后可能变成加载图像节点；仅凭编号写入字符串会产生隐蔽错误。白名单应同时检查节点标识、类类型、字段名和数据类型。补丁后重新解析整个工作流，并生成“字段旧值—新值”差异摘要供人确认。
随机种子需要记录实际值和策略。固定种子帮助在同一实现环境中比较单变量，但不是跨模型、跨版本永久复现码；随机种子适合探索，却必须把服务最终使用的值写回日志。所谓“只改一个变量”还要求模型、工作流、输入资产、尺寸、时长和软件环境保持不变。
七、队列控制、并发与显存¶
批量不等于同时提交全部镜头。并发数量取决于显存、模型加载方式、服务限制和费用风险。对个人项目，先用单任务闭环验证，再逐步增加队列；若第一个任务已经失败，后面七个相同错误任务只会放大浪费。
客户端应限制在途任务数量，记录排队顺序，并允许安全停止“尚未提交”的任务。取消服务器任务前确认目标ID，不用“清空所有队列”处理一个镜头的错误。多个使用者共享服务器时，尤其不能把他人的任务误删。
显存不足不只是把分辨率调低。要先确认模型和节点是否按预期加载、是否残留其他任务、精度与卸载策略是否改变、输入长度和批量是否超出基线。每次只改变一个主要因素并重试；若为了跑通同时换模型、尺寸、节点和输入，就失去了诊断价值。
八、故障从最早错误层级查起¶
第一类是加载错误：缺少自定义节点、模型文件不存在、版本接口不兼容。它们应在提交前或任务开始时暴露，修复目标是环境和依赖。第二类是运行错误：显存、形状、数据类型或节点内部异常，需要绑定具体节点与任务。第三类是输出错误：任务结束但保存节点没有产生预期文件，检查保存配置和历史输出。第四类是内容失败：文件技术正常但身份、动作或空间不成立，回到镜头设计和生成变量，不把它当服务器故障。
建立最小复现时，复制工作流，换成无隐私的小型输入，删去与错误无关的分支，仍保留能够触发问题的最少节点。最小复现文件可以进入实验记录；完整生产工作流可能包含私人路径和资产，分享前必须清理。社区求助时提供版本、节点名、完整错误和最小复现，不上传密钥或未授权素材。
九、自定义节点何时值得写¶
如果已有节点能稳定完成任务，只是连线稍多，不必为了“更专业”写自定义节点。适合封装的场景是：一个经过验证的纯数据变换被许多工作流重复使用；输入输出类型清楚；失败可以给出明确错误；维护收益高于新增依赖成本。创作判断和批准状态不适合藏进节点内部。
节点接口要小。输入名称表达语义，给出合理默认值和范围；输出类型稳定；错误消息说明缺少什么以及在哪个阶段失败。不要让节点静默寻找任意目录、联网下载权重或覆盖用户文件。若确实需要网络或写入，在文档中显式说明目标、权限、缓存和失败恢复。
节点升级可能改变类名、字段和行为。生产项目应固定来源版本，并保存许可证信息。把第三方节点仓库加入环境不等于它的许可证自动覆盖模型和输出素材；代码许可、模型许可和生成内容的使用条件要分别核对。
十、从任务完成到媒体验收¶
下载视频后，先做技术探测：容器、编码、宽高、时长、帧率、音轨、文件大小。再实际解码首帧、中间帧和尾帧，最后正常速度观看。技术检查回答“能否读取和交付”，人工观看回答“是否完成镜头职责”。二者都通过后，才允许进入候选或批准流程。
对《回声舱》SH-001，API链路的技术成功不能证明旋钮旋转、静电触发和停手顺序成立；对SH-005，音轨存在也不能证明呼吸、视线、口型和决定协调。每个镜头仍按第8—9章的停止条件人工选择。自动化只减少搬运和漏记，不替导演批准。
远端操作环境：AutoDL SSH/Linux。下面只表示诊断方向，不是要求立即执行，也不包含模型下载。
执行环境：AutoDL SSH / Linux
pwd
python --version
nvidia-smi
本地回传和教材检查环境：Windows PowerShell。
执行环境：Windows PowerShell
python scripts/validate_project.py .\demo\echo-cabin
十一、《回声舱》任务清单示范¶
每个任务副本至少记录镜头ID、基线工作流ID、输入资产及校验、补丁摘要、实际模型版本、种子、尺寸、时长、提交任务ID、服务器输出、本地输出和各阶段状态。SH-001应使用与镜头表一致的I2VA模式和工作流标识；如果工作流需要首尾帧，镜头规格和提示也必须明确，不允许客户端暗中升级模式。
失败示范：“接口返回200，标记SH-001完成。”这里缺少历史、输出和媒体证据。改写为：“任务已被接受，ID为某值；历史尚未报告完成；未发现本地文件；状态保持submitted。”另一种失败是文件可播放就自动改approved，它越过了创作判断。正确状态最多到verified，随后由人观看并记录选择理由。
原创片迁移练习：选一个低风险镜头，先在界面中完成一次可解释基线；导出API格式并逐项找到允许补丁的字段；用虚拟输入测试路径和错误；只提交一个真实任务；沿状态机保存证据；回传后做技术和人工两层检查。任何一层无法解释，就停在该层修复，不扩大到批量。
本篇检查表¶
- 能否说明每个关键节点的输入、输出与职责。
- API工作流是否经过实际检查，而非只从界面截图推测。
- 生产基线是否固定ComfyUI、节点、模型和工作流版本。
- 补丁是否使用节点、类型、字段和数据类型白名单。
- 本地与远端路径是否通过上传和映射明确转换。
- 提交、运行、完成、下载、技术通过和批准是否分开。
- 轮询、并发、重试和费用是否有上限。
- 输出是否做元数据、解码和正常播放检查。
- 自定义节点是否最小、可诊断、无隐蔽写入或下载。
- 升级是否先经过实验环境，并能回退到旧生产基线。