拓冰网站定制 
人工智能大模型媒体生成本地部署【免费下载链接】ComfyUIThe most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.项目地址https://gitcode.com/GitHub_Trending/co/ComfyUI点击查看免费下载本文基于仓库根目录 AGENTS.md 编写系统梳理 ComfyUI 的工程风格、架构边界、内存与设备行为、节点设计及评审习惯等核心开发守则。无论你是想为 ComfyUI 贡献新模型、新节点还是排查执行引擎与显存问题都能从中掌握项目对代码改动的最基本要求与底层实现依据。读完本文你将理解如何以“最小改动、最窄路径”的方式开发并学会在 ComfyUI 的源码与测试中找到印证。一、工程风格小改动、窄路径、少依赖AGENTS.md 开篇定义了 ComfyUI 的核心工程价值观这是评估一切 PR 是否合格的底色改动要小且直接大多数修复应只触及能解释 bug、性能问题、dtype 问题、模型格式问题或用户可见行为的最窄代码路径。改动文件数量越少越好一个波及大量文件的改动更可能是坏改动除非更大的范围是直接必需的。实用主义优先于架构工程只有在新抽象能消除真实的重复逻辑、或与 ComfyUI 既有模式吻合时才引入抽象。少加依赖除非绝对必要不要给 ComfyUI 添加新的第三方依赖。这与 requirements.txt 中精简的依赖面保持一致。激进删除过时代码当新基础设施使旧代码无用后删除失效回退路径、迁移路径、未用选项、调试打印和不再需要的兼容分支。代码如果不服务于当前行为就应该被移除不留死分支、不可达代码或从未被调用的函数。快速回退当问题破坏用户体验时宁可移除一个有问题的功能路径也不要保留复杂的不完整修复。保护兼容性除非改动明确就是替换它们否则保持现有 API、节点名、模型加载行为、文件布局与工作流兼容当兼容性明确不在范围内时则彻底移除兼容别名、重复节点、遗留入口和预设包装而不是保留多种做同一件事的并行方式。代码要“手工感”看起来像通用 AI 生成的代码会被自动拒绝——不必要的辅助层、含糊命名、模板化注释、没有真实失败场景的防御分支、大范围重写、无视本地风格的代码都不合格。这套规则在仓库结构中有直观体现核心逻辑集中在comfy/模型、采样、执行、comfy_extras/节点与模型集成、app/资产管理、应用生命周期等分层清晰的目录中新功能应当被放进最贴合其归属的层而不是四处蔓延。二、架构边界每一层只拥有自己的概念AGENTS.md 对分层有明确要求每一层只关注自己拥有的概念不得因为方便传数据就把 UI、API、工作流、队列、持久化、遥测、模型加载、节点、执行等关注点泄漏到无关层。共享核心模块只应依赖底层原语和自身领域概念更上层的产品概念应归属到调用方、适配器、服务或 UI/API 边界。跨边界只传递最窄的数据。避免传递宽泛的 context 对象、请求/会话元数据、id、簿记状态或回调除非接收层确实需要它们来完成自己的职责。身份映射、持久化簿记、历史更新、遥测、响应整形和 UI 状态都应留在各自负责的层中不要为了省去一个合理的边界而把它们塞进无关的共享代码。execution.py是最典型的范例它只应消费 prompt 图与执行相关的状态、产出执行结果与错误不应知道工作流 id、前端 id、持久化 id 或仅属于 API 的概念。查看 execution.py 可以印证这一点——它围绕 prompt 图遍历、节点执行与结果返回组织代码而不持有任何前端或持久化 id 的语义。改多个文件之前先识别能解决问题的最小归属层一个把某功能散布到无关的加载器、节点、执行、服务器和前端代码中的 PR需要有清晰的架构理由。如果某个改动似乎要求一层去理解另一层的私有概念停下来寻找调用方侧的映射、适配器、事件、小而明确的接口或在边界上更窄的数据流。这些边界约束的直接动机是保持执行引擎的可复用性与可测试性让 tests/execution/ 与 tests-unit/execution_test/ 能够以纯粹的执行语义驱动测试。三、无网络请求核心代码的离线红线AGENTS.md 对核心 ComfyUI 的网络访问有近乎绝对的禁令不要向核心 ComfyUI 添加任何发起互联网请求的代码。拒绝在核心中增加上传、遥测、分析、追踪、用量上报、崩溃上报、更新检查、远程配置、feature flag、指标、许可校验或其他任何出站网络请求路径——包括“opt-in / opt-out / 匿名化 / 聚合 / 用户触发”等任何形式的标签这些标签都不能让网络访问变得可接受。模型下载仅在用户明确发起或授权时允许必须限定于所请求的模型产物本身且不得附带遥测、追踪、持久身份标识、无关元数据上传或后台网络活动。仅限本地的行为是允许的但必须停留在用户机器上不得引入网络访问、追踪、持久身份标识或数据收集行为。这意味着 ComfyUI 核心是一个“本地优先”的推理引擎所有与外部服务如各类 API 节点的通信都应位于边界层。仓库中comfy_api_nodes/apis/目录集中封装了各厂商 API 客户端与核心执行路径保持隔离正是这一原则的体现。四、状态所有权与接口契约4.1 状态归属状态与能力标志应放在“拥有该行为的对象”上。避免用getattr(child, ..., default)探测子对象来决定父层的控制流如果父层需要根据某个能力分支应在子对象构造或挂载时初始化一个显式的父层字段。优先使用带清晰默认值的直接属性而不是通过任意的子属性做隐式能力探测。仅当子对象确实拥有被调用的行为、且父层只是简单委托时才使用子对象能力检查。4.2 公共接口契约公共方法必须与调用方期望的接口保持一致不要为单一实现而让共享方法返回额外值、其他形状或哨兵包装除非共享接口被显式更新。修改已有函数时保留当前调用方的调用方式除非同步更新所有调用点与共享接口契约否则不得改变必填参数、参数顺序、返回类型、副作用或错误行为。不要添加“只被存储而从不读取”的兼容参数、标志、属性或构造选项——传递但未使用的值应被删除而不是保留上游或废弃 API 的包袱。不要给共享 helper 添加只有单个调用方需要的模型专属选项一次性行为应放在模型集成边界或仅在选项是连贯的可复用能力时才扩展共享 helper。共享模型接口的实现应接受标准调用契约不得为不消费的可选能力添加模型专属拒绝分支让支持的行为由真正使用这些输入的实现路径决定。如果实现需要为自己的工作流提供辅助值通过私有 helper 或命名清晰的实现专属方法暴露而不是重载公共方法的返回契约。在集成边界规范化第三方/上游返回约定核心代码应收到项目期望的类型与形状而不是被迫处理模型专属的 tuple/list/dict 变体。除非被调用的接口文档明确返回该结构否则避免调用方侧解包如out out[0]。4.3 模型冻结与 Autograd不要在 ComfyUI 代码中添加torch.no_grad、torch.inference_mode或推理模式包装唯一允许的推理模式相关用法是训练路径需要梯度时禁用全局设置的推理模式。不要给模型类添加 freeze / unfreeze / trainability 开关——ComfyUI 模型在推理中始终视为冻结显式冻结功能是冗余的。从推理模型代码中移除仅训练时才有的行为如 dropout但删除时要保持 checkpoint 与 state-dict 兼容如果删除某个模块会改变 state-dict 键、模块顺序或 checkpoint 加载行为应替换为nn.Identity之类的 no-op而不是直接移除槽位。五、Python 风格要求模块级导入保持 import 在模块顶部除非是既有的可选后端探测或需要避免循环导入否则避免内联导入。慎用 try/except不要添加不必要的异常捕获仅在对可选依赖、平台或后端能力探测且程序有可用回退时使用新代码中优先使用具体的异常类型。与依赖版本对齐如果库版本已在 requirements.txt 中固定不要写兼容旧版本的代码移除为已不再官方支持的 PyTorch 版本准备的 workaround典型例子捕获异常后用 float 重跑同一 op若 workaround 没有注释标明仍需要它的确切 PyTorch 版本就删除它。让坏状态清晰失败不支持的模型格式、无效的量化元数据、坏状态应报出明确错误而不是静默产出更低质量的输出。贴合本地风格本代码库容忍长行、简单辅助函数、模块级状态和直接张量操作只要它们让代码更易读。注释精简删除复述代码或描述显而易见行为的无用注释短 TODO 可以保留但要指明具体的缺失后续工作。六、模型、设备与内存行为核心正确性关切这是 AGENTS.md 中篇幅最大、技术含量最高的部分全部内容都以dtype / 设备放置 / VRAM 使用 / offload 行为为核心正确性为前提。6.1 优先复用优化算子改动共享执行或加载代码时要检查 CPU、CUDA、ROCm、MPS、DirectML、XPU、NPU 及低 VRAM 场景的影响。优先使用 ComfyUI 原生格式与既有量化/卸载 helpercomfy.quant_ops、comfy.model_management、comfy.memory_management、comfy.pinned_memory等而不是新增并行代码路径。模型实现必须使用既有优化算子只要某个 Comfy Kitchen 或 ComfyUI 算子能在不改变期望 dtype、设备、内存与接口行为的前提下支持所需数学与张量布局就必须使用它。这是默认实现要求不是可选的后续优化。写模型数学前先检查 Comfy Kitchen、comfy.quant_ops和既有 model helpers 已暴露的算子寻找单输入、配对、融合、布局专属与量化变体若多个优化变体都适用用代表性模型形状做基准选最快的合法路径。只有没有既有优化算子支持所需数学/布局/dtype/设备/autograd/patch 契约时才新增或保留本地实现当优化推理算子不提供可微或可 patch 契约时保留可微或 patch 兼容的回退。使用既有 ComfyUI cast、offload、cleanup helper 处理传入优化算子的参数并保持模型专属的 epsilon、缩放、布局、dtype、设备与输出形状行为。所有模型都应使用 ComfyUI 选择的优化注意力函数。把优化后端函数、分派 helper 与按能力选择的 callable 视为不透明对象高层代码不得通过检查函数身份、名字、模块或实现细节来决定行为同样的“不透明规则”也适用于注意力之外的类似模式——调用方只依赖文档化的接口与结果契约而不是依赖底层选了哪个后端实现。不要使用只复制既有 op 并 upcast 到 float32 的自定义推理 op例如自定义 RMSNorm 变体改用通用 ComfyUI ops 与原生 torch ops。这与 comfy/rmsnorm.py 的存在相印证——RMSNorm 已有共享实现无需重复造轮子。6.2 dtype 与 cast 规则保持计算 dtype、存储 dtype、bias dtype 与原始张量形状元数据不被破坏避免无谓的 cast 与传输。除非优化后端的结果契约明确要求归一化否则不要把它返回的 dtype 转回输入 dtype尤其是要信任所选优化注意力实现遵守其 dtype 契约。默认假设主模型 forward 的输入已在计算 dtype除部分整数输入如某些模型的时间步张量不要添加防御性或便利性 cast——dtype 管道错误应清晰报错而不是被无谓的 cast 掩盖。未被 op 持有、且可能以不同于计算 dtype 初始化的原始模型参数应在 forward/推理代码中用comfy.ops.cast_to_input或comfy.model_management.cast_to在使用时 cast以避免 dtype 不匹配。见 comfy/ops.py 的cast_to_input与 comfy/model_management.py 的cast_to。模型代码不关心自己以什么 dtype 初始化__init__中不应包含针对特定 dtype 的 workaround——这类代码属于负责计算策略的执行或模型管理层。不要执行无谓的设备间传输新分配必须创建在正确的设备与 dtype 上绝不允许“先在 CPU 分配再搬到 GPU”或“先在一个 dtype 分配再转成另一个”。6.3 模型检测规则检查线性权重形状的模型检测代码只能使用第一维——第二维在 NVFP4 或其他 4-bit 量化模型上可能只有原尺寸的一半。模型检测签名必须防护其解引用的每个 state-dict 键不要部分匹配某格式后在提取配置时抛出偶然的KeyError。模型检测检查顺序应从更成熟/更具体的签名到更新/更宽的签名新的宽泛检测器放在通用回退附近避免抢占其他模型家族的优先级。6.4 张量使用纪律核心推理代码避免使用einops改用原生 torch 张量算子reshape、view、permute、transpose、flatten、unflatten、unsqueeze、squeeze。不要把张量当作通用 Python 数据结构元数据、簿记、计数器、标志、形状/填充数学、索引规划、内存估算、控制流决策都应保持为普通 Python 值除非数据必须直接参与张量计算。序列长度、累计偏移、切分索引、窗口计数、切片边界、repeat 计数从计算那一刻起就应保持为 Python int/list不要先建成 CPU/GPU 张量再转回 Python 用于split、tensor_split、索引规划、循环或 cache key。避免为纯标量或结构计算创建临时张量去“借用”张量方法。当条件相关的模型工作在每次去噪步都会重复时若预计算一次能显著提升性能应暴露模型预处理方法并从BaseModel.extra_conds调用参照 LTXAV、Anima 等模式结果走正常 conditioning 通道不要为此添加模型自有缓存、sampler-option 缓存或缓存管理包装。extra_conds是理解这一节的最佳入口它在 comfy/model_base.py 的BaseModel上定义被大量子类重写以注入各自模型的专属条件。例如 Anima 在 comfy/model_base.py 中通过extra_conds预处理 T5 文本嵌入WAN21 系列各变体VACE、Camera、HuMo、Animate、SCAIL 等也在同一文件中用extra_conds注入vace_frames、camera_conditions、audio_embed、pose_latents等条件。这些条件通过comfy/conds.py中的CONDRegular、CONDNoiseShape、CONDCrossAttn、CONDConstant、CONDList等容器统一承载进入采样流程。6.5 内存与缓存管理归属模型代码本身不做内存管理加载、卸载、offload、设备移动、VRAM 策略、缓存生命周期与清理属于模型管理与执行层。对应实现见 comfy/model_management.py 中的free_memory、soft_empty_cache、unload_all_modelscomfy/model_management.py等接口。不要添加跨越多次执行的全局/模块级/类级/单例/模型自有张量或大内存存储临时缓存必须限定在单次执行或单次 forward/encode/decode 调用内在拥有它的顶层调用中分配、通过调用栈显式传递、调用返回时丢弃。遵循 Wan VAE 时间缓存模式为 encode/decode 创建局部缓存如feat_map传入需要它的 block不要保留在模型或全局状态上。该模式在 comfy/ldm/wan/vae.py 有直接实现——feat_map在 encode 开始时创建、随分帧迭代传入 encoder 并更新函数返回后即随作用域释放。跨执行持久缓存应尽量避免仅当占用极小且有清晰的归属与失效机制时才允许。切大张量时若切出张量的生命周期超出当前函数作用域应复制该切片长生命周期 view 会拖住大后备张量而小拷贝能更早释放内存。数学自然匹配时使用融合/复合 torch 算子如addcmul减少 Python 与 torch 分派开销是合理优化但不得掩盖代码或改变 dtype/device 行为。优化时偏好小而可衡量的改动更少分配、更少设备传输、更低峰值内存、更好批处理或使用更快的既有后端算子。6.6 模型初始化与结构模型__init__中对从 state dict 填充的参数/缓冲占位符优先用torch.empty而不是torch.zeros等零初始化如果某分配不来自 state dict 且对推理无用就不要包含它。存储于并从 state dict 填充的nn.Parameter张量应以torch.empty初始化而不是零、随机或其它“有意义”的初始化——模型初始化应描述模块结构而不是捏造 checkpoint 拥有的张量内容从 state dict 加载的参数与缓冲不得手动初始化、重赋值或填回退值除非该值在无对应 checkpoint 键时确实被使用。若模型类__init__有operations参数假设operations永不为None不要为缺失的operations添加回退分支或默认 torch ops。不要给模型、模型 block 或模型 ops 相关类添加不必要的参数构造函数与 forward 签名只应携带该对象推理实际需要的值。实现新模型组件前先搜索既有模型代码中是否已有提供该行为的类或 helper 并复用。6.7 Latent 布局与 DiT 尺寸处理模型原生的 latent 布局处理应留在模型或 latent-format 归属者内而不是 helper 节点不要为了满足模型 forward 而在节点或调用方侧适配器里压缩、扩展、打包或解包 latent 维度——模型路径应消费并返回该模型家族的原生 latent 形状。DiT 模型应接受不是 patch-size 整倍数的 latent 尺寸对每个 patchified 的目标或参考输入使用comfy.ldm.common_dit.pad_to_patch_size随后只把目标输出 crop 回原始尺寸。该 helper 在 comfy/ldm/common_dit.py 中实现按 patch_size 对空间维度做取整补零默认padding_modecircularjit trace/script 时回退reflect。避免防御性的形状与配置检查——它们只是替换了下方张量算子本会给出的清晰报错只在真实边界上能提供实质性更好上下文或防止静默错误输出时才添加显式校验。七、用户输入容忍度能跑就放行优先用用户提供的值完成工作流而不是因为超出推荐/UI 宣传/质量导向的限制就拒绝。只要下游实现能消费该输入就原样传下去即使结果可能较差。例如不要因为节点宣传了更小的推荐最大值就拒绝或截断额外的参考图。不要仅仅为了防止退化、无意义或低质量输出而添加校验错误——坏结果优于让一个本可执行的工作流失效。仅在“原样传递必然导致既有模型或底层算子失败”时才去 resize、pad、clamp、normalize 或改造用户输入做保持执行继续所需的最小调整不要为了证明改动合理而添加模型级校验失败。这一宽容政策不覆盖安全边界路径包含path containment与安全加载模型格式/checkpoint 所需的完整性校验仍然必须执行。这条原则解释了为什么 ComfyUI 的图执行倾向于“宽容消费”图解析与节点执行在 comfy_execution/ 与 execution.py 中完成节点尽量不引入会阻断整条工作流的额外校验。八、节点与用户可见行为8.1 节点约定遵循既有节点约定INPUT_TYPES、RETURN_TYPES、FUNCTION、CATEGORY并通过该文件使用的本地映射注册。这是 comfy_extras/ 与 nodes.py 中所有节点的标准模式。Combo 输入视为不可信凡是会影响文件系统访问的 legacy combo 输入、io.Combo、io.DynamicCombo值在加载/保存边界必须再次用既有的folder_pathsresolver 或 containment helper或固定 allowlist/映射校验。不能只依赖广告的 combo 选项或 prompt 校验。默认保持节点改动向后兼容新增输入要带合理默认值除非请求明确要求避免改变输出类型。模型实现应只添加运行该模型所需的最少节点尽量复用既有节点优先“改造模型去适配既有节点”而不是创建新节点。变量数量的重复输入使用io.Autogrow而不是一排编号的可选 socket当模型有无条目合法路径时把最小值设为 0仅在模型有真实上限时才设上限。该类型在 comfy_api/latest/_io.py 中实现支持模板前缀与最小/最大数量约束。当执行存在不读取某输入的合法路径时将该输入标记为 optional如果某可选输入只用于处理另一个可选输入不要在两者都不提供的路径上强迫用户连接它。8.2 输出与流向约束Conditioning 节点通常只输出 conditioning不要为下游尺寸计算或路由暴露输入或中间图像作为便利输出应使用既有图像路径或专用图像算子。节点只输出自己拥有的值不要为了工作流便利添加 pass-through 输出除非该节点本身就是输出节点既有模型、latent、conditioning 或其他输入应直接流向下一个消费者而不是被原样重新发射。节点只暴露实际读取以产生当前行为的输入不要添加被忽略的占位、pass-through、兼容性或工作流塑形输入。节点级代码不得直接 patch 模型代码任何修改、包装、hook 或改变模型行为的节点行为都必须通过模型 patcher 类完成而不是深入模型内部。模型 patcher 见 comfy/model_patcher.py 的ModelPatcher类。8.3 消息与文档警告与信息消息应短且有可操作性删除嘈杂或误导的消息而不是堆更多日志。文档与 README 改动应简洁、基于事实并与所改行为绑定。九、提交与评审习惯提交信息用简短直白的主语与既有历史风格一致Fix ...、Add ...、Support ...、Remove ...、Update ...、Make ...、Use ...、Disable ...、Bump ...、Revert ...。PR 描述保持简短可评审说明问题、行为改动、跑过的测试避免长篇叙事、实现日记或逐文件总结除非评审者明确需要。每个提交聚焦一个连贯的行为改动依赖 pin、测试与需要它们的代码在不可分割时可放在同一提交。评审时优先关注真实用户影响崩溃、错误的 dtype/device 行为、内存回退、模型加载失败、工作流不兼容、嘈杂或误导的用户可见输出。十、如何在仓库中验证这些规范以上规范并非抽象口号仓库中处处可以找到对应实现供比对执行边界对照 execution.py 与 comfy_execution/ 观察“只消费 prompt 图与执行状态”的边界设计测试见 tests/execution/ 与 tests-unit/execution_test/。conditioning 机制BaseModel.extra_conds与comfy.conds的容器类comfy/conds.py解释了模型如何通过统一接口声明所需条件这与“共享接口契约”一节直接呼应。内存管理归属模型代码不直接管理显存而是由 comfy/model_management.py 统一调度free_memory、soft_empty_cache、unload_all_models等模型实现只需遵循“不持有跨执行缓存”的纪律Wan VAE 的feat_map局部缓存comfy/ldm/wan/vae.py是教科书式范例。优化算子复用comfy.ops.cast_to_inputcomfy/ops.py、comfy.model_management.cast_tocomfy/model_management.py与comfy.ldm.common_dit.pad_to_patch_sizecomfy/ldm/common_dit.py是“优先既有 helper”的直接证据。动态输入io.Autogrowcomfy_api/latest/_io.py是节点设计“用 Autogrow 而非编号 socket”的实现落点。模型加载与检测可对照 comfy/model_detection.py 与 comfy/supported_models.py 检查 6.3 节关于权重形状探测与检查顺序的要求。十一、小结AGENTS.md 的九大章节本质上回答了一个问题在 ComfyUI 这样庞大且快速演进的扩散模型工程中什么才是一次“合格”的改动。它的答案可以浓缩为几句话改动落在最窄的代码路径上每一层只拥有自己的概念核心代码绝不联网状态与接口契约清晰不越界模型实现以 dtype/设备/内存为第一正确性优先复用既有优化算子节点宽容对待用户输入、严格约束自己的输入输出提交信息简短、评审聚焦真实用户影响。对于任何想在 ComfyUI 上做模型集成、节点开发或性能修复的开发者这份规范既是行动清单也是理解这个项目代码组织方式的钥匙。赞分享人工智能大模型媒体生成本地部署【免费下载链接】ComfyUIThe most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.项目地址https://gitcode.com/GitHub_Trending/co/ComfyUI点击查看免费下载相关推荐Kaneo 项目开发指南从架构边界到发布流程的完整协作规范Kaneo 项目开发指南从架构边界到发布流程的完整协作规范 Kaneo 是一个快速、刻意保持简单、支持自托管的一体化项目管理平台Hono API 拥有领域行前端后端Litestream 代码模式与反模式实践指南从架构边界到并发安全的核心开发规范Litestream 代码模式与反模式实践指南从架构边界到并发安全的核心开发规范 Litestream 是一个基于 SQLite WAL 的流式复制工具其代数据库数据同步灾备高可用Comp AI CRM 的 AGENTS.md 全解AI Agent 协作开发的工作区规则、架构边界与工程规范Comp AI CRM 的 AGENTS.md 全解AI Agent 协作开发的工作区规则、架构边界与工程规范 导读 Comp AI CRM 是一个为 AI后端前端CRM人工智能AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ComfyUI 工程规范指南：从架构边界到模型实现的开发守则
人工智能大模型媒体生成本地部署【免费下载链接】ComfyUIThe most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.项目地址https://gitcode.com/GitHub_Trending/co/ComfyUI点击查看免费下载本文基于仓库根目录 AGENTS.md 编写系统梳理 ComfyUI 的工程风格、架构边界、内存与设备行为、节点设计及评审习惯等核心开发守则。无论你是想为 ComfyUI 贡献新模型、新节点还是排查执行引擎与显存问题都能从中掌握项目对代码改动的最基本要求与底层实现依据。读完本文你将理解如何以“最小改动、最窄路径”的方式开发并学会在 ComfyUI 的源码与测试中找到印证。一、工程风格小改动、窄路径、少依赖AGENTS.md 开篇定义了 ComfyUI 的核心工程价值观这是评估一切 PR 是否合格的底色改动要小且直接大多数修复应只触及能解释 bug、性能问题、dtype 问题、模型格式问题或用户可见行为的最窄代码路径。改动文件数量越少越好一个波及大量文件的改动更可能是坏改动除非更大的范围是直接必需的。实用主义优先于架构工程只有在新抽象能消除真实的重复逻辑、或与 ComfyUI 既有模式吻合时才引入抽象。少加依赖除非绝对必要不要给 ComfyUI 添加新的第三方依赖。这与 requirements.txt 中精简的依赖面保持一致。激进删除过时代码当新基础设施使旧代码无用后删除失效回退路径、迁移路径、未用选项、调试打印和不再需要的兼容分支。代码如果不服务于当前行为就应该被移除不留死分支、不可达代码或从未被调用的函数。快速回退当问题破坏用户体验时宁可移除一个有问题的功能路径也不要保留复杂的不完整修复。保护兼容性除非改动明确就是替换它们否则保持现有 API、节点名、模型加载行为、文件布局与工作流兼容当兼容性明确不在范围内时则彻底移除兼容别名、重复节点、遗留入口和预设包装而不是保留多种做同一件事的并行方式。代码要“手工感”看起来像通用 AI 生成的代码会被自动拒绝——不必要的辅助层、含糊命名、模板化注释、没有真实失败场景的防御分支、大范围重写、无视本地风格的代码都不合格。这套规则在仓库结构中有直观体现核心逻辑集中在comfy/模型、采样、执行、comfy_extras/节点与模型集成、app/资产管理、应用生命周期等分层清晰的目录中新功能应当被放进最贴合其归属的层而不是四处蔓延。二、架构边界每一层只拥有自己的概念AGENTS.md 对分层有明确要求每一层只关注自己拥有的概念不得因为方便传数据就把 UI、API、工作流、队列、持久化、遥测、模型加载、节点、执行等关注点泄漏到无关层。共享核心模块只应依赖底层原语和自身领域概念更上层的产品概念应归属到调用方、适配器、服务或 UI/API 边界。跨边界只传递最窄的数据。避免传递宽泛的 context 对象、请求/会话元数据、id、簿记状态或回调除非接收层确实需要它们来完成自己的职责。身份映射、持久化簿记、历史更新、遥测、响应整形和 UI 状态都应留在各自负责的层中不要为了省去一个合理的边界而把它们塞进无关的共享代码。execution.py是最典型的范例它只应消费 prompt 图与执行相关的状态、产出执行结果与错误不应知道工作流 id、前端 id、持久化 id 或仅属于 API 的概念。查看 execution.py 可以印证这一点——它围绕 prompt 图遍历、节点执行与结果返回组织代码而不持有任何前端或持久化 id 的语义。改多个文件之前先识别能解决问题的最小归属层一个把某功能散布到无关的加载器、节点、执行、服务器和前端代码中的 PR需要有清晰的架构理由。如果某个改动似乎要求一层去理解另一层的私有概念停下来寻找调用方侧的映射、适配器、事件、小而明确的接口或在边界上更窄的数据流。这些边界约束的直接动机是保持执行引擎的可复用性与可测试性让 tests/execution/ 与 tests-unit/execution_test/ 能够以纯粹的执行语义驱动测试。三、无网络请求核心代码的离线红线AGENTS.md 对核心 ComfyUI 的网络访问有近乎绝对的禁令不要向核心 ComfyUI 添加任何发起互联网请求的代码。拒绝在核心中增加上传、遥测、分析、追踪、用量上报、崩溃上报、更新检查、远程配置、feature flag、指标、许可校验或其他任何出站网络请求路径——包括“opt-in / opt-out / 匿名化 / 聚合 / 用户触发”等任何形式的标签这些标签都不能让网络访问变得可接受。模型下载仅在用户明确发起或授权时允许必须限定于所请求的模型产物本身且不得附带遥测、追踪、持久身份标识、无关元数据上传或后台网络活动。仅限本地的行为是允许的但必须停留在用户机器上不得引入网络访问、追踪、持久身份标识或数据收集行为。这意味着 ComfyUI 核心是一个“本地优先”的推理引擎所有与外部服务如各类 API 节点的通信都应位于边界层。仓库中comfy_api_nodes/apis/目录集中封装了各厂商 API 客户端与核心执行路径保持隔离正是这一原则的体现。四、状态所有权与接口契约4.1 状态归属状态与能力标志应放在“拥有该行为的对象”上。避免用getattr(child, ..., default)探测子对象来决定父层的控制流如果父层需要根据某个能力分支应在子对象构造或挂载时初始化一个显式的父层字段。优先使用带清晰默认值的直接属性而不是通过任意的子属性做隐式能力探测。仅当子对象确实拥有被调用的行为、且父层只是简单委托时才使用子对象能力检查。4.2 公共接口契约公共方法必须与调用方期望的接口保持一致不要为单一实现而让共享方法返回额外值、其他形状或哨兵包装除非共享接口被显式更新。修改已有函数时保留当前调用方的调用方式除非同步更新所有调用点与共享接口契约否则不得改变必填参数、参数顺序、返回类型、副作用或错误行为。不要添加“只被存储而从不读取”的兼容参数、标志、属性或构造选项——传递但未使用的值应被删除而不是保留上游或废弃 API 的包袱。不要给共享 helper 添加只有单个调用方需要的模型专属选项一次性行为应放在模型集成边界或仅在选项是连贯的可复用能力时才扩展共享 helper。共享模型接口的实现应接受标准调用契约不得为不消费的可选能力添加模型专属拒绝分支让支持的行为由真正使用这些输入的实现路径决定。如果实现需要为自己的工作流提供辅助值通过私有 helper 或命名清晰的实现专属方法暴露而不是重载公共方法的返回契约。在集成边界规范化第三方/上游返回约定核心代码应收到项目期望的类型与形状而不是被迫处理模型专属的 tuple/list/dict 变体。除非被调用的接口文档明确返回该结构否则避免调用方侧解包如out out[0]。4.3 模型冻结与 Autograd不要在 ComfyUI 代码中添加torch.no_grad、torch.inference_mode或推理模式包装唯一允许的推理模式相关用法是训练路径需要梯度时禁用全局设置的推理模式。不要给模型类添加 freeze / unfreeze / trainability 开关——ComfyUI 模型在推理中始终视为冻结显式冻结功能是冗余的。从推理模型代码中移除仅训练时才有的行为如 dropout但删除时要保持 checkpoint 与 state-dict 兼容如果删除某个模块会改变 state-dict 键、模块顺序或 checkpoint 加载行为应替换为nn.Identity之类的 no-op而不是直接移除槽位。五、Python 风格要求模块级导入保持 import 在模块顶部除非是既有的可选后端探测或需要避免循环导入否则避免内联导入。慎用 try/except不要添加不必要的异常捕获仅在对可选依赖、平台或后端能力探测且程序有可用回退时使用新代码中优先使用具体的异常类型。与依赖版本对齐如果库版本已在 requirements.txt 中固定不要写兼容旧版本的代码移除为已不再官方支持的 PyTorch 版本准备的 workaround典型例子捕获异常后用 float 重跑同一 op若 workaround 没有注释标明仍需要它的确切 PyTorch 版本就删除它。让坏状态清晰失败不支持的模型格式、无效的量化元数据、坏状态应报出明确错误而不是静默产出更低质量的输出。贴合本地风格本代码库容忍长行、简单辅助函数、模块级状态和直接张量操作只要它们让代码更易读。注释精简删除复述代码或描述显而易见行为的无用注释短 TODO 可以保留但要指明具体的缺失后续工作。六、模型、设备与内存行为核心正确性关切这是 AGENTS.md 中篇幅最大、技术含量最高的部分全部内容都以dtype / 设备放置 / VRAM 使用 / offload 行为为核心正确性为前提。6.1 优先复用优化算子改动共享执行或加载代码时要检查 CPU、CUDA、ROCm、MPS、DirectML、XPU、NPU 及低 VRAM 场景的影响。优先使用 ComfyUI 原生格式与既有量化/卸载 helpercomfy.quant_ops、comfy.model_management、comfy.memory_management、comfy.pinned_memory等而不是新增并行代码路径。模型实现必须使用既有优化算子只要某个 Comfy Kitchen 或 ComfyUI 算子能在不改变期望 dtype、设备、内存与接口行为的前提下支持所需数学与张量布局就必须使用它。这是默认实现要求不是可选的后续优化。写模型数学前先检查 Comfy Kitchen、comfy.quant_ops和既有 model helpers 已暴露的算子寻找单输入、配对、融合、布局专属与量化变体若多个优化变体都适用用代表性模型形状做基准选最快的合法路径。只有没有既有优化算子支持所需数学/布局/dtype/设备/autograd/patch 契约时才新增或保留本地实现当优化推理算子不提供可微或可 patch 契约时保留可微或 patch 兼容的回退。使用既有 ComfyUI cast、offload、cleanup helper 处理传入优化算子的参数并保持模型专属的 epsilon、缩放、布局、dtype、设备与输出形状行为。所有模型都应使用 ComfyUI 选择的优化注意力函数。把优化后端函数、分派 helper 与按能力选择的 callable 视为不透明对象高层代码不得通过检查函数身份、名字、模块或实现细节来决定行为同样的“不透明规则”也适用于注意力之外的类似模式——调用方只依赖文档化的接口与结果契约而不是依赖底层选了哪个后端实现。不要使用只复制既有 op 并 upcast 到 float32 的自定义推理 op例如自定义 RMSNorm 变体改用通用 ComfyUI ops 与原生 torch ops。这与 comfy/rmsnorm.py 的存在相印证——RMSNorm 已有共享实现无需重复造轮子。6.2 dtype 与 cast 规则保持计算 dtype、存储 dtype、bias dtype 与原始张量形状元数据不被破坏避免无谓的 cast 与传输。除非优化后端的结果契约明确要求归一化否则不要把它返回的 dtype 转回输入 dtype尤其是要信任所选优化注意力实现遵守其 dtype 契约。默认假设主模型 forward 的输入已在计算 dtype除部分整数输入如某些模型的时间步张量不要添加防御性或便利性 cast——dtype 管道错误应清晰报错而不是被无谓的 cast 掩盖。未被 op 持有、且可能以不同于计算 dtype 初始化的原始模型参数应在 forward/推理代码中用comfy.ops.cast_to_input或comfy.model_management.cast_to在使用时 cast以避免 dtype 不匹配。见 comfy/ops.py 的cast_to_input与 comfy/model_management.py 的cast_to。模型代码不关心自己以什么 dtype 初始化__init__中不应包含针对特定 dtype 的 workaround——这类代码属于负责计算策略的执行或模型管理层。不要执行无谓的设备间传输新分配必须创建在正确的设备与 dtype 上绝不允许“先在 CPU 分配再搬到 GPU”或“先在一个 dtype 分配再转成另一个”。6.3 模型检测规则检查线性权重形状的模型检测代码只能使用第一维——第二维在 NVFP4 或其他 4-bit 量化模型上可能只有原尺寸的一半。模型检测签名必须防护其解引用的每个 state-dict 键不要部分匹配某格式后在提取配置时抛出偶然的KeyError。模型检测检查顺序应从更成熟/更具体的签名到更新/更宽的签名新的宽泛检测器放在通用回退附近避免抢占其他模型家族的优先级。6.4 张量使用纪律核心推理代码避免使用einops改用原生 torch 张量算子reshape、view、permute、transpose、flatten、unflatten、unsqueeze、squeeze。不要把张量当作通用 Python 数据结构元数据、簿记、计数器、标志、形状/填充数学、索引规划、内存估算、控制流决策都应保持为普通 Python 值除非数据必须直接参与张量计算。序列长度、累计偏移、切分索引、窗口计数、切片边界、repeat 计数从计算那一刻起就应保持为 Python int/list不要先建成 CPU/GPU 张量再转回 Python 用于split、tensor_split、索引规划、循环或 cache key。避免为纯标量或结构计算创建临时张量去“借用”张量方法。当条件相关的模型工作在每次去噪步都会重复时若预计算一次能显著提升性能应暴露模型预处理方法并从BaseModel.extra_conds调用参照 LTXAV、Anima 等模式结果走正常 conditioning 通道不要为此添加模型自有缓存、sampler-option 缓存或缓存管理包装。extra_conds是理解这一节的最佳入口它在 comfy/model_base.py 的BaseModel上定义被大量子类重写以注入各自模型的专属条件。例如 Anima 在 comfy/model_base.py 中通过extra_conds预处理 T5 文本嵌入WAN21 系列各变体VACE、Camera、HuMo、Animate、SCAIL 等也在同一文件中用extra_conds注入vace_frames、camera_conditions、audio_embed、pose_latents等条件。这些条件通过comfy/conds.py中的CONDRegular、CONDNoiseShape、CONDCrossAttn、CONDConstant、CONDList等容器统一承载进入采样流程。6.5 内存与缓存管理归属模型代码本身不做内存管理加载、卸载、offload、设备移动、VRAM 策略、缓存生命周期与清理属于模型管理与执行层。对应实现见 comfy/model_management.py 中的free_memory、soft_empty_cache、unload_all_modelscomfy/model_management.py等接口。不要添加跨越多次执行的全局/模块级/类级/单例/模型自有张量或大内存存储临时缓存必须限定在单次执行或单次 forward/encode/decode 调用内在拥有它的顶层调用中分配、通过调用栈显式传递、调用返回时丢弃。遵循 Wan VAE 时间缓存模式为 encode/decode 创建局部缓存如feat_map传入需要它的 block不要保留在模型或全局状态上。该模式在 comfy/ldm/wan/vae.py 有直接实现——feat_map在 encode 开始时创建、随分帧迭代传入 encoder 并更新函数返回后即随作用域释放。跨执行持久缓存应尽量避免仅当占用极小且有清晰的归属与失效机制时才允许。切大张量时若切出张量的生命周期超出当前函数作用域应复制该切片长生命周期 view 会拖住大后备张量而小拷贝能更早释放内存。数学自然匹配时使用融合/复合 torch 算子如addcmul减少 Python 与 torch 分派开销是合理优化但不得掩盖代码或改变 dtype/device 行为。优化时偏好小而可衡量的改动更少分配、更少设备传输、更低峰值内存、更好批处理或使用更快的既有后端算子。6.6 模型初始化与结构模型__init__中对从 state dict 填充的参数/缓冲占位符优先用torch.empty而不是torch.zeros等零初始化如果某分配不来自 state dict 且对推理无用就不要包含它。存储于并从 state dict 填充的nn.Parameter张量应以torch.empty初始化而不是零、随机或其它“有意义”的初始化——模型初始化应描述模块结构而不是捏造 checkpoint 拥有的张量内容从 state dict 加载的参数与缓冲不得手动初始化、重赋值或填回退值除非该值在无对应 checkpoint 键时确实被使用。若模型类__init__有operations参数假设operations永不为None不要为缺失的operations添加回退分支或默认 torch ops。不要给模型、模型 block 或模型 ops 相关类添加不必要的参数构造函数与 forward 签名只应携带该对象推理实际需要的值。实现新模型组件前先搜索既有模型代码中是否已有提供该行为的类或 helper 并复用。6.7 Latent 布局与 DiT 尺寸处理模型原生的 latent 布局处理应留在模型或 latent-format 归属者内而不是 helper 节点不要为了满足模型 forward 而在节点或调用方侧适配器里压缩、扩展、打包或解包 latent 维度——模型路径应消费并返回该模型家族的原生 latent 形状。DiT 模型应接受不是 patch-size 整倍数的 latent 尺寸对每个 patchified 的目标或参考输入使用comfy.ldm.common_dit.pad_to_patch_size随后只把目标输出 crop 回原始尺寸。该 helper 在 comfy/ldm/common_dit.py 中实现按 patch_size 对空间维度做取整补零默认padding_modecircularjit trace/script 时回退reflect。避免防御性的形状与配置检查——它们只是替换了下方张量算子本会给出的清晰报错只在真实边界上能提供实质性更好上下文或防止静默错误输出时才添加显式校验。七、用户输入容忍度能跑就放行优先用用户提供的值完成工作流而不是因为超出推荐/UI 宣传/质量导向的限制就拒绝。只要下游实现能消费该输入就原样传下去即使结果可能较差。例如不要因为节点宣传了更小的推荐最大值就拒绝或截断额外的参考图。不要仅仅为了防止退化、无意义或低质量输出而添加校验错误——坏结果优于让一个本可执行的工作流失效。仅在“原样传递必然导致既有模型或底层算子失败”时才去 resize、pad、clamp、normalize 或改造用户输入做保持执行继续所需的最小调整不要为了证明改动合理而添加模型级校验失败。这一宽容政策不覆盖安全边界路径包含path containment与安全加载模型格式/checkpoint 所需的完整性校验仍然必须执行。这条原则解释了为什么 ComfyUI 的图执行倾向于“宽容消费”图解析与节点执行在 comfy_execution/ 与 execution.py 中完成节点尽量不引入会阻断整条工作流的额外校验。八、节点与用户可见行为8.1 节点约定遵循既有节点约定INPUT_TYPES、RETURN_TYPES、FUNCTION、CATEGORY并通过该文件使用的本地映射注册。这是 comfy_extras/ 与 nodes.py 中所有节点的标准模式。Combo 输入视为不可信凡是会影响文件系统访问的 legacy combo 输入、io.Combo、io.DynamicCombo值在加载/保存边界必须再次用既有的folder_pathsresolver 或 containment helper或固定 allowlist/映射校验。不能只依赖广告的 combo 选项或 prompt 校验。默认保持节点改动向后兼容新增输入要带合理默认值除非请求明确要求避免改变输出类型。模型实现应只添加运行该模型所需的最少节点尽量复用既有节点优先“改造模型去适配既有节点”而不是创建新节点。变量数量的重复输入使用io.Autogrow而不是一排编号的可选 socket当模型有无条目合法路径时把最小值设为 0仅在模型有真实上限时才设上限。该类型在 comfy_api/latest/_io.py 中实现支持模板前缀与最小/最大数量约束。当执行存在不读取某输入的合法路径时将该输入标记为 optional如果某可选输入只用于处理另一个可选输入不要在两者都不提供的路径上强迫用户连接它。8.2 输出与流向约束Conditioning 节点通常只输出 conditioning不要为下游尺寸计算或路由暴露输入或中间图像作为便利输出应使用既有图像路径或专用图像算子。节点只输出自己拥有的值不要为了工作流便利添加 pass-through 输出除非该节点本身就是输出节点既有模型、latent、conditioning 或其他输入应直接流向下一个消费者而不是被原样重新发射。节点只暴露实际读取以产生当前行为的输入不要添加被忽略的占位、pass-through、兼容性或工作流塑形输入。节点级代码不得直接 patch 模型代码任何修改、包装、hook 或改变模型行为的节点行为都必须通过模型 patcher 类完成而不是深入模型内部。模型 patcher 见 comfy/model_patcher.py 的ModelPatcher类。8.3 消息与文档警告与信息消息应短且有可操作性删除嘈杂或误导的消息而不是堆更多日志。文档与 README 改动应简洁、基于事实并与所改行为绑定。九、提交与评审习惯提交信息用简短直白的主语与既有历史风格一致Fix ...、Add ...、Support ...、Remove ...、Update ...、Make ...、Use ...、Disable ...、Bump ...、Revert ...。PR 描述保持简短可评审说明问题、行为改动、跑过的测试避免长篇叙事、实现日记或逐文件总结除非评审者明确需要。每个提交聚焦一个连贯的行为改动依赖 pin、测试与需要它们的代码在不可分割时可放在同一提交。评审时优先关注真实用户影响崩溃、错误的 dtype/device 行为、内存回退、模型加载失败、工作流不兼容、嘈杂或误导的用户可见输出。十、如何在仓库中验证这些规范以上规范并非抽象口号仓库中处处可以找到对应实现供比对执行边界对照 execution.py 与 comfy_execution/ 观察“只消费 prompt 图与执行状态”的边界设计测试见 tests/execution/ 与 tests-unit/execution_test/。conditioning 机制BaseModel.extra_conds与comfy.conds的容器类comfy/conds.py解释了模型如何通过统一接口声明所需条件这与“共享接口契约”一节直接呼应。内存管理归属模型代码不直接管理显存而是由 comfy/model_management.py 统一调度free_memory、soft_empty_cache、unload_all_models等模型实现只需遵循“不持有跨执行缓存”的纪律Wan VAE 的feat_map局部缓存comfy/ldm/wan/vae.py是教科书式范例。优化算子复用comfy.ops.cast_to_inputcomfy/ops.py、comfy.model_management.cast_tocomfy/model_management.py与comfy.ldm.common_dit.pad_to_patch_sizecomfy/ldm/common_dit.py是“优先既有 helper”的直接证据。动态输入io.Autogrowcomfy_api/latest/_io.py是节点设计“用 Autogrow 而非编号 socket”的实现落点。模型加载与检测可对照 comfy/model_detection.py 与 comfy/supported_models.py 检查 6.3 节关于权重形状探测与检查顺序的要求。十一、小结AGENTS.md 的九大章节本质上回答了一个问题在 ComfyUI 这样庞大且快速演进的扩散模型工程中什么才是一次“合格”的改动。它的答案可以浓缩为几句话改动落在最窄的代码路径上每一层只拥有自己的概念核心代码绝不联网状态与接口契约清晰不越界模型实现以 dtype/设备/内存为第一正确性优先复用既有优化算子节点宽容对待用户输入、严格约束自己的输入输出提交信息简短、评审聚焦真实用户影响。对于任何想在 ComfyUI 上做模型集成、节点开发或性能修复的开发者这份规范既是行动清单也是理解这个项目代码组织方式的钥匙。赞分享人工智能大模型媒体生成本地部署【免费下载链接】ComfyUIThe most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.项目地址https://gitcode.com/GitHub_Trending/co/ComfyUI点击查看免费下载相关推荐Kaneo 项目开发指南从架构边界到发布流程的完整协作规范Kaneo 项目开发指南从架构边界到发布流程的完整协作规范 Kaneo 是一个快速、刻意保持简单、支持自托管的一体化项目管理平台Hono API 拥有领域行前端后端Litestream 代码模式与反模式实践指南从架构边界到并发安全的核心开发规范Litestream 代码模式与反模式实践指南从架构边界到并发安全的核心开发规范 Litestream 是一个基于 SQLite WAL 的流式复制工具其代数据库数据同步灾备高可用Comp AI CRM 的 AGENTS.md 全解AI Agent 协作开发的工作区规则、架构边界与工程规范Comp AI CRM 的 AGENTS.md 全解AI Agent 协作开发的工作区规则、架构边界与工程规范 导读 Comp AI CRM 是一个为 AI后端前端CRM人工智能AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考