# ComfyUI-SimpleChat Architecture Design

## Design Philosophy

**Do one thing, do best** - 每个节点只做一件事，做到极致。

## 节点设计原则

1. **单一职责**: 每个节点只负责一个功能
2. **清晰命名**: 节点名称直接表达功能
3. **最少配置**: 合理默认值，减少必填项
4. **美观布局**: 输入输出顺序符合直觉

---

## 节点清单

### 配置节点

| 节点 | 功能 | 设计理念 |
|------|------|----------|
| `API Config` | 配置 API 连接 | 一次配置，到处使用 |

### 对话节点

| 节点 | 功能 | 设计理念 |
|------|------|----------|
| `Chat` | 基础对话 | 最简单的文本对话 |
| `Chat with Image` | 发送图片给 LLM | 视觉理解 |
| `Chat NoASS` | NoASS 格式对话 | 角色扮演优化 |

### 图片生成节点 (Gemini Only)

| 节点 | 功能 | 设计理念 |
|------|------|----------|
| `Gemini Image Gen` | 文生图 | 纯文本生成图片 |
| `Gemini Image Edit` | 图片编辑 | 基于参考图修改 |

---

## 节点详细设计

### 1. API Config

**功能**: 配置 API 连接参数

```
┌─────────────────────────────────────┐
│          🔧 API Config              │
├─────────────────────────────────────┤
│  provider    [openai ▼]             │
│  api_key     [••••••••••]           │
│  base_url    [                    ] │
│  model       [gpt-4o ▼]             │
├─────────────────────────────────────┤
│                          CONFIG ○───│
└─────────────────────────────────────┘
```

**输入:**
- `provider`: 下拉 ["openai", "claude", "gemini"]
- `api_key`: 密码输入
- `base_url`: 文本 (可选，留空使用默认)
- `model`: 可编辑下拉

**输出:**
- `CONFIG`: 配置对象

---

### 2. Chat

**功能**: 基础文本对话

```
┌─────────────────────────────────────┐
│            💬 Chat                  │
├─────────────────────────────────────┤
│ ───○ config                         │
├─────────────────────────────────────┤
│  prompt      [                    ] │
│              [                    ] │
│  system      [                    ] │
│  temperature [1.0    ]              │
│  max_tokens  [2048   ]              │
├─────────────────────────────────────┤
│                            text ○───│
└─────────────────────────────────────┘
```

**输入:**
- `config`: CONFIG (必需)
- `prompt`: 多行文本
- `system`: 系统提示 (可选)
- `temperature`: 0-2, 默认 1.0
- `max_tokens`: 默认 2048

**输出:**
- `text`: STRING

---

### 3. Chat with Image

**功能**: 发送图片给 LLM 分析

```
┌─────────────────────────────────────┐
│        🖼️ Chat with Image           │
├─────────────────────────────────────┤
│ ───○ config                         │
│ ───○ image                          │
├─────────────────────────────────────┤
│  prompt      [Describe this image ] │
│              [                    ] │
│  system      [                    ] │
│  temperature [1.0    ]              │
│  max_tokens  [2048   ]              │
├─────────────────────────────────────┤
│                            text ○───│
└─────────────────────────────────────┘
```

**输入:**
- `config`: CONFIG
- `image`: IMAGE
- `prompt`: 多行文本
- `system`: 系统提示 (可选)
- `temperature`: 0-2
- `max_tokens`: 默认 2048

**输出:**
- `text`: STRING

---

### 4. Chat NoASS

**功能**: NoASS 格式的角色扮演对话

```
┌─────────────────────────────────────┐
│         🎭 Chat NoASS               │
├─────────────────────────────────────┤
│ ───○ config                         │
│ ───○ history (optional)             │
│ ───○ image (optional)               │
├─────────────────────────────────────┤
│  system      [You are...          ] │
│              [                    ] │
│  user_input  [                    ] │
│  user_name   [User    ]             │
│  char_name   [Assistant]            │
│  temperature [1.0    ]              │
│  max_tokens  [2048   ]              │
├─────────────────────────────────────┤
│                            text ○───│
│                         history ○───│
└─────────────────────────────────────┘
```

**输入:**
- `config`: CONFIG
- `history`: STRING (可选，上一轮输出)
- `image`: IMAGE (可选)
- `system`: 系统提示/世界观设定
- `user_input`: 用户本轮输入
- `user_name`: 用户角色名
- `char_name`: AI 角色名
- `temperature`: 0-2
- `max_tokens`: 默认 2048

**输出:**
- `text`: STRING (本轮 AI 回复)
- `history`: STRING (完整对话历史，可连接到下一个节点的 history 输入)

---

### 5. Gemini Image Gen

**功能**: Gemini 文生图

```
┌─────────────────────────────────────┐
│       🎨 Gemini Image Gen           │
├─────────────────────────────────────┤
│ ───○ config (Gemini only)           │
├─────────────────────────────────────┤
│  prompt      [A cat wearing a hat ] │
│              [                    ] │
│  aspect      [1:1 ▼]                │
│  size        [1K ▼]                 │
├─────────────────────────────────────┤
│                           IMAGE ○───│
│                            text ○───│
└─────────────────────────────────────┘
```

**输入:**
- `config`: CONFIG (必须是 Gemini provider)
- `prompt`: 多行文本
- `aspect`: 下拉 ["1:1", "16:9", "9:16", "4:3", "3:4"]
- `size`: 下拉 ["1K", "2K", "4K"]

**输出:**
- `IMAGE`: IMAGE
- `text`: STRING (Gemini 的文字描述)

---

### 6. Gemini Image Edit

**功能**: Gemini 图片编辑

```
┌─────────────────────────────────────┐
│       ✏️ Gemini Image Edit          │
├─────────────────────────────────────┤
│ ───○ config (Gemini only)           │
│ ───○ image                          │
├─────────────────────────────────────┤
│  prompt      [Add a red hat       ] │
│              [                    ] │
│  size        [1K ▼]                 │
├─────────────────────────────────────┤
│                           IMAGE ○───│
│                            text ○───│
└─────────────────────────────────────┘
```

**输入:**
- `config`: CONFIG (必须是 Gemini provider)
- `image`: IMAGE (要编辑的图片)
- `prompt`: 编辑指令
- `size`: 下拉 ["1K", "2K", "4K"]

**输出:**
- `IMAGE`: IMAGE
- `text`: STRING

---

## 数据流示例

### 基础对话

```
[API Config] ──CONFIG──> [Chat] ──text──> [Display Text]
```

### 图片分析

```
[Load Image] ──IMAGE──┐
                      ├──> [Chat with Image] ──text──> [Display Text]
[API Config] ──CONFIG─┘
```

### 多轮 NoASS 对话

```
[API Config] ──CONFIG──> [Chat NoASS] ──history──> [Chat NoASS] ──history──> ...
                              │                         │
                              └──text──>           └──text──>
```

### Gemini 图片生成

```
[API Config] ──CONFIG──> [Gemini Image Gen] ──IMAGE──> [Preview Image]
      │                                           │
      │                                      ──text──> [Display Text]
```

---

## 文件结构

```
custom_nodes/ComfyUI-SimpleChat/
├── __init__.py              # 节点注册
├── nodes/
│   ├── __init__.py
│   ├── config.py            # API Config
│   ├── chat.py              # Chat
│   ├── chat_image.py        # Chat with Image
│   ├── chat_noass.py        # Chat NoASS
│   ├── gemini_gen.py        # Gemini Image Gen
│   └── gemini_edit.py       # Gemini Image Edit
├── core/
│   ├── __init__.py
│   ├── providers/
│   │   ├── __init__.py
│   │   ├── base.py          # Provider 抽象基类
│   │   ├── openai.py        # OpenAI (+ 兼容 API)
│   │   ├── claude.py        # Claude/Anthropic
│   │   └── gemini.py        # Google Gemini
│   ├── noass.py             # NoASS 格式处理
│   └── image_utils.py       # 图片转换
├── docs/                    # 文档
├── requirements.txt
└── README.md
```

---

## 实现优先级

1. **Phase 1**: API Config + Chat (最小可用)
2. **Phase 2**: Chat with Image
3. **Phase 3**: Chat NoASS
4. **Phase 4**: Gemini Image Gen/Edit