超详细实战案例复盘！ComfyUI 自定义节点开发全流程

需求探索 → 技术调研 → PRD文档 → 架构设计 → 编码 → 自我测试 → 本地测试 → 发现新需求 → 新PRD → 循环

位移 (translateX/Y) → 画面从哪里来、到哪里去
缩放 (scale) → 画面的放大缩小
旋转 (rotate) → 画面的旋转角度
透明度 (opacity) → 画面的淡入淡出

# [项目名] - 需求总结

## 版本：v1.0
## 日期：2026-XX-XX
## 模块：[模块名]

---

## 一、背景与痛点
- 现状分析（用户现在怎么做这件事）
- 核心痛点（现有方案有什么问题）
- 目标定义（我们要达到什么效果）

## 二、功能范围
- 做什么（本版本的功能列表）
- 不做什么（明确排除项）

## 三、技术架构
- 设计原则
- 目录结构
- 数据流图
- 输入输出规范（ComfyUI tensor 格式）
- 性能优化策略

## 四、功能详细规格
- 每个节点/效果的参数表
- 算法描述（数学公式、缓动曲线）
- 边界情况处理

## 五、共享模块规格
- 各引擎模块的 API 定义
- 函数签名和参数说明

## 六、关键决策记录
- 每个重要选择的"选了什么 + 为什么"

## 七、开发计划
- 阶段划分
- 依赖关系
- 哪些可以并行

项目文件夹/设计/
├── v1.0-[模块名]/
│ └── 需求总结.md ← 首版 PRD
├── v1.1-[模块名]/
│ └── 需求总结.md ← 迭代 PRD（不覆盖旧版）
└── v1.2-.../

ComfyUI/custom_nodes/My-Plugin-Name/
├── __init__.py # 插件入口，注册所有节点
├── pyproject.toml # 项目元数据和依赖声明
├── core/ # 引擎层：共享的底层逻辑
│ ├── __init__.py
│ ├── module_a.py # 例如：缓动曲线库
│ ├── module_b.py # 例如：图像混合引擎
│ └── utils.py # 工具函数
└── nodes/ # 节点层：每个 ComfyUI 节点一个文件
├── __init__.py
├── node_type_1.py
├── node_type_2.py
└── node_type_3.py

class TransitionFade:
"""淡入淡出转场"""

@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"image_a": ("IMAGE",), # 前一个画面
"image_b": ("IMAGE",), # 后一个画面
"transition_frames": ("INT", { # 过渡帧数
"default": 15,
"min": 2,
"max": 120,
"step": 1,
}),
"easing": (["linear", "ease_in", "ease_out", "ease_in_out"],),
},
"optional": {
"custom_curve": ("STRING", {"default": ""}),
}
}

RETURN_TYPES = ("IMAGE",)
RETURN_NAMES = ("transition_frames",)
FUNCTION = "render"
CATEGORY = "Transition Effects"

def render(self, image_a, image_b, transition_frames, easing, custom_curve=""):
# 1. 将 tensor 转为 PIL
# 2. 逐帧计算混合比例（基于缓动曲线）
# 3. 逐帧混合两张图片
# 4. 转回 tensor 返回
return (result_tensor,)

from .nodes.transition_fade import TransitionFade
from .nodes.transition_slide import TransitionSlide
from .nodes.transition_zoom import TransitionZoom

NODE_CLASS_MAPPINGS = {
"TransitionFade": TransitionFade,
"TransitionSlide": TransitionSlide,
"TransitionZoom": TransitionZoom,
}

NODE_DISPLAY_NAME_MAPPINGS = {
"TransitionFade": "Fade Transition (淡入淡出)",
"TransitionSlide": "Slide Transition (滑动转场)",
"TransitionZoom": "Zoom Transition (缩放转场)",
}

__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS"]

Step 1: core/easing.py ← 缓动曲线（纯数学，零依赖）
Step 2: core/utils.py ← tensor↔PIL 转换（基础设施）
Step 3: core/blender.py ← 图像混合引擎（依赖 utils）
Step 4: nodes/xxx.py ← 各节点（依赖 core 完成）
Step 5: __init__.py ← 注册（最后一步）

[core/ 完成并测试通过]
↓
并行开发多个节点
├── Agent 1 → transition_fade.py
├── Agent 2 → transition_slide.py
└── Agent 3 → transition_zoom.py

Level 1: 能不能 import（语法和依赖）
↓ 通过
Level 2: 函数输出对不对（逻辑正确性）
↓ 通过
Level 3: ComfyUI 认不认识这个节点（注册验证）
↓ 通过
Level 4: 节点之间数据能不能流通（集成验证）

python3 -c "
from core.easing import ease_in, ease_out, spring_overshoot
print('easing.py OK')
"

python3 -c "
from core.easing import ease_out

# 边界值测试
assert ease_out(0.0) == 0.0, 't=0 应该返回 0'
assert ease_out(1.0) == 1.0, 't=1 应该返回 1'

# 单调性测试：ease_out 应该是递增的
v1 = ease_out(0.3)
v2 = ease_out(0.7)
assert v2 > v1, 'ease_out 应该单调递增'

# 缓出特性：前半段变化应该快于后半段
mid = ease_out(0.5)
assert mid > 0.5, 'ease_out(0.5) 应该 > 0.5（前快后慢）'

print(f'ease_out(0.5) = {mid:.4f} ✓')
print('所有断言通过')
"

python3 -c "
from core.blender import blend_crossfade
from PIL import Image
import numpy as np

# 创建两张测试图片
img_a = Image.new('RGB', (100, 100), (255, 0, 0)) # 纯红
img_b = Image.new('RGB', (100, 100), (0, 0, 255)) # 纯蓝

# t=0 应该是纯 A
result = blend_crossfade(img_a, img_b, t=0.0)
pixel = result.getpixel((50, 50))
assert pixel == (255, 0, 0), f't=0 应该是纯红，实际是 {pixel}'

# t=1 应该是纯 B
result = blend_crossfade(img_a, img_b, t=1.0)
pixel = result.getpixel((50, 50))
assert pixel == (0, 0, 255), f't=1 应该是纯蓝，实际是 {pixel}'

# t=0.5 应该是混合色
result = blend_crossfade(img_a, img_b, t=0.5)
pixel = result.getpixel((50, 50))
assert 100 < pixel[0] < 150, f'红色通道应该在中间值，实际是 {pixel[0]}'

print('blend_crossfade 测试通过 ✓')
"

python3 -c "
import sys, os, importlib.util

# 模拟 ComfyUI 的包加载方式
plugin_dir = '/path/to/custom_nodes/My-Plugin'
spec = importlib.util.spec_from_file_location(
'My-Plugin',
os.path.join(plugin_dir, '__init__.py'),
submodule_search_locations=[plugin_dir]
)
mod = importlib.util.module_from_spec(spec)
mod.__path__ = [plugin_dir]
mod.__package__ = 'My-Plugin'
sys.modules['My-Plugin'] = mod

# ... 注册子包和子模块（略）...

spec.loader.exec_module(mod)

# 验证所有节点
mappings = mod.NODE_CLASS_MAPPINGS
print(f'注册了 {len(mappings)} 个节点：')
for name, cls in mappings.items():
# 检查 ComfyUI 要求的 4 个必要属性
assert hasattr(cls, 'INPUT_TYPES'), f'{name} 缺少 INPUT_TYPES'
assert hasattr(cls, 'RETURN_TYPES'), f'{name} 缺少 RETURN_TYPES'
assert hasattr(cls, 'FUNCTION'), f'{name} 缺少 FUNCTION'
assert hasattr(cls, 'CATEGORY'), f'{name} 缺少 CATEGORY'
print(f' ✓ {name} ({cls.CATEGORY})')

print('所有节点注册验证通过')
"

python3 -c "
# 模拟数据从 ConfigNode 传递到 RenderNode
config = make_transition_config(
effect='fade',
easing='ease_out',
duration_frames=15,
)
print(f'Config 创建成功: {config}')

# 模拟 RenderNode 接收 config
entries = resolve_config(config)
print(f'Config 解析成功: {len(entries)} 个关键帧')

# 模拟向后兼容（不传 config，直接传参数）
entries = resolve_config(config=None, effect='fade', duration=15)
print(f'向后兼容模式: {len(entries)} 个关键帧')

print('集成测试通过 ✓')
"

写完一个模块
↓
运行 Level 1 测试 → 失败 → 修 import/语法 → 重测
↓ 通过
运行 Level 2 测试 → 失败 → 修逻辑 → 重测
↓ 通过
继续写下一个模块
↓
全部模块写完
↓
运行 Level 3 测试 → 失败 → 修注册 → 重测
↓ 通过
运行 Level 4 测试 → 失败 → 修接口 → 重测
↓ 通过
进入 Phase 7（本地测试）

[Load Image A] ──→ image_a ──→ [TransitionFade] ──→ [Preview Image]
[Load Image B] ──→ image_b ──↗ ↑
transition_frames = 15
easing = "ease_out"

[发现新需求]
↓
讨论方案（可能要多轮）
- "这个功能要不要做？" → 可能砍掉
- "谁来做这件事？" → 可能交给上游节点
- "怎么实现最简洁？" → 最小改动原则
↓
编写 v1.1 PRD（独立归档，不覆盖 v1.0）
↓
编码 + 自我测试
↓
本地测试
↓
[准备 v1.2...]

Plugin/
├── __init__.py # 入口：注册所有节点
├── pyproject.toml # 元数据和依赖
├── core/ # 引擎层（不依赖 ComfyUI）
│ ├── easing.py # 缓动曲线
│ ├── blender.py # 图像混合
│ └── utils.py # 工具函数
└── nodes/ # 节点层（ComfyUI 接口）
├── node_a.py
├── node_b.py
└── node_c.py