ComfyUI Painter LITE

ComfyUI 基础版,通过 ComfyUI API 在本地 GPU 上生成图片。支持文生图任务与手动参数控制,内置 3 种基础模型别名. 范围外（本技能不做）: CivitAI 模型搜索/下载/更新检查、自动调参、图生视频、批量更新推荐参数（需升级付费版）.

输入格式

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY="your_api_key_here"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

核心能力

脚本路径

• （请参考skill目录中的脚本文件） — ComfyUI 启动/关闭/状态检查
• （请参考skill目录中的脚本文件） — 图片生成（调用 ComfyUI API）
• （请参考skill目录中的脚本文件） — 空闲自动关闭检查
• config.json — 配置文件（模型别名、默认参数）

ComfyUI 生命周期管理

输入: 用户提供ComfyUI 生命周期管理所需的指令和必要参数. 处理: 解析ComfyUI 生命周期管理的输入参数,执行核心处理逻辑,返回结构化结果和执行状态. 输出: 返回ComfyUI 生命周期管理的处理结果,包含执行状态码、结果数据和执行日志。- 验证返回数据的完整性和格式正确性

• 参考ComfyUI 生命周期管理的配置文档进行参数调优

启动 ComfyUI

import scripts.comfyui_manager as mgr
mgr.start()

启动后默认监听 http://127.0.0.1:8188。脚本会等待服务就绪后返回. 输入: 用户提供启动 ComfyUI所需的指令和必要参数. 处理: 解析启动 ComfyUI的输入参数,执行核心处理逻辑,返回结构化结果和执行状态.

状态检查

import scripts.comfyui_manager as mgr
status = mgr.s
# ...
**输入**: 用户提供ComfyUI 生命周期管理相关的配置参数、输入数据和处理选项.
**处理**: 解析ComfyUI 生命周期管理的输入参数,执行核心处理逻辑,返回结构化结果和执行状态.
# ...
**输出**: 返回状态检查的处理结果,包含执行状态码、结果数据和执行日志.
### 基础图片生成
# ...
```python
from scripts.generate import generate
result = generate(
    positive="masterpiece, best quality, 1girl, solo, detailed background",
    model="noobv6",
    batch_size=1,
    width=1024,

**输入**: 用户提供基础图片生成相关的配置参数、输入数据和处理选项.
**处理**: 解析基础图片生成的输入参数,执行核心处理逻辑,返回结构化结果和执行状态.
### 基础模型别名

| 别名 | Checkpoint | 风格 |
|---:|---:|---:|
| noobv6 | pornmasterPro_noobV6 | NoobAI 动漫（默认） |
| sdxlv8 | pornmaster_proSDXLV8 | SDXL 写实 |
| flux | flux1-dev-bnb-nf4-v2 | Flux 写实 |

> 付费版额外提供 hassaku、

**处理**: 解析基础模型别名的输入参数,执行核心处理逻辑,返回结构化结果和执行状态.
**输出**: 返回基础模型别名的处理结果,包含执行状态码、结果数据和执行日志.
### 基础参数指南

| 参数 | 说明 | 推荐值 |
|:---:|:---:|:---:|
| positive | 正向提示词 | 专业 SD 标签格式 |
| model | 模型别名 | noobv6 / sdxlv8 / flux |
| batch_size | 生成数量 | 1-4 |
| width | 图片宽度 | 512-1536 |
| height | 图片高度 | 512-1536 |
|

**处理**: 解析基础参数指南的输入参数,执行核心处理逻辑,返回结构化结果和执行状态.
### 提示词优化基础

- 质量标签在前: `masterpiece, best quality, absurdres, highres`
- 用 `BREAK` 分隔不同语义段
- 负面提示词加入: `censored, mosaic censoring, low quality`

**输入**: 用户提供提示词优化基础相关的配置参数、输入数据和处理选项.
**处理**: 解析提示词优化基础的输入参数,执行核心处理逻辑,返回结构化结果和执行状态.
**输出**: 返回提示词优化基础的处理结果,包含执行状态码、结果数据和执行日志.
#
## 脚本路径(补充)

## ComfyUI 生命周期管理(补充)

### 启动 ComfyUI(补充)

```python
import scripts.comfyui_manager as mgr
mgr.start()

状态检查(补充)

import scripts.comfyui_manager as mgr
status = mgr.status()  # 返回 running / stopped / error

关闭 ComfyUI

import scripts.comfyui_manager as mgr
mgr.stop()

空闲自动关闭

python3 （请参考skill目录中的脚本文件）

超过 15 分钟无使用自动关闭 ComfyUI 释放显存.

基础图片生成(补充)

from scripts.generate import generate
result = generate(
    positive="masterpiece, best quality, 1girl, solo, detailed background",
    model="noobv6",
    batch_size=1,
    width=1024,
    height=1536,
    steps=20,
    cfg=7,
)

生成完成后,图片输出到 workspace 临时目录,返回文件路径列表.

升级提示: 自动调参（从 CivitAI 获取推荐 Steps/CFG/采样器）、CivitAI 模型搜索/下载/更新检查等高级能力仅在 comfyui-painter 付费版中提供.

基础模型别名(补充)

付费版额外提供 hassaku、janku、nova3d、unholy 等 5 种模型别名.

基础参数指南(补充)

提示词优化基础(补充)

适用场景

不适用于: CivitAI 模型搜索/下载、自动调参、图生视频、模型更新检查（需升级付费版）

使用流程

1. 调用 comfyui_manager.status() 检查 ComfyUI 是否运行,未运行则调用 start() 启动
2. 解析用户需求: 提示词、模型别名、尺寸、步数等参数
3. 调用 generate.generate() 执行生成,获取图片文件路径
4. 将图片路径回传用户
5. 心跳回调中调用 auto_shutdown.py 检查空闲关闭

结果验证: 任务完成后,查看输出确认状态。成功时返回摘要和数据;失败时根据错误信息排查,参考恢复章节获取修复步骤.

案例展示

案例一： 动漫角色生成

场景: 创作者需要用 noobv6 模型生成 1 张动漫风格角色图

from scripts.generate import generate
result = generate(
    positive="masterpiece, best quality, 1girl, solo, silver hair, red eyes, gothic dress, detailed background BREAK cathedral, stained glass, moonlight",
    negative="censored, mosaic censoring, low quality, worst quality",
    model="noobv6",
    batch_size=1,
    width=1024,
    height=1536,
    steps=20,
    cfg=7,
)

输出: 1 张 PNG 图片文件路径

说明: 使用 BREAK 分隔角色描述与背景描述。免费版 batch_size 建议设为 1,避免显存压力.

案例二： 写实风格生成

场景: 用户需要生成一张写实风格的人像照片

from scripts.generate import generate
result = generate(
    positive="photorealistic, 1person, portrait, natural lighting, shallow depth of field, 85mm lens, detailed skin texture",
    negative="cartoon, anime, illustration, low quality",
    model="sdxlv8",
    batch_size=1,
    width=1024,
    height=1024,
    steps=25,
    cfg=5,
)

说明: SDXL 写实模型推荐 steps=25、cfg=5。Flux 模型则使用 cfg=1.

异常处理

常见问题

Q1: ComfyUI 启动后多久可以开始生成?

A: mgr.start() 会等待 ComfyUI 服务就绪后返回,通常需要 10-30 秒。若超过 60 秒仍未就绪,检查 GPU 驱动与模型路径配置.

Q2: 免费版和付费版有什么区别?

A: 免费版（LITE）支持基础文生图、3 种模型别名、手动参数控制。付费版（comfyui-painter）额外提供:

• CivitAI 模型搜索/详情/下载/更新检查
• 自动调参（从 CivitAI 样图元数据提取推荐参数）
• 8 种模型别名（含 hassaku、janku、nova3d、unholy 等）
• 图生视频支持
• 3 个完整案例（vs 免费版 2 个基础案例）
• 8 种异常处理（vs 免费版 5 种）

Q3: 参数怎么设置?

A: 动漫模型（noobv6）推荐 steps=20、cfg=7。写实模型（sdxlv8）推荐 steps=25、cfg=5。Flux 模型推荐 steps=20、cfg=1。付费版的自动调参功能可自动获取推荐参数,无需手动设置.

Q4: 为什么没有 CivitAI 集成?

A: CivitAI 模型搜索/下载/更新检查与自动调参是付费版专属功能。免费版需用户手动下载模型并配置 config.json。升级到 comfyui-painter 付费版可解锁全部 CivitAI 集成能力.

错误处理

已知限制

1. 基础任务: 仅支持文生图,不支持图生视频（需升级付费版）
2. 手动调参: 需用户手动指定 Steps/CFG/采样器,无自动调参能力
3. 模型别名有限: 仅 3 种基础别名,付费版提供 8 种
4. 无 CivitAI 集成: 不支持模型搜索/下载/更新检查
5. 需本地 GPU: 必须有 NVIDIA GPU,显存不足时生成会失败

想要 CivitAI 模型搜索、自动调参、图生视频? 升级到 comfyui-painter 付费版 解锁全部高级能力.

输出格式

{
  "success": true,
  "data": {
    "result": "ComfyUI画图基础版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "comfyui-painter"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}