# 剧本 AI 解析语法错误和格式兼容性修复

**日期**: 2026-02-09  
**类型**: Bug Fix  
**影响范围**: 剧本解析功能、Celery Worker

## 问题描述

剧本 AI 解析功能存在两个关键问题：

### 1. Python 语法错误导致 Celery Worker 启动失败

多个文件中存在语法错误：
- `server/app/tasks/ai_tasks.py` 第 1088 行：多余的三引号和分隔符导致 docstring 未关闭
- `server/app/tasks/ai_tasks.py` 第 1217 行：中文全角括号 `（）`
- `server/app/services/ai_service.py` 第 1029 行：中文全角括号
- `server/app/repositories/ai_job_repository.py` 第 356 行：中文全角括号

**错误信息**:
```
SyntaxError: unterminated triple-quoted string literal (detected at line 1245)
SyntaxError: invalid character '（' (U+FF08)
```

**影响**: Celery Worker 无法启动，所有 AI 任务无法处理

### 2. AI 返回格式不匹配

AI 实际返回的 JSON 格式与代码预期不一致：
- **场景数组键名**: AI 返回 `scenes`，代码期望 `locations`
- **场景对象字段**: AI 返回 `location` 字段，代码期望 `name` 字段

**影响**: 所有场景被跳过，最终创建 0 个元素

## 修复方案

### 1. 修复 Python 语法错误

#### 修复 ai_tasks.py 第 1088 行

**错误代码**:
```python
# 移除固定分镜数量要求，让 AI 根据剧本内容自动决定
# AI 会根据剧情节奏、关键情节、场景切换等因素智能生成合适数量的分镜

---
"""

result = await provider.process_text(
```

**修复后**:
```python
# 移除固定分镜数量要求，让 AI 根据剧本内容自动决定
# AI 会根据剧情节奏、关键情节、场景切换等因素智能生成合适数量的分镜

result = await provider.process_text(
```

#### 修复中文全角括号

将所有 docstring 中的中文全角括号 `（）` 替换为英文半角括号 `()`：

```python
# 修复前
timeout_minutes: 超时时间（分钟），默认 30 分钟

# 修复后
timeout_minutes: 超时时间(分钟), 默认 30 分钟
```

### 2. 增强格式转换逻辑

修改 `ScreenplayService._transform_ai_tags_format()` 方法：

```python
# 支持 AI 返回 scenes 键名
if 'scenes' in parsed_data and 'locations' not in parsed_data:
    parsed_data['locations'] = parsed_data.pop('scenes')
    logger.warning("AI 返回了 'scenes' 键名，已自动转换为 'locations'")

# 增强场景名称提取逻辑
for location in parsed_data.get('locations', []):
    if 'name' not in location:
        if 'title' in location:
            location['name'] = location.pop('title')
        elif 'location' in location:
            location['name'] = location.pop('location')
        else:
            logger.warning(f"场景缺少 name/title/location 字段，跳过: {location}")
            continue
```

## 测试验证

### 1. 语法检查
```bash
docker exec jointo-server-app python -m py_compile app/tasks/ai_tasks.py
# ✅ 语法检查通过
```

### 2. Celery Worker 启动
```bash
docker restart jointo-server-celery-ai
docker logs jointo-server-celery-ai --tail 30
# ✅ celery@xxx ready.
```

### 3. 剧本解析测试
- 剧本 ID: `019c4104-7231-75c0-9420-a7d143465f0e`
- 剧本名称：《狮子回头剧本for周室长》
- 文件大小：38,065 字符，3100 行
- **预期结果**: 成功提取角色、场景、道具、分镜

## 影响范围

- ✅ 修复 Celery Worker 启动失败问题
- ✅ 修复剧本 AI 解析功能，支持 AI 实际返回的格式
- ✅ 提升代码健壮性，支持多种字段名变体

## 相关文件

- `server/app/tasks/ai_tasks.py` - 语法错误修复
- `server/app/services/ai_service.py` - 语法错误修复
- `server/app/repositories/ai_job_repository.py` - 语法错误修复
- `server/app/services/screenplay_service.py` - 格式转换逻辑

## 后续优化建议

1. **代码规范**: 建立 pre-commit hook 检查中文全角字符
2. **AI Prompt 优化**: 更新 AI Skill 提示词，明确要求使用 `locations` 键名和 `name` 字段
3. **Schema 验证**: 添加 Pydantic Schema 验证 AI 返回格式