# 画布工作流参考文档

本文档提供画布工作流的详细技术参考。

## 节点类型完整参考

### PROMPT_INPUT（提示词输入）

**用途**：接收用户输入的文本提示词

**必需字段**：
- `type`: "PROMPT_INPUT"
- `data.prompt`: 提示词文本
- `data.label`: 节点标签

**可选字段**：
- `position`: {x, y} 坐标

**示例**：
```json
{
  "id": "prompt_1",
  "type": "PROMPT_INPUT",
  "data": {
    "prompt": "一位年轻的魔法师",
    "label": "提示词输入"
  },
  "position": {"x": 100, "y": 100}
}
```

### PROMPT_GENERATOR（提示词生成器）

**用途**：优化和扩展提示词

**必需字段**：
- `type`: "PROMPT_GENERATOR"
- `data.style`: 风格（anime, realistic, cinematic, cartoon）
- `data.label`: 节点标签

**可选字段**：
- `data.quality_keywords`: 是否添加质量关键词（默认 true）
- `data.negative_prompt`: 负面提示词

**示例**：
```json
{
  "id": "prompt_gen_1",
  "type": "PROMPT_GENERATOR",
  "data": {
    "style": "anime",
    "quality_keywords": true,
    "label": "提示词优化"
  }
}
```

### IMAGE_GENERATOR（图像生成器）

**用途**：生成图像

**必需字段**：
- `type`: "IMAGE_GENERATOR"
- `data.model`: 模型名称（z-image, wan2.6-image, qwen-image）
- `data.label`: 节点标签

**可选字段**：
- `data.size`: 尺寸（1024x1024, 1344x768, 768x1344 等）
- `data.steps`: 步数（20-100，默认 30）
- `data.seed`: 随机种子

**示例**：
```json
{
  "id": "img_gen_1",
  "type": "IMAGE_GENERATOR",
  "data": {
    "model": "z-image",
    "size": "1024x1024",
    "steps": 30,
    "label": "图像生成"
  }
}
```

### VIDEO_GENERATOR（视频生成器）

**用途**：生成视频

**必需字段**：
- `type`: "VIDEO_GENERATOR"
- `data.model`: 模型名称（wan2.6-video, kling-v2-6）
- `data.label`: 节点标签

**可选字段**：
- `data.duration`: 时长（5, 6, 10 秒）
- `data.size`: 尺寸（1280x720, 720x1280, 1024x1024）
- `data.mode`: 模式（text_to_video, image_to_video）

**示例**：
```json
{
  "id": "video_gen_1",
  "type": "VIDEO_GENERATOR",
  "data": {
    "model": "wan2.6-video",
    "duration": 6,
    "size": "1280x720",
    "mode": "text_to_video",
    "label": "视频生成"
  }
}
```

## 连接规则完整列表

### 有效连接

| 源节点 | 目标节点 | 说明 |
|--------|---------|------|
| PROMPT_INPUT | PROMPT_GENERATOR | 提示词输入到优化 |
| PROMPT_INPUT | IMAGE_GENERATOR | 直接生成图像 |
| PROMPT_INPUT | VIDEO_GENERATOR | 直接生成视频 |
| PROMPT_GENERATOR | IMAGE_GENERATOR | 优化后生成图像 |
| PROMPT_GENERATOR | VIDEO_GENERATOR | 优化后生成视频 |
| IMAGE_GENERATOR | VIDEO_GENERATOR | 图像转视频 |
| IMAGE_GENERATOR | IMAGE_EDITOR | 图像编辑 |
| IMAGE_GENERATOR | INFO_DISPLAY | 显示结果 |
| VIDEO_GENERATOR | VIDEO_ANALYZER | 视频分析 |
| VIDEO_GENERATOR | INFO_DISPLAY | 显示结果 |
| * | INFO_DISPLAY | 任何节点都可以连接到展示 |

### 无效连接

| 源节点 | 目标节点 | 原因 |
|--------|---------|------|
| VIDEO_GENERATOR | IMAGE_GENERATOR | 不支持视频转图像 |
| INFO_DISPLAY | * | 展示节点应该是终点 |
| * | PROMPT_INPUT | 输入节点应该是起点 |

## 工具 API 参考

### create_workflow_chain

创建线性工作流链。

**参数**：
- `workflow_type` (str): 工作流类型
  - "text_to_image": 文生图
  - "text_to_video": 文生视频
  - "image_to_video": 图生视频
  - "character_showcase": 角色展示
- `start_prompt` (str): 起始提示词
- `style` (str, 可选): 视觉风格，默认 "anime"
- `image_model` (str, 可选): 图像模型，默认 "z-image"
- `video_model` (str, 可选): 视频模型，默认 "wan2.6-video"

**返回**：
```json
{
  "workflow_id": "wf_xxx",
  "nodes": [...],
  "edges": [...]
}
```

### create_node_group

创建节点组。

**参数**：
- `nodes` (list): 节点列表
- `layout` (str, 可选): 布局类型（horizontal, vertical, grid）

**返回**：
```json
{
  "group_id": "group_xxx",
  "nodes": [...]
}
```

### connect_nodes

连接两个节点。

**参数**：
- `source_id` (str): 源节点 ID
- `target_id` (str): 目标节点 ID
- `source_handle` (str, 可选): 源句柄
- `target_handle` (str, 可选): 目标句柄

**返回**：
```json
{
  "edge_id": "edge_xxx",
  "source": "...",
  "target": "..."
}
```

## 错误代码参考

| 错误代码 | 说明 | 解决方案 |
|---------|------|---------|
| INVALID_NODE_TYPE | 无效的节点类型 | 检查节点类型拼写 |
| INVALID_CONNECTION | 无效的连接 | 查看连接规则 |
| MISSING_REQUIRED_FIELD | 缺少必需字段 | 检查节点配置 |
| DUPLICATE_NODE_ID | 重复的节点 ID | 使用唯一 ID |
| CIRCULAR_DEPENDENCY | 循环依赖 | 避免循环连接 |
