# Changelog: AI Prompt System v2.0 - 剧本解析接口增强

**日期**: 2026-02-07  
**类型**: 功能增强 (Feature Enhancement)  
**模块**: AI 服务 / 剧本解析  
**影响范围**: API、Service、Celery Task  

---

## 📋 变更摘要

为 `/api/v1/screenplays/{screenplay_id}/parse` 接口新增 2 个用户可见参数，支持个性化剧本解析需求。

---

## 🎯 新增功能

### 1. 用户可见参数（置顶显示）

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `customRequirements` | string | 否 | - | 用户个性化要求（如：增加特写镜头、强调情绪变化等），最大 500 字符 |
| `storyboardCount` | integer | 否 | 10 | 期望生成的分镜数量，范围：3-12 |

### 2. 高级选项参数（前端可选传递）

保留原有 6 个高级参数：
- `model`: AI 模型名称
- `autoCreateElements`: 是否自动创建元素
- `autoCreateTags`: 是否自动创建标签
- `autoCreateStoryboards`: 是否自动创建分镜
- `temperature`: 温度参数
- `maxTokens`: 最大 token 数

---

## 🔧 技术实现

### 1. Schema 层（`app/schemas/screenplay.py`）

```python
class ScreenplayParseRequest(BaseModel):
    # 用户可见参数（置顶）
    custom_requirements: Optional[str] = Field(
        None,
        alias="customRequirements",
        description="用户个性化要求",
        max_length=500
    )
    
    storyboard_count: int = Field(
        10,
        alias="storyboardCount",
        description="期望生成的分镜数量（范围：3-12）",
        ge=3,
        le=12
    )
    
    # 高级选项（6 个原有参数保持不变）
    # ...
```

### 2. API 层（`app/api/v1/screenplays.py`）

- ✅ 新增日志记录：记录 `custom_requirements` 和 `storyboard_count`
- ✅ 参数传递：将新参数传递给 `AIService.parse_screenplay()`

### 3. Service 层（`app/services/ai_service.py`）

- ✅ 方法签名更新：`parse_screenplay()` 新增 2 个参数
- ✅ 日志记录：记录新参数
- ✅ 参数持久化：将新参数存入 `task_params` 和 `input_data`
- ✅ Celery 任务调用：传递新参数到 `parse_screenplay_task.delay()`

### 4. Celery 任务层（`app/tasks/ai_tasks.py`）

#### 4.1 参数接收

```python
def parse_screenplay_task(
    self,
    job_id: str,
    user_id: str,
    screenplay_id: str,
    screenplay_content: str,
    custom_requirements: Optional[str] = None,
    storyboard_count: int = 10,
    model: str = 'gpt-4',
    # ...
):
```

#### 4.2 动态提示词构建

**基础提示词** → **用户要求注入** → **分镜数量注入** → **完整提示词**

```python
# 1. 基础提示词（参考 docs/prompts/screenplay-ai-parse-prompt.md）
system_prompt = """
# 系统角色
你是一个专业的影视剧本分析专家...

# 任务说明
请分析以下剧本，提取所有角色、场景、道具信息...
"""

# 2. 动态注入用户个性化要求
if custom_requirements:
    system_prompt += f"""
## 用户特殊要求
{custom_requirements}

请在分析剧本时特别注意以上用户要求...
"""

# 3. 动态注入分镜数量要求
system_prompt += f"""
## 分镜生成要求
- **目标分镜数量**：{storyboard_count} 个
- **分镜分布**：根据剧情节奏和关键情节合理分配分镜数量
...
"""
```

---

## 📦 数据流

```
Frontend Request (JSON)
  ↓
API Layer (screenplays.py)
  ↓ 接收参数 + 权限校验
Service Layer (ai_service.py)
  ↓ 积分扣除 + 任务创建
Celery Task (ai_tasks.py)
  ↓ 动态构建提示词
AI Provider (OpenAI/Claude)
  ↓ 返回解析结果
Database Storage
```

---

## 🧪 测试建议

### 1. 单元测试

```python
# tests/services/test_ai_service.py
async def test_parse_screenplay_with_custom_requirements():
    """测试带个性化要求的剧本解析"""
    result = await ai_service.parse_screenplay(
        user_id=user_id,
        screenplay_id=screenplay_id,
        screenplay_content="剧本内容...",
        custom_requirements="增加人物特写镜头",
        storyboard_count=8
    )
    assert result['status'] == 'pending'
```

### 2. 集成测试

```python
# tests/api/test_screenplays.py
async def test_parse_screenplay_api_with_new_params():
    """测试新参数的 API 调用"""
    response = await client.post(
        f"/api/v1/screenplays/{screenplay_id}/parse",
        json={
            "customRequirements": "强调情绪变化",
            "storyboardCount": 12,
            "model": "gpt-4"
        }
    )
    assert response.status_code == 202
```

### 3. 参数验证测试

```python
# tests/schemas/test_screenplay.py
def test_storyboard_count_validation():
    """测试分镜数量范围验证"""
    # 正常范围
    request = ScreenplayParseRequest(storyboard_count=10)
    assert request.storyboard_count == 10
    
    # 低于最小值
    with pytest.raises(ValidationError):
        ScreenplayParseRequest(storyboard_count=2)
    
    # 高于最大值
    with pytest.raises(ValidationError):
        ScreenplayParseRequest(storyboard_count=13)
```

---

## 📝 前端集成示例

### Request Body

```json
{
  "customRequirements": "增加人物特写镜头，注重情感表达",
  "storyboardCount": 10,
  "model": "gpt-4",
  "autoCreateElements": true,
  "autoCreateTags": true,
  "autoCreateStoryboards": true,
  "temperature": 0.7,
  "maxTokens": 4000
}
```

### Response

```json
{
  "code": 200,
  "message": "剧本解析任务已提交，请使用 jobId 查询任务状态",
  "data": {
    "jobId": "uuid-v7-job-id",
    "taskId": "celery-task-id",
    "status": "pending",
    "estimatedCredits": 50
  }
}
```

---

## 🎨 UI 建议

### 前端表单设计

```
┌─────────────────────────────────────┐
│ 剧本解析设置                         │
├─────────────────────────────────────┤
│ 📝 个性化要求（选填）                │
│ ┌─────────────────────────────────┐ │
│ │ 例如：增加特写镜头、强调情绪变化 │ │
│ └─────────────────────────────────┘ │
│                                     │
│ 🎬 分镜数量（3-12）                  │
│ ┌─────────────────────────────────┐ │
│ │ [滑块] 10                        │ │
│ └─────────────────────────────────┘ │
│                                     │
│ [高级选项 ▼]                         │
│                                     │
│ [开始解析]                           │
└─────────────────────────────────────┘
```

---

## 🚀 部署检查清单

- [x] Schema 更新
- [x] API 路由更新
- [x] Service 层更新
- [x] Celery 任务更新
- [x] 动态提示词构建
- [x] 代码 Lint 检查通过
- [ ] 单元测试编写
- [ ] 集成测试编写
- [ ] 前端联调测试
- [ ] 生产环境验证

---

## 📚 相关文档

- [AI Prompt System v2.0 设计文档](../requirements/backend/04-services/ai/ai-prompt-system-service.md)
- [剧本解析提示词模板](../../prompts/screenplay-ai-parse-prompt.md)
- [AI 服务测试规范](../../guides/ai-development-prompts.md)

---

## ⚠️ 注意事项

1. **参数优先级**：用户个性化要求会附加到基础提示词之后，不会覆盖核心指令
2. **分镜数量控制**：AI 会尝试生成目标数量的分镜，但可能根据剧本长度自动调整
3. **积分消耗**：新参数不影响积分计算规则（仍按剧本字符数计算）
4. **向后兼容**：所有新参数均为可选，旧版前端调用不受影响

---

## 🔄 后续优化方向

1. **AI Skill Registry 集成**：将提示词模板迁移到 `ai_skills_registry` 表
2. **多阶段解析**：支持长剧本的分批次解析（参考 Two-Stage Parsing Strategy）
3. **提示词版本管理**：支持提示词的 A/B 测试和版本回滚
4. **预设模板**：提供"动作片"、"文艺片"等预设个性化要求模板

---

**变更人员**: AI Agent (Claude Sonnet 4.5)  
**审核状态**: Pending  
**版本**: v1.0.0