企业官网建设流程全解析

Comfyui-zhenzhen 是一个收录了大量平价 API 调用节点的 ComfyUI 插件，支持 Seedance 2.0、Midjourney、Suno、GPT-Image、Nano-Banana 等模型。本文面向想参与贡献的开发者，讲清楚三件事：📌 新模型节点如何从零开发、🧪 测试清单怎么过、🔍 回归验证如何保证不破坏已有工作流。

一、先读懂项目结构：代码都在哪里

Comfyui-zhenzhen 采用「核心入口 + 按模型分文件 + 集中注册」的架构，新增模型节点前先熟悉这 5 个关键位置：

以最新加入的 Moss 图像节点为例，它的实现只集中在 moss_image_low_price_nodes.py 一个文件里，这是「一个模型一个文件」的惯例。

二、开发新模型节点五步走

第 1 步：复用公共 API 层，不要重复造轮子

seedance_low_price_nodes.py 提供了全套基础设施：

• resolve_config()：统一解析工作流设置节点或环境变量里的base_url/api_key
• upload_media()/submit_task()/poll_task()：上传素材、提交任务、轮询进度
• extract_video_url()/download_video()/download_image()：结果提取与下载
• media_download.py中还内置了断线重试与代理回退逻辑（见 media_download.py）

新节点只需from . import seedance_low_price_nodes as api即可复用（参考 moss_image_low_price_nodes.py）。

第 2 步：按固定骨架编写节点类

本项目节点类遵循统一模板，以 Moss 节点为例，包含 5 个要素：

1. RETURN_TYPES/RETURN_NAMES：输出IMAGE、结果 URL、task_id、完整响应 JSON
2. INPUT_TYPES()：required+optional分区，可选输入里必须带上api_config（类型ZHENZHEN_SEEDANCE2_CONFIG）和skip_error
3. VALIDATE_INPUTS()：输入契约校验，严格模式下返回错误原因
4. build_payload()：把控件值组装成 API 请求体，纯函数、可单测
5. generate()：串起「上传 → 提交 → 轮询 → 下载」，用ProgressBar汇报进度

另外两个硬性约定：

• 视频/图像/音频/3D 类生成节点会自动接入 execution_seed.py 的执行种子缓存控件，无需手写 seed
• CATEGORY用「zhenzhen/模型名」格式，方便前端区分「平价AI小屋」和「AI工坊」渠道

第 3 步：注册节点并自动接入缓存控件

节点写完后在 Comfly.py 的NODE_CLASS_MAPPINGS中注册节点 key（如"T8Zhenzhen_Moss_Image_LowPrice": T8ZhenzhenMossImageLowPrice），并在NODE_DISPLAY_NAME_MAPPINGS中配置中文名。注册完成后，Comfly.py 末尾的install_execution_seed_controls()会自动为所有生成类节点注入 seed 控件，无需额外处理。

⚠️ 兼容性红线：一旦发布的节点 key 不可更改，改名会直接破坏用户已保存的工作流。

第 4 步：连接 API 设置节点

每个节点通过api_config输入接收 Key，工作流里用Comfly API Settings节点统一配置base_url与api_key，再连线给生成节点，界面效果如下：

第 5 步（可选）：前端 JS 动态显隐控件

当节点支持多模式（如文生/图生/多参考）时，在 web/js/ 下添加脚本，按NODE_NAME匹配后只显示当前模式有效的输入。通用隐藏逻辑可复用 web/js/dynamic_widget_ui.js，Midjourney 动作节点的多操作显隐是完整范例（见 web/js/midjourney_action_ui.js）。

三、测试清单：从离线契约到 live 实测

1️⃣ 离线契约测试（必做，不花积分）

在 tests/ 下新增test_xxx.py，用unittest+ mock 校验三件事，可参考 tests/test_qwen_minimax_lowprice.py：

• 模型目录精确匹配：XXX_MODELS列表与文档逐字一致
• 输入契约：INPUT_TYPES()的选项、顺序、默认值正确
• payload 构造：build_payload()在互斥参数（如 auto/ratio/custom_size）下生成正确的请求体，非法输入抛出明确的SeedanceLowPriceError

2️⃣ Live 实测（真实调用，需环境变量开关）

live 脚本位于 tests/live_midjourney_lowprice.py 这类文件，用RUN_XXX_LIVE=1+SEEDANCE_API_KEY双重开关保护，避免误触发计费调用。实测要验证完整链路：上传 → 提交 → 轮询 → 下载 → 结果可解码，例如视频节点要确认下载的 MP4 分辨率、帧率、帧数符合预期：

3️⃣ 工作流完整性回归（防手滑）

每新增一份示例工作流 JSON，都要跑 tests/test_workflow_integrity.py，它自动检查：

• 所有 JSON 可解析、无语法错误
• 不包含任何sk-开头的真实 Key（敏感信息扫描）
• 连线引用的节点槽位全部真实存在
• 设置节点类型统一使用最终注册名

四、回归验证：合并前的最后一道门

参照项目更新日志中的标准动作，提交前完成：

• ✅完整离线回归：tests/下全部测试通过（项目惯例是跑完全部用例，如220/220）
• ✅节点计数探针：确认普通节点、并发提交节点、合并节点数量与预期一致，防止误删
• ✅旧工作流兼容：新节点不得改动既有节点的 key、控件顺序与输入名称
• ✅示例工作流齐套：每个新模型提供空 API Key 的可导入工作流，放入 workflow/
• ✅前端脚本校验：新增 JS 通过语法检查，web/js/下脚本数量对得上

遇到 API 报错时，对照 HTTP 状态码快速定位是客户端问题还是上游问题：

五、小结

为 Comfyui-zhenzhen 开发新模型节点的路径其实很清晰：复用 seedance_low_price_nodes.py 公共层 → 按模板写节点类 → 在 Comfly.py 注册 → 补离线契约测试 → live 实测 → 过工作流回归。严格遵守「节点 key 不变、payload 可单测、Key 不进仓库」三条红线，你的新模型节点就能平滑加入这个 200+ 节点的生态。