# Creative Studio MVP 使用指南

## 快速开始

### 1. 启动后端

```powershell
cd backend
.\start.bat
```

### 2. 启动前端

```powershell
cd frontend
npm install
npm run dev
```

### 3. 配置 GLM API Key

编辑 `backend\.env` 文件：

```env
ZHIPUAI_API_KEY=your_api_key_here
```

获取 API Key: https://open.bigmodel.cn/usercenter/apikeys

---

## 完整创作流程演示

### 步骤 1: 创建项目

1. 访问 http://localhost:5173
2. 点击 "创建新项目"
3. 填写项目信息：

```
项目名称: 宫廷风云
总集数: 30

世界观设定: 架空朝代天启朝，皇权与相权之争

风格指南: 古风正剧，对话半文半白

主要人物:
李云飞：边关将军，耿直刚正，说话简练直接
苏婉儿：丞相之女，聪慧隐忍，说话含蓄委婉

整体大纲:
EP01-05：相识与相恋，两人被迫分离
EP06-15：宫中斗争，婉儿周旋，云飞征战
EP16-25：真相大白，联手对抗丞相
EP26-30：最终对决，有情人终成眷属
```

### 步骤 2: 开始创作

1. 进入项目详情页
2. 点击 "开始创作 (EP1-EP3)"
3. 等待 AI 创作完成（每集约需 30-60 秒）

### 步骤 3: 查看结果

1. 创作完成后，剧集列表会显示已完成
2. 点击 "查看内容" 查看剧本
3. 可以看到大纲、完整剧本、质量分数

---

## API 使用示例

### 使用 Swagger UI

访问 http://localhost:8000/docs

#### 1. 查看所有 Skills

```
GET /api/v1/skills
```

#### 2. 测试 Skill

```
POST /api/v1/skills/dialogue_writer_ancient/test
{
  "test_input": "请创作一段古风对话：李云飞向苏婉儿告别",
  "temperature": 0.7
}
```

#### 3. 创建项目

```
POST /api/v1/projects
{
  "name": "宫廷风云",
  "totalEpisodes": 30,
  "globalContext": {
    "worldSetting": "架空朝代天启朝...",
    "characterProfiles": {
      "char_1": {
        "name": "李云飞",
        "description": "边关将军",
        "personality": "耿直刚正",
        "speechStyle": "简练直接"
      }
    }
  }
}
```

#### 4. 执行剧集创作

```
POST /api/v1/projects/{project_id}/execute
{
  "episodeNumber": 1,
  "title": "初识"
}
```

---

## Python 脚本示例

### 完整创作流程脚本

```python
import requests
import time

BASE_URL = "http://localhost:8000/api/v1"

# 1. 创建项目
project_data = {
    "name": "测试项目",
    "totalEpisodes": 3,
    "globalContext": {
        "worldSetting": "架空朝代，皇权与相权之争",
        "overallOutline": "EP1-3：相识与相恋"
    }
}

response = requests.post(f"{BASE_URL}/projects", json=project_data)
project = response.json()
project_id = project["id"]
print(f"✅ 项目创建成功: {project_id}")

# 2. 执行 EP1 创作
print("\n🎬 开始创作 EP1...")
start_time = time.time()

response = requests.post(
    f"{BASE_URL}/projects/{project_id}/execute",
    json={"episodeNumber": 1, "title": "初识"}
)

result = response.json()
if result["success"]:
    episode = result["episode"]
    print(f"✅ EP1 创作完成!")
    print(f"   质量分数: {episode['qualityScore']}")
    print(f"   创作耗时: {time.time() - start_time:.1f}秒")
    print(f"\n📜 剧本预览:")
    print(episode["content"][:500] + "...")
else:
    print(f"❌ 创作失败: {result['message']}")

# 3. 获取所有剧集
response = requests.get(f"{BASE_URL}/projects/{project_id}/episodes")
episodes = response.json()
print(f"\n📊 已完成 {len(episodes)} 集")
for ep in episodes:
    print(f"   EP{ep['number']}: {ep['status']} - 分数: {ep.get('qualityScore', 'N/A')}")
```

### 批量创作脚本

```python
import requests
import time

BASE_URL = "http://localhost:8000/api/v1"
project_id = "your-project-id"

# 批量创作 EP1-EP5
for ep_num in range(1, 6):
    print(f"\n🎬 创作 EP{ep_num}...")

    start = time.time()
    response = requests.post(
        f"{BASE_URL}/projects/{project_id}/execute",
        json={"episodeNumber": ep_num}
    )

    result = response.json()
    elapsed = time.time() - start

    if result["success"]:
        episode = result["episode"]
        print(f"✅ 完成 - 分数: {episode['qualityScore']} - 耗时: {elapsed:.1f}秒")
    else:
        print(f"❌ 失败: {result['message']}")
```

---

## cURL 示例

### 创建项目

```bash
curl -X POST http://localhost:8000/api/v1/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "宫廷风云",
    "totalEpisodes": 3,
    "globalContext": {
      "worldSetting": "架空朝代天启朝",
      "overallOutline": "EP1-3：相识与相恋"
    }
  }'
```

### 执行创作

```bash
curl -X POST http://localhost:8000/api/v1/projects/{project_id}/execute \
  -H "Content-Type: application/json" \
  -d '{
    "episodeNumber": 1,
    "title": "初识"
  }'
```

---

## 预期输出示例

### 创作完成的剧本

```
【场景】御花园，傍晚，落霞满天
【人物】李云飞、苏婉儿

李云飞：（拱手）苏姑娘，此地不宜久留。

苏婉儿：（轻叹）将军所言极是，只是...

李云飞：（环顾四周）只是什么？

苏婉儿：（低头）只是婉儿不知何时才能再与将军相见。

李云飞：（沉默片刻）三年，三年后我必回来。

苏婉儿：（猛地抬头）三年？太久了...

李云飞：（坚定）这是我能做到的极限。

【场景转换】
宫门之外，李云飞翻身上马，最后回首望向宫墙深处...

```

---

## 故障排查

### 问题 1: GLM API 调用失败

**症状**: 创作失败，提示 "GLM API 调用失败"

**解决**:
1. 检查 `.env` 文件中的 `ZHIPUAI_API_KEY` 是否正确
2. 确认 API Key 有效且有足够额度
3. 检查网络连接

### 问题 2: 创作结果为空

**症状**: 创作完成但内容为空

**解决**:
1. 查看后端日志
2. 尝试降低 `temperature` 参数
3. 检查提示词是否过长

### 问题 3: 前端无法连接后端

**症状**: 前端报错 "Network Error"

**解决**:
1. 确认后端服务正在运行 (http://localhost:8000)
2. 检查 CORS 配置
3. 确认前端代理配置正确

---

## MVP 功能限制

当前 MVP 版本的功能限制：

| 功能 | 状态 | 说明 |
|-----|------|------|
| 项目管理 | ✅ | 完整支持 |
| 单集执行 | ✅ | 完整支持 |
| 批量执行 | ✅ | 简化实现 |
| 记忆系统 | ⚠️ | 简化版（仅记录事件） |
| 审核系统 | ⚠️ | 简化版（LLM 评分） |
| Agent 管理 | ❌ | 未实现（使用固定 Agent） |
| Skill 配置 | ⚠️ | 仅支持内置 Skills |
| 用户创建 Skill | ✅ | 支持 |
| 数据持久化 | ❌ | 内存存储（重启丢失） |

---

## 下一步

MVP 验证通过后，可以继续实现：

1. **数据持久化** - 集成 MongoDB 存储项目和剧集
2. **完整记忆系统** - 事件时间线、伏笔追踪
3. **高级审核** - 多维度审核、问题定位
4. **Agent 管理** - 可视化 Agent 工作流
5. **实时执行监控** - WebSocket 推送创作进度