用途
ComfyUI Troubleshooter 是一个用于诊断和解决 ComfyUI 使用问题的技能。根据资料，它覆盖四大类问题：服务器错误、工作流错误、画质问题和性能问题。
主要能力
诊断流程
第一步：对错误分类
| 类别 | 症状 | 首要检查 |
|---|---|---|
| 服务器 | 连接被拒、超时、崩溃 | ComfyUI 是否运行？检查 /system_stats |
| 工作流 | 节点错误、缺失输入、类型不匹配 | 对照清单验证工作流 |
| 画质 | 伪影、身份错误、输出模糊 | 检查设置（CFG、权重、分辨率） |
| 性能 | 显存不足、生成缓慢、VRAM 错误 | 检查 VRAM 使用、模型大小 |
第二步：收集上下文，诊断前需收集：
- 错误信息（精确文本）
- 正在执行的工作流（或描述）
- 涉及模型（checkpoint、LoRA、ControlNet 等）
- 设置（CFG、steps、分辨率、采样器）
- 硬件信息（来自 foundation/hardware-profile.md）
- 安装清单（来自 state/inventory.json）
第三步：匹配错误模式，完整错误数据库见 references/troubleshooting.md。
快速修复参考（十大常见错误）
-
"CUDA out of memory" → 使用 FP8：--fp8_e4m3fn-unet → 启用 tiled VAE → 降低分辨率 → 重启 ComfyUI（清除碎片）
-
"Node type not found: {name}" → 通过 ComfyUI-Manager 安装自定义节点包 → 检查 comfyui-inventory 的节点到包映射
-
"Expected scalar type BFloat16 but found Float" → 精度不匹配。添加 --force-fp16 或使用精度匹配的节点
-
面部过曝/过烧 → 降低 CFG 到 4-5（InstantID） → 降低身份方法权重 → 向负向嵌入添加噪声（35%）
-
"No model found at path" → 检查文件名拼写（必须精确匹配） → 确认文件位于正确子目录 → 运行清单扫描确认
-
1024x1024 出现水印伪影 → 改用 1016x1016 或 1020x1020
-
身份与参考图不符 → 使用更高质量的参考图（清晰、正面） → 提高 IP-Adapter 权重至 0.8+ → 确认已安装 InsightFace antelopev2
-
视频闪烁 → 降低 FaceDetailer 降噪到 0.3 → 添加 deflicker 后处理 → 提高 AnimateDiff 上下文重叠到 4+
-
队列卡住/不处理 → POST /interrupt 取消 → POST /free 卸载模型 → 重启 ComfyUI
-
生成缓慢 → 检查是否启用 --lowvram（RTX 5090 上应移除） → 改用 --highvram → 更新 cuDNN 到 8800+ → 为 Wan 模型启用 SageAttention
画质问题决策树
输出不正常：
- 人脸看起来不对
- 过于光滑/塑料感 → 添加皮肤纹理 LoRA（0.2-0.4）
- 身份错误 → 提高身份权重，检查参考图质量
- 过曝/过热 → 降低 CFG 到 4-5，降低 InstantID 权重
- 畸形 → 在负向提示中加入 "bad anatomy, deformed"
- 每次都不一样 → 固定种子，添加 LoRA 提升一致性
- 颜色错误
- 过饱和 → 降低 CFG，负向加入 "oversaturated"
- 发白 → 检查 VAE 是否加载，尝试不同调度器
- 视频色偏 → 添加颜色校正后处理
- 分辨率/清晰度
- 模糊 → 提高 steps（25-30），检查分辨率是否匹配模型
- 像素化 → 使用合适的放大器（4x-UltraSharp），而非缩放
- 伪影 → 降低降噪，检查模型是否损坏
- 构图
- 忽略提示词 → 略微提高 CFG，简化提示词
- 多出肢体/物体 → 加入负向提示，使用 ControlNet
- 姿势错误 → 配合参考图使用 ControlNet OpenPose
缺失依赖解决
当工作流引用了清单中不存在的内容：
缺失自定义节点
- 通过 class_type 识别包（参见 inventory 技能的映射）
- 建议："打开 ComfyUI-Manager → 搜索 → 安装 {package_name}"
- 备选："cd {ComfyUI}/custom_nodes && git clone {repo_url}"
- 提醒：安装后重启 ComfyUI
缺失模型
- 在 references/models.md 中查找下载链接
- 提供：精确文件名、下载 URL、目标目录
- 对于大模型（>10GB）：建议使用 HF CLI 以保证可靠性 "huggingface-cli download {repo} {file} --local-dir {path}"
版本不兼容
- 检查 ComfyUI 版本与节点包要求
- 建议："cd {ComfyUI} && git pull" 更新 ComfyUI
- 或者：如果最新版出问题，固定特定节点版本
升级求助
如果排查后仍未解决：
- 查看 ComfyUI GitHub Issues 中的已知 bug
- 查看具体节点包的 Issues
- 在 r/comfyui 搜索社区方案
- 建议在 ComfyUI Discord 中附错误详情发帖
使用方式
按诊断流程先分类错误，再收集上下文，然后匹配错误模式，最后给出针对性修复建议。完整错误数据库见 references/troubleshooting.md，当前安装状态见 state/inventory.json，模型下载链接与路径见 references/models.md。
适用场景
适用于排查 ComfyUI 的服务器连接、工作流节点、画质输出和性能瓶颈问题，特别是涉及自定义节点缺失、模型路径错误、精度不匹配、显存不足和视频生成质量等常见故障。
限制
资料未提供该技能的具体安装命令、收费方式、运行环境要求及支持范围等信息，暂未提供。