---
slug: "comfyui-painter-free"
name: "comfyui-painter-free"
version: 1.0.1
displayName: "ComfyUI画图基础版"
summary: "ComfyUI基础画图,支持文生图与本地模型管理,手动调参,不含CivitAI集成。ComfyUI 本地画图基础客户端（免费版）。通过 ComfyUI API 在本地 GPU 上生成图片,"
summary_zh: "ComfyUI基础画图,支持文生图与本地模型管理,手动调参,不含CivitAI集成。ComfyUI 本地画图基础客户端（免费版）。通过 ComfyUI API 在本地 GPU 上生成图片,"
license: "MIT"
description: |-
  ComfyUI 本地画图基础客户端（免费版）。通过 ComfyUI API 在本地 GPU 上生成图片,
  支持文生图任务与基础参数控制。提供 ComfyUI 启动/关闭/状态检查与空闲自动关闭功能.
  内置 3 种基础模型别名覆盖动漫与写实风格。用户需手动指定 Steps/CFG/采样器等参数.
  不含 CivitAI 模型搜索/下载/更新检查与自动调参能力。适用于个人创作者快速试图、
  学习 ComfyUI API 调用、简单画图需求场景.
tags:
  - Creative
  - 图像生成
  - ComfyUI
  - UI设计
  - 前端
  - 设计
  - comfyui
  - generate
  - mgr
  - 生命周期
  - 补充
tools:
  - read
  - exec
  - write
homepage: ""
category: "Creative"
---
# ComfyUI Painter LITE

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

| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| input | string | 是 | ComfyUI画图基础版处理的输入数据或指令 |
| options | object | 否 | 附加配置选项,如模式选择、格式偏好等 |
| callback_url | string | 否 | 异步处理完成后的回调通知URL |

## 依赖说明

### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
- **操作系统**: Windows / macOS / Linux

### 依赖项
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-----|:-----|:-----|:-----|
| LLM API | API | 必需 | 由Agent内置LLM提供 |

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

### 可用性分类
- **分类**: MD+EXEC（）

**API Key配置方式**:
```bash
export API_KEY="your_api_key_here"
```
配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.
## 核心能力

### 脚本路径

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

### ComfyUI 生命周期管理

**输入**: 用户提供ComfyUI 生命周期管理所需的指令和必要参数.
**处理**: 解析ComfyUI 生命周期管理的输入参数,执行核心处理逻辑,返回结构化结果和执行状态.
**输出**: 返回ComfyUI 生命周期管理的处理结果,包含执行状态码、结果数据和执行日志。- 验证返回数据的完整性和格式正确性
- 参考`ComfyUI 生命周期管理`的配置文档进行参数调优
### 启动 ComfyUI
```python
import scripts.comfyui_manager as mgr
mgr.start()
```

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

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

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 详细的输入输出格式请参考下方章节说明。

## 脚本路径(补充)

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

### 启动 ComfyUI(补充)

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

### 状态检查(补充)

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

### 关闭 ComfyUI

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

### 空闲自动关闭

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

超过 15 分钟无使用自动关闭 ComfyUI 释放显存.
## 基础图片生成(补充)

```python
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 付费版中提供.
## 基础模型别名(补充)

| 别名(续)| Checkpoint | 风格 |
|:-------|-------:|:-------|
| noobv6 | pornmasterPro_noobV6 | NoobAI 动漫（默认） |

> 付费版额外提供 hassaku、janku、nova3d、unholy 等 5 种模型别名.
## 基础参数指南(补充)

| 参数(续)| 说明 | 推荐值 |
|---:|:---|---:|
| positive | 正向提示词 | 专业 SD 标签格式 |
| steps | 采样步数 | 20-25 |
| cfg | CFG 引导强度 | 5-7（Flux 用 1） |

## 提示词优化基础(补充)

## 适用场景

| 场景 | 典型输入 | 输出内容 |
|:------:|--------|:-------|
| 动漫风格生成 | "用 noobv6 生成一张动漫角色图" | PNG 图片文件 |
| 写实风格生成 | "用 sdxlv8 生成写实头像" | PNG 图片文件 |

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

## 使用流程

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

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

### 案例一： 动漫角色生成

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

```python
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,避免显存压力.
### 案例二： 写实风格生成

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

```python
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.
## 异常处理

| 错误场景 | 错误信息 | 原因分析 | 处理方式 |
|----|:--:|---:|----|
| comfyui_not_running | `Connection refused: 127.0.0.1:8188` | ComfyUI 未启动或启动中 | 调用 `mgr.start()` 启动,等待 10 秒后检查网络连接和配置后重试 |
| model_alias_not_found | `Unknown model alias: xxx` | config.json 中无此别名 | 列出可用别名（noobv6/sdxlv8/flux）,引导用户选择 |
| generate_timeout | `ComfyUI generation timeout` | 生成耗时超过 120 秒 | 降低 batch_size 或 steps 后检查网络连接和配置后重试 |
| oom_error | `CUDA out of memory` | 显存不足 | 降低分辨率或 batch_size,关闭其他占用显存的进程 |
| invalid_params | `Invalid parameter: cfg must be > 0` | 参数值非法 | 检查 steps/cfg/width/height 是否在合理范围 |

## 常见问题

### 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 集成能力.
## 错误处理

| 错误场景 | 原因 | 处理方式 |
|----|----|----|
| LLM响应超时或无响应 | 网络延迟或模型负载过高 | 检查网络连接和配置后重试；确认Agent平台LLM服务正常 |
| 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求，参考示例章节 |
| 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述，补充必要的上下文信息 |
| 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求；检查命令权限设置 |

## 已知限制

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

---
## 快速开始

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 详细的输入输出格式请参考下方章节说明。

> **想要 CivitAI 模型搜索、自动调参、图生视频?** 升级到 [comfyui-painter 付费版](#) 解锁全部高级能力.
## 输出格式

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