creative_studio/docs/API.md

# Creative Studio API 文档

## 概述

Creative Studio 提供 RESTful API 接口，支持项目管理、Skill 管理、记忆系统、审核系统等功能。

**Base URL**: `http://localhost:8000/api/v1`

**认证方式**: Bearer Token (即将支持)

**数据格式**: JSON

---

## 目录

- [Skill 管理 API](#skill-管理-api)
- [项目管理 API](#项目管理-api)
- [记忆系统 API](#记忆系统-api)
- [审核系统 API](#审核系统-api)
- [错误处理](#错误处理)
- [使用示例](#使用示例)

---

## Skill 管理 API

### 1. 列出所有 Skills

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

**查询参数**:

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| skill_type | string | 否 | 筛选类型 (builtin/user) |
| category | string | 否 | 筛选分类 |

**响应示例**:

```json
[
  {
    "id": "dialogue-writer-ancient",
    "name": "古风对话大师",
    "version": "2.1.0",
    "type": "builtin",
    "category": "编剧 > 对话风格",
    "behavior_guide": "你是专业的古风剧集编剧...",
    "tags": ["古风", "对话", "编剧"],
    "created_at": "2024-01-15T10:00:00Z"
  }
]
```

---

### 2. 获取 Skill 详情

```http
GET /api/v1/skills/{skill_id}
```

**路径参数**:

| 参数 | 类型 | 说明 |
|-----|------|------|
| skill_id | string | Skill ID |

**响应示例**:

```json
{
  "id": "dialogue-writer-ancient",
  "name": "古风对话大师",
  "version": "2.1.0",
  "author": "Creative Studio Platform",
  "type": "builtin",
  "behavior_guide": "你是专业的古风剧集编剧...",
  "config": {
    "preset": null,
    "parameters": {},
    "weights": null
  },
  "category": "编剧 > 对话风格",
  "tags": ["古风", "对话", "编剧"]
}
```

---

### 3. 创建新 Skill

```http
POST /api/v1/skills
```

**请求体**:

```json
{
  "id": "my-custom-skill",
  "name": "我的自定义 Skill",
  "content": "# Skill: 我的自定义 Skill\n\n## 行为指导\n你是...",
  "category": "自定义",
  "tags": ["测试"]
}
```

**响应**: 返回创建的 Skill 对象

---

### 4. 测试 Skill

```http
POST /api/v1/skills/{skill_id}/test
```

**请求体**:

```json
{
  "test_input": "请帮我创作一段古风对话",
  "context": {
    "scene": "御花园",
    "characters": ["李云飞", "苏婉儿"]
  },
  "temperature": 0.7
}
```

**响应示例**:

```json
{
  "skill_id": "dialogue-writer-ancient",
  "skill_name": "古风对话大师",
  "response": "【场景】御花园，傍晚\n【人物】李云飞、苏婉儿\n\n李云飞：（拱手）苏姑娘...",
  "usage": {
    "prompt_tokens": 150,
    "completion_tokens": 300,
    "total_tokens": 450
  }
}
```

---

### 5. 更新 Skill

```http
PUT /api/v1/skills/{skill_id}
```

**请求体**:

```json
{
  "name": "更新后的名称",
  "content": "更新后的内容..."
}
```

---

### 6. 删除 Skill

```http
DELETE /api/v1/skills/{skill_id}
```

**响应**: 204 No Content

---

### 7. 重新加载 Skill

```http
POST /api/v1/skills/{skill_id}/reload
```

用于清除缓存并重新加载 Skill。

---

### 8. 列出所有分类

```http
GET /api/v1/skills/categories/list
```

**响应示例**:

```json
["编剧 > 对话风格", "审核 > 一致性", "通用"]
```

---

## 项目管理 API

### 1. 列出所有项目

```http
GET /api/v1/projects
```

**查询参数**:

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| status | string | 否 | 筛选状态 |
| agent_id | string | 否 | 筛选 Agent 类型 |

**响应示例**:

```json
[
  {
    "id": "proj-123",
    "name": "我的古风剧集",
    "description": "一部古装爱情剧",
    "agent_id": "series-creation-agent",
    "status": "active",
    "created_at": "2024-01-15T10:00:00Z",
    "episode_count": 10,
    "completed_episodes": 3
  }
]
```

---

### 2. 创建项目

```http
POST /api/v1/projects
```

**请求体**:

```json
{
  "name": "我的古风剧集",
  "description": "一部古装爱情剧",
  "agent_id": "series-creation-agent",
  "global_context": {
    "world_setting": "古代架空世界...",
    "character_profiles": [...],
    "scene_settings": [...],
    "overall_outline": "..."
  }
}
```

---

### 3. 获取项目详情

```http
GET /api/v1/projects/{project_id}
```

**响应示例**:

```json
{
  "id": "proj-123",
  "name": "我的古风剧集",
  "description": "一部古装爱情剧",
  "agent_id": "series-creation-agent",
  "status": "active",
  "global_context": {...},
  "memory": {...},
  "episodes": [...]
}
```

---

### 4. 更新项目

```http
PUT /api/v1/projects/{project_id}
```

---

### 5. 删除项目

```http
DELETE /api/v1/projects/{project_id}
```

---

### 6. 执行单集创作

```http
POST /api/v1/projects/{project_id}/execute
```

**请求体**:

```json
{
  "episode_number": 4,
  "config": {
    "duration_minutes": 45,
    "focus_areas": ["情感发展", "剧情推进"]
  }
}
```

**响应示例**:

```json
{
  "episode_id": "ep-proj-123-4",
  "episode_number": 4,
  "status": "in_progress",
  "stages": {
    "structure": "completed",
    "outline": "in_progress",
    "dialogue": "pending",
    "review": "pending",
    "memory": "pending"
  }
}
```

---

### 7. 批量执行剧集创作

```http
POST /api/v1/projects/{project_id}/execute-batch
```

**请求体**:

```json
{
  "start_episode": 4,
  "end_episode": 6,
  "batch_config": {
    "quality_threshold": 85,
    "max_retries": 2
  }
}
```

---

### 8. 获取剧集列表

```http
GET /api/v1/projects/{project_id}/episodes
```

---

### 9. 获取单集详情

```http
GET /api/v1/projects/{project_id}/episodes/{episode_number}
```

---

## 记忆系统 API

### 1. 获取项目记忆

```http
GET /api/v1/projects/{project_id}/memory
```

**响应示例**:

```json
{
  "eventTimeline": [...],
  "pendingThreads": [...],
  "characterStates": {...},
  "foreshadowing": [...],
  "relationships": {...}
}
```

---

### 2. 获取事件时间线

```http
GET /api/v1/projects/{project_id}/memory/timeline
```

**查询参数**:

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| character | string | 否 | 筛选角色 |
| episode | int | 否 | 筛选集数 |
| importance | string | 否 | 筛选重要性 (low/medium/high) |

---

### 3. 获取待收线问题

```http
GET /api/v1/projects/{project_id}/memory/threads
```

---

### 4. 添加待收线问题

```http
POST /api/v1/projects/{project_id}/memory/threads
```

**请求体**:

```json
{
  "description": "需要解释为什么主角会失去记忆",
  "importance": "high",
  "reminder_episode": 5
}
```

---

### 5. 更新待收线问题

```http
PUT /api/v1/projects/{project_id}/memory/threads/{thread_id}
```

---

### 6. 标记问题已解决

```http
POST /api/v1/projects/{project_id}/memory/resolve-thread
```

**请求体**:

```json
{
  "thread_id": "thread-123",
  "resolution_episode": 5,
  "resolution_description": "在第五集中揭示..."
}
```

---

### 7. 获取人物状态

```http
GET /api/v1/projects/{project_id}/memory/characters
```

---

## 审核系统 API

### 1. 获取审核配置

```http
GET /api/v1/projects/{project_id}/review-config
```

**响应示例**:

```json
{
  "enabled_review_skills": ["consistency_checker", "dialogue_quality_checker"],
  "overall_strictness": "medium",
  "dimension_settings": {...},
  "custom_rules": [...]
}
```

---

### 2. 更新审核配置

```http
PUT /api/v1/projects/{project_id}/review-config
```

**请求体**:

```json
{
  "enabled_review_skills": ["consistency_checker"],
  "overall_strictness": "strict",
  "dimension_settings": {
    "character_consistency": {
      "enabled": true,
      "strictness": 0.8,
      "weight": 0.5
    }
  }
}
```

---

### 3. 获取审核配置预设

```http
GET /api/v1/projects/{project_id}/review-presets
```

---

### 4. 执行剧集审核

```http
POST /api/v1/projects/{project_id}/episodes/{episode_number}/review
```

**响应示例**:

```json
{
  "episode_id": "ep-proj-123-4",
  "overall_score": 85.5,
  "passed": true,
  "dimension_scores": {
    "character_consistency": 88,
    "plot_coherence": 82,
    "dialogue_quality": 90
  },
  "issues": [
    {
      "id": "issue-1",
      "type": "character_inconsistency",
      "dimension": "character_consistency",
      "severity": "medium",
      "location": {
        "episode": 4,
        "scene": 2,
        "line": 15
      },
      "description": "角色行为与设定不符",
      "suggestion": "建议修改为...",
      "auto_fix_available": true
    }
  ],
  "new_foreshadowing": [...],
  "resolved_threads": [...]
}
```

---

### 5. 获取可用的审核维度

```http
GET /api/v1/review/dimensions
```

---

### 6. 添加自定义规则

```http
POST /api/v1/review/custom-rules
```

**请求体**:

```json
{
  "project_id": "proj-123",
  "rule": {
    "name": "对话自然性检查",
    "description": "检查对话是否过于生硬",
    "trigger_condition": "对话包含超过3个连续的形容词",
    "severity": "medium"
  }
}
```

---

### 7. 删除自定义规则

```http
DELETE /api/v1/review/custom-rules/{rule_id}
```

---

## 错误处理

所有 API 在出错时返回以下格式：

```json
{
  "detail": "错误描述信息"
}
```

**常见 HTTP 状态码**:

| 状态码 | 说明 |
|-------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 204 | 成功（无内容） |
| 400 | 请求参数错误 |
| 404 | 资源不存在 |
| 422 | 数据验证失败 |
| 500 | 服务器内部错误 |

---

## 使用示例

### Python 示例

```python
import requests

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

# 列出所有 Skills
response = requests.get(f"{BASE_URL}/skills")
skills = response.json()
print(skills)

# 测试 Skill
response = requests.post(
    f"{BASE_URL}/skills/dialogue-writer-ancient/test",
    json={
        "test_input": "请帮我创作一段古风对话",
        "temperature": 0.7
    }
)
result = response.json()
print(result["response"])

# 创建项目
response = requests.post(
    f"{BASE_URL}/projects",
    json={
        "name": "我的古风剧集",
        "agent_id": "series-creation-agent",
        "global_context": {...}
    }
)
project = response.json()
print(project)
```

### JavaScript 示例

```javascript
const BASE_URL = "http://localhost:8000/api/v1";

// 列出所有 Skills
const response = await fetch(`${BASE_URL}/skills`);
const skills = await response.json();
console.log(skills);

// 测试 Skill
const result = await fetch(`${BASE_URL}/skills/dialogue-writer-ancient/test`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    test_input: "请帮我创作一段古风对话",
    temperature: 0.7
  })
});
const data = await result.json();
console.log(data.response);

// 创建项目
const project = await fetch(`${BASE_URL}/projects`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "我的古风剧集",
    agent_id: "series-creation-agent",
    global_context: {...}
  })
});
const projectData = await project.json();
console.log(projectData);
```

---

## 附录

### Skill 类型说明

- **builtin**: 平台内置的 Skill，用户不可修改
- **user**: 用户自定义的 Skill，可以编辑和删除

### 项目状态说明

- **draft**: 草稿状态
- **active**: 活跃项目
- **completed**: 已完成
- **archived**: 已归档

### 剧集状态说明

- **pending**: 待创作
- **in_progress**: 创作中
- **completed**: 已完成
- **needs-review**: 需要审核
- **failed**: 创作失败

### 审核问题严重程度说明

- **low**: 低优先级问题
- **medium**: 中等优先级问题
- **high**: 高优先级问题