creative_studio/COMPLETE_GUIDE.md

# Creative Studio - 完整平台使用指南

## 🎯 功能概览

| 功能模块 | 状态 | 说明 |
|---------|------|------|
| **Skills 管理中心** | ✅ | 查看、测试、配置所有 Skills |
| **Agents 管理中心** | ✅ | 查看 Agent 工作流、配置绑定 |
| **项目创建** | ✅ | 上传剧本、AI 辅助生成、Skill 选择 |
| **执行监控** | ✅ | 实时进度、各阶段状态、日志输出 |
| **项目详情** | ✅ | 查看设定、管理剧集、查看内容 |

---

## 🚀 快速开始

### 1. 启动服务

```powershell
# 后端
cd backend
.\start.bat

# 前端
cd frontend
npm run dev
```

### 2. 访问平台

- **前端**: http://localhost:5173
- **API 文档**: http://localhost:8000/docs

---

## 📖 完整使用流程

### 方案 A: 上传剧本改编（推荐）

适合：已有现成的剧本，想要快速改编

#### 步骤 1: 创建项目
1. 访问 http://localhost:5173
2. 点击 "创建新项目"
3. 选择创作方式：**上传剧本**
4. 上传你的剧本文件（.txt, .md, .docx）
5. 系统会自动解析剧本

#### 步骤 2: AI 辅助完善（可选）
1. 点击 "AI 辅助生成" 按钮
2. AI 会根据你的剧本内容：
   - 提取主要人物
   - 生成人物小传
   - 优化大纲结构

#### 步骤 3: 配置 Skills
1. 选择对话创作 Skills（如：古风对话大师）
2. 选择审核 Skills（如：一致性审核器）
3. 查看每个 Skill 的行为指导

#### 步骤 4: 执行创作
1. 进入项目详情页
2. 选择要创作的集数
3. 点击 "执行单集" 或 "批量执行"
4. 实时查看 Agent 执行进度

---

### 方案 B: 从头创作 + AI 辅助

适合：只有一个初步想法或框架

#### 步骤 1: 创建项目
1. 点击 "创建新项目"
2. 选择创作方式：**从头创作**
3. 输入项目名称和集数

#### 步骤 2: AI 辅助生成
1. 在 "AI 辅助完善" 页面：
   - 输入你的初步想法，例如：
     > "一个架空朝代，边关将军与丞相之女的爱情故事，充满政治阴谋"

   - 点击 "AI 生成人物" → AI 自动生成人物设定
   - 点击 "AI 生成大纲" → AI 自动生成完整大纲

2. 你可以修改 AI 生成的内容

#### 步骤 3-4: 同方案 A

---

## 🎛️ 功能详解

### Skills 管理中心

访问路径：`http://localhost:5173/skills`

#### 功能
- **查看所有 Skills**: 内置 + 用户创建的
- **测试 Skill**: 输入测试内容，查看 AI 输出
- **查看行为指导**: 了解 Skill 如何指导 AI
- **分类筛选**: 按编剧、审核、通用等分类

#### 内置 Skills

| Skill ID | 名称 | 用途 |
|---------|------|------|
| `dialogue_writer_ancient` | 古风对话大师 | 创作古风风格对话 |
| `consistency_checker` | 一致性审核器 | 检查内容一致性 |

---

### Agents 管理中心

访问路径：`http://localhost:5173/agents`

#### 功能
- **查看 Agent 工作流**: 可视化 5 阶段流程
- **查看 Skill 绑定**: 每个阶段使用什么 Skill
- **配置 Skill**: 可配置阶段更换 Skill

#### 剧集创作 Agent 工作流

```
1. 加载全局上下文 (固定)
   ↓
2. 结构分析 → 使用 Skill: script-structure-analyzer
   ↓
3. 大纲生成 → 使用 Skill: outline-generator
   ↓
4. 对话创作 → 使用 Skill: dialogue-writer (可配置) ⭐
   ↓
5. 一致性审核 → 使用 Skill: consistency-checker
   ↓
6. 更新记忆系统 (固定)
```

---

### 执行监控页面

访问路径：`http://localhost:5173/projects/{id}/execute`

#### 功能
- **实时进度**: 显示当前执行的阶段
- **执行日志**: 显示详细的执行日志
- **批次执行**: 一键执行 EP1-EP3
- **查看结果**: 点击已完成的剧集查看内容

#### 执行日志示例

```
[阶段 1] 加载全局上下文 开始...
[阶段 1] 加载全局上下文 完成 ✓
[阶段 2] 结构分析 开始...
[阶段 2] 结构分析 完成 ✓
[阶段 3] 大纲生成 开始...
[阶段 3] 大纲生成 完成 ✓
[阶段 4] 对话创作 开始...
使用 Skill: dialogue_writer_ancient
[阶段 4] 对话创作 完成 ✓
[阶段 5] 一致性审核 开始...
[阶段 5] 一致性审核 完成 ✓

✅ EP1 创作完成！
```

---

## 🔧 API 端点说明

### AI 辅助生成 API

| 端点 | 功能 | 使用场景 |
|-----|------|---------|
| `POST /api/v1/ai-assistant/generate/characters` | 生成人物设定 | 用户只有初步想法 |
| `POST /api/v1/ai-assistant/generate/outline` | 生成大纲 | 用户提供框架 |
| `POST /api/v1/ai-assistant/parse/script` | 解析剧本 | 上传剧本后提取 |
| `GET /api/v1/ai-assistant/available-skills` | 获取可用 Skills | 项目创建时选择 |

### 使用示例：生成人物设定

```bash
curl -X POST http://localhost:8000/api/v1/ai-assistant/generate/characters \
  -H "Content-Type: application/json" \
  -d '{
    "idea": "架空朝代，边关将军李云飞与丞相之女苏婉儿的爱情故事"
  }'
```

---

## 💡 使用技巧

### 1. 充分利用 AI 辅助

- **人物设定**: 输入简短描述，让 AI 扩展成完整小传
- **大纲生成**: 输入故事框架，让 AI 生成详细大纲
- **修改完善**: AI 生成后可以手动调整

### 2. 选择合适的 Skills

- **古风剧**: 选择 `dialogue_writer_ancient`
- **现代剧**: 可以创建新的对话风格 Skill
- **审核**: 始终启用 `consistency_checker`

### 3. 执行策略

- **小规模**: 1-3 集，手动查看每个
- **中规模**: 4-10 集，分批次执行
- **大规模**: 11+ 集，全自动模式（开发中）

---

## 🐛 故障排查

### 问题 1: Skills 未加载

**解决**: 重启后端服务，确保 Skills 在正确目录

### 问题 2: AI 生成失败

**解决**:
1. 检查 `.env` 中的 `ZHIPUAI_API_KEY`
2. 确认网络连接正常
3. 查看 API Key 是否有额度

### 问题 3: 执行卡住

**解决**:
1. 检查后端日志
2. 确认 GLM API 调用正常
3. 刷新页面重新执行

---

## 📊 完整创作流程图

```
┌─────────────────────────────────────────────┐
│         1. 选择创作方式                      │
├─────────────────────────────────────────────┤
│  [上传剧本改编]    或    [从头创作+AI辅助]     │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│         2. AI 辅助完善 (可选)                │
├─────────────────────────────────────────────┤
│  • AI 生成人物设定                           │
│  • AI 生成完整大纲                           │
│  • 手动调整完善                               │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│         3. 配置 Skills                       │
├─────────────────────────────────────────────┤
│  • 选择对话创作 Skill (古风/现代等)          │
│  • 选择审核 Skill                             │
│  • 查看 Skill 的行为指导                     │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│         4. 执行创作                           │
├─────────────────────────────────────────────┤
│  • 选择要创作的集数                          │
│  • 点击执行                                  │
│  • 实时查看进度和日志                        │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│         5. 查看结果                           │
├─────────────────────────────────────────────┤
│  • 查看剧本内容                              │
│  • 查看质量分数                              │
│  • 查看审核问题                              │
│  • 导出或继续下一集                            │
└─────────────────────────────────────────────┘
```

---

## 🎯 下一步功能

计划中的功能：

- [ ] **数据持久化** - MongoDB 集成
- [ ] **实时进度推送** - WebSocket
- [ ] **更多内置 Skills** - 覆盖更多风格类型
- [ ] **自定义 Skill 创建器** - 可视化创建 Skill
- [ ] **项目模板** - 预设项目模板
- [ ] **导出功能** - 导出为 Word/PDF

---

**Creative Studio** - 让 AI 创作更简单、更可控