ComfyUI-Doctor：ComfyUI 全时运行期诊断工具，无需再猜测工作流程失败的原因

ComfyUI-Doctor 是一款专为 ComfyUI 设计的实时诊断套件。它能在 ComfyUI 启动后自动拦截所有终端输出，精准捕捉 Python 异常（Traceback），并结合节点级上下文（Node ID、名称、类别）提供结构化修复建议。

• GitHub：https://github.com/rookiestar28/ComfyUI-Doctor

无需手动查日志、无需复现错误、无需翻看代码 —— 错误发生时，诊断已就绪。

核心能力

1. 自动错误监控

• 实时捕获全部终端输出，包括后台异常
• 自动识别 Python Traceback，即使错误未阻断流程
• 支持 19+ 常见错误模式（如 OOM、维度不匹配、模型缺失等）

2. 智能修复建议

• 针对每类错误提供可操作的解决路径
• 示例（CUDA 内存不足）：

  SUGGESTION: OOM（内存不足）：GPU VRAM 已满。建议：
     1. 减少 Batch Size
     2. 使用 '--lowvram' 启动参数
     3. 关闭其他占用 GPU 的程序
  

3. 节点级上下文提取

• 精确定位错误来源：
  • Node ID（如 #42）
  • 节点名称（如 KSampler）
  • 节点所属自定义插件（如 ComfyUI-Impact-Pack）

4. AI 智能分析（可选）

• 一键调用 LLM 分析错误上下文
• 支持 8+ 种 AI 提供商：
  • 云端：OpenAI、DeepSeek、Gemini、Groq、Grok、OpenRouter
  • 本地：Ollama（localhost:11434）、LMStudio（localhost:1234）
• 支持自动列出本地可用模型（如 llama3.1:8b）

5. 主动调试节点

• 在画布任意位置插入 Smart Debug Node
• 透传数据的同时，输出：
  • Tensor 形状（如 [1, 4, 64, 64]）
  • 数据类型（float16 / float32）
  • 设备（cuda:0 / cpu）
  • 数值统计（Min / Max / Mean）
• 不中断工作流，适用于逐节点排查

6. 可视化侧边栏界面

• 点击左侧 🏥 Doctor 按钮即可开启
• 功能包括：
  • 状态指示灯（🟢 正常 / 🔴 错误）
  • 错误卡片（含时间、节点、建议）
  • 「在画布上定位」：自动居中并高亮问题节点
  • 「AI 分析」按钮：触发 LLM 诊断

安装与启动

cd ComfyUI/custom_nodes/
git clone https://github.com/rookiestar28/ComfyUI-Doctor.git

重启 ComfyUI，终端出现以下初始化信息即表示成功：

[ComfyUI-Doctor] Initializing Smart Debugger...
[ComfyUI-Doctor] Log file: .../logs/comfyui_debug_2025-12-28.log
==================== SYSTEM SNAPSHOT ====================
OS: Windows 11
Python: 3.12.3
PyTorch: 2.0.1+cu118
CUDA Available: True
...

安装后无需额外操作，系统自动进入被动监控模式。

使用场景

被动模式（推荐日常使用）

• 自动记录日志至 ComfyUI/custom_nodes/ComfyUI-Doctor/logs/
• 自动捕获错误并生成建议
• 错误发生时可选自动弹出 Doctor 面板（需在设置中启用）

主动模式（深度调试）

1. 右键 → Add Node → Smart Debug Node
2. 插入工作流任意连接线上（支持万用输入 *）
3. 执行后查看控制台输出，或通过日志文件分析

配置选项（通过 ComfyUI 设置面板）

🔒 安全性说明：API Key 仅在分析请求时临时传输，不会被记录或持久化。

📡 RESTful API（供前端或脚本集成）

日志管理

• 路径：ComfyUI/custom_nodes/ComfyUI-Doctor/logs/
• 命名格式：comfyui_debug_YYYY-MM-DD_HH-MM-SS.log
• 保留策略：默认保留最近 10 个日志文件
• 自定义：通过 config.json 调整：

  {
    "max_log_files": 10,
    "history_size": 20,
    "default_language": "zh_TW",
    "enable_api": true
  }
  

支持的错误类型（部分）

• CUDA out of memory（显存不足）
• Tensor shape mismatch（维度不匹配）
• ModuleNotFoundError（缺少依赖）
• AssertionError / KeyError / AttributeError
• SafeTensors loading failed
• InsightFace not installed
• VAE/Model 不匹配
• 无效的 Prompt JSON
• 设备冲突（如 cpu vs cuda）

💡 使用技巧

• 搭配 ComfyUI Manager：自动安装缺失的自定义节点
• 日志用于报 bug：向插件作者提交完整 Traceback
• 调试节点串接：在怀疑出错的节点后插入，验证输入/输出
• 本地 LLM 优先：避免 API 费用与网络延迟，推荐 Ollama + llama3.1:8b