ComfyUI 本地画图基础客户端（免费版）。通过 ComfyUI API 在本地 GPU 上生成图片, 支持文生图任务与基础参数控制。提供 ComfyUI 启动/关闭/状态检查与空闲自动关闭功能。内置 3 种基础模型别名覆盖动漫与写实风格。用户需手动指定 Steps/CFG/采样器等参数。不含 CivitA...
SKILL.md

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

# ComfyUI Painter LITE

ComfyUI 基础版,通过 ComfyUI API 在本地 GPU 上生成图片。支持文生图任务与手动参数控制,内置 3 种基础模型别名。

**范围外**（本技能不做）: CivitAI 模型搜索/下载/更新检查、自动调参、图生视频、批量更新推荐参数（需升级付费版）。

## 依赖说明

### 运行环境
- **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应妥善保管,避免泄露到版本控制系统。

## 核心能力

### 脚本路径

- `scripts/comfyui_manager.py` — ComfyUI 启动/关闭/状态检查
- `scripts/generate.py` — 图片生成（调用 ComfyUI API）
- `scripts/auto_shutdown.py` — 空闲自动关闭检查
- `config.json` — 配置文件（模型别名、默认参数）


### ComfyUI 生命周期管理


**输入**: 用户提供ComfyUI 生命周期管理所需的指令和必要参数。
**处理**: 按照skill规范执行ComfyUI 生命周期管理操作,遵循单一意图原则。
**输出**: 返回ComfyUI 生命周期管理的执行结果,包含操作状态和输出数据。

- 执行`ComfyUI 生命周期管理`操作，处理输入数据并返回结果
- 验证执行结果，确认输出符合预期格式
- 参考`ComfyUI 生命周期管理`相关配置参数进行设置
### 启动 ComfyUI
```python
import scripts.comfyui_manager as mgr
mgr.start()
```

启动后默认监听 `http://127.0.0.1:8188`。脚本会等待服务就绪后返回。

**输入**: 用户提供启动 ComfyUI所需的指令和必要参数。
**处理**: 按照skill规范执行启动 ComfyUI操作,遵循单一意图原则。
### 状态检查
```python
import scripts.comfyui_manager as mgr
status = mgr.s

**输入**: 用户提供ComfyUI 生命周期管理所需的参数和指令。
**处理**: 按照skill规范执行ComfyUI 生命周期管理操作。

**输出**: 返回状态检查的执行结果,包含操作状态和输出数据。
### 基础图片生成

```python
from scripts.generate import generate
result = generate(
    positive="masterpiece, best quality, 1girl, solo, detailed background",
    model="noobv6",
    batch_size=1,
    width=1024,
   

**输入**: 用户提供基础图片生成所需的参数和指令。
**处理**: 按照skill规范执行基础图片生成操作。

### 基础模型别名

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

> 付费版额外提供 hassaku、

**处理**: 按照skill规范执行基础模型别名操作。
**输出**: 返回基础模型别名的执行结果,包含操作状态和输出数据。

### 基础参数指南

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

**处理**: 按照skill规范执行基础参数指南操作。

### 提示词优化基础

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

**输入**: 用户提供提示词优化基础所需的参数和指令。
**处理**: 按照skill规范执行提示词优化基础操作。
**输出**: 返回提示词优化基础的执行结果,包含操作状态和输出数据。

### 能力覆盖范围

本skill还覆盖以下能力场景: 基础画图、支持文生图与本地、模型管理、手动调参、CivitAI、本地画图基础客户、免费版、在本地、GPU、上生成图片、支持文生图任务与、基础参数控制、状态检查与空闲自、动关闭功能、种基础模型别名覆、盖动漫与写实风格、用户需手动指定、Steps、CFG、采样器等参数、模型搜索、更新检查与自动调、参能力、适用于个人创作者、快速试图、简单画图需求场景。这些能力在上述核心功能中均有对应处理逻辑。
## 脚本路径

- `scripts/comfyui_manager.py` — ComfyUI 启动/关闭/状态检查
- `scripts/generate.py` — 图片生成（调用 ComfyUI API）
- `scripts/auto_shutdown.py` — 空闲自动关闭检查
- `config.json` — 配置文件（模型别名、默认参数）

## ComfyUI 生命周期管理

### 启动 ComfyUI

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

启动后默认监听 `http://127.0.0.1:8188`。脚本会等待服务就绪后返回。

### 状态检查

```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 scripts/auto_shutdown.py
```

超过 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 动漫（默认） |
| sdxlv8 | pornmaster_proSDXLV8 | SDXL 写实 |
| flux | flux1-dev-bnb-nf4-v2 | Flux 写实 |

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

## 基础参数指南

| 参数 | 说明 | 推荐值 |
| --- | --- | --- |
| positive | 正向提示词 | 专业 SD 标签格式 |
| model | 模型别名 | noobv6 / sdxlv8 / flux |
| batch_size | 生成数量 | 1-4 |
| width | 图片宽度 | 512-1536 |
| height | 图片高度 | 512-1536 |
| steps | 采样步数 | 20-25 |
| cfg | CFG 引导强度 | 5-7（Flux 用 1） |

## 提示词优化基础

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

## 适用场景

| 场景 | 典型输入 | 输出内容 |
| --- | --- | --- |
| 动漫风格生成 | "用 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,
)
```

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

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

## 异常处理


| 错误场景 | 错误信息 | 原因分析 | 处理方式 |
|---------|---------|---------|---------|
| comfyui_not_running | `Connection refused: 127.0.0.1:8188` | ComfyUI 未启动或启动中 | 调用 `mgr.start()` 启动,等待 10 秒后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令 |
| model_alias_not_found | `Unknown model alias: xxx` | config.json 中无此别名 | 列出可用别名（noobv6/sdxlv8/flux）,引导用户选择 |
| generate_timeout | `ComfyUI generation timeout` | 生成耗时超过 120 秒 | 降低 batch_size 或 steps 后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令 |
| 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响应超时或无响应 | 网络延迟或模型负载过高 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接，执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令请求；确认Agent平台LLM服务正常 |
| 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求，参考示例章节 |
| 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述，补充必要的上下文信息 |
| 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求；检查命令权限设置 |

## 已知限制

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

---

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

SKILL.md

related skills
