4.5 KiB

Raw Blame History

移除剧本解析分镜数量参数

日期: 2026-02-09
类型: Breaking Change
影响范围: 剧本解析 API

变更概述

移除 POST /api/v1/screenplays/{screenplay_id}/parse 端点的 storyboardCount 参数，改为系统根据剧本内容自动决定分镜数量。

变更原因

简化用户体验: 用户无需手动指定分镜数量，减少决策负担
智能化: AI 可以根据剧本内容、剧情节奏、场景切换等因素智能生成合适数量的分镜
参数冗余: 已有 auto_create_storyboards 参数控制是否创建分镜，storyboard_count 参数显得多余

变更详情

API 变更

之前:

POST /api/v1/screenplays/{screenplay_id}/parse
{
  "customRequirements": "增加特写镜头",
  "storyboardCount": 10  // 已移除
}

现在:

POST /api/v1/screenplays/{screenplay_id}/parse
{
  "customRequirements": "增加特写镜头"
}

Schema 变更

ScreenplayParseRequest:

❌ 移除: storyboard_count 字段（及其 storyboardCount 别名）
✅ 保留: custom_requirements 字段

后端逻辑变更

AI Service (server/app/services/ai_service.py):
- 移除 storyboard_count 参数
- 更新日志输出
AI Task (server/app/tasks/ai_tasks.py):
- 移除 storyboard_count 参数
- 移除 Prompt 中的固定分镜数量要求
- AI 根据剧本内容自动决定分镜数量
API 路由 (server/app/api/v1/screenplays.py):
- 移除 request.storyboard_count 的传递
- 更新日志输出

测试变更

Schema 测试 (server/tests/unit/schemas/test_screenplay_parse_request.py):
- 移除所有 storyboard_count 相关测试
- 保留 custom_requirements 测试
集成测试 (server/tests/integration/test_screenplay_api.py):
- 移除 test_parse_screenplay_with_storyboard_count_only 测试
- 移除 test_parse_screenplay_storyboard_count_validation 测试
- 更新 test_parse_screenplay_with_custom_requirements 测试
- 新增 test_parse_screenplay_without_requirements 测试

向后兼容性

Breaking Change: 此变更不向后兼容。

前端如果仍然传递 storyboardCount 参数，Pydantic 会忽略该字段（不会报错）
建议前端尽快移除该参数的传递

迁移指南

前端迁移

之前:

const response = await api.post(`/api/v1/screenplays/${id}/parse`, {
  customRequirements: "增加特写镜头",
  storyboardCount: 10  // 移除此行
});

现在:

const response = await api.post(`/api/v1/screenplays/${id}/parse`, {
  customRequirements: "增加特写镜头"
  // 分镜数量由系统自动决定
});

后端迁移

如果有其他服务调用 parse_screenplay 方法，需要移除 storyboard_count 参数：

之前:

await ai_service.parse_screenplay(
    user_id=user_id,
    screenplay_id=screenplay_id,
    screenplay_content=content,
    storyboard_count=10  # 移除此行
)

现在:

await ai_service.parse_screenplay(
    user_id=user_id,
    screenplay_id=screenplay_id,
    screenplay_content=content
    # 分镜数量由 AI 自动决定
)

影响范围

受影响的文件

server/app/schemas/screenplay.py - Schema 定义
server/app/api/v1/screenplays.py - API 路由
server/app/services/ai_service.py - AI Service
server/app/tasks/ai_tasks.py - Celery Task
server/tests/unit/schemas/test_screenplay_parse_request.py - Schema 测试
server/tests/integration/test_screenplay_api.py - 集成测试

不受影响的功能

auto_create_storyboards 参数仍然有效，控制是否创建分镜
分镜创建逻辑不变，仅数量由 AI 自动决定
其他剧本解析功能（角色、场景、道具、标签）不受影响

测试验证

单元测试

docker exec jointo-server-app pytest server/tests/unit/schemas/test_screenplay_parse_request.py -v

集成测试

docker exec jointo-server-app pytest server/tests/integration/test_screenplay_api.py::TestScreenplayParseAPI -v

后续优化

AI Prompt 优化: 调整 AI Prompt，让 AI 更智能地决定分镜数量
分镜质量评估: 收集用户反馈，评估自动分镜的质量
可选参数恢复: 如果用户强烈需要控制分镜数量，可以考虑恢复为可选参数

4.5 KiB Raw Blame History