v0.4.0 发布说明
v0.4.0 发布说明
2026年5月6日·Jellyfish Team
v0.4.0 重构了提示词的生产方式,并补齐了视频与配音环节长期缺失的闭环。
在此之前,提示词模板散落在代码常量里、项目风格只是一句弱提示、视频每次生成都会覆写上一版、对白情绪从脚本提取出来就被丢掉。本次把这些都收敛成显式、可验证、可回滚的链路。
Highlights
- 提示词 IR 与 H3 渲染器:新增中间表示层
app/chains/prompts/ir.py,把镜头业务数据先整理成结构化 IR,再由renderers/输出目标模型需要的格式,解决“提示词正文里的图片编号与实际上传顺序不一致”的根本问题。 - 提示词模板落库:14 个类别的模板从代码常量迁移到数据库
prompt_templates表,迁移文件由backend/scripts/gen_prompt_templates_sql.py生成,杜绝手抄漂移。 - 项目级风格包与统一负面提示词:
app/chains/prompts/style_pack.py一处配置、全局注入,并按visual_style与style自动选择形态包与题材包。 - 视频抽卡与版本切换:同一分镜的每次生成都留档,当前使用哪一版是一个可切换的指针,历史永不覆写。参考了版本保留的思路,但没有采用画布式交互。
- 对白情绪贯通到配音:
emotion从脚本提取一路带到 TTSemotion_description,并在编辑页可改。 - 生成前准备度门禁:分镜级 8 项与项目级开工预检,把“点了必失败”的情况提前到点之前暴露。
Added
- 提示词链路
backend/app/chains/prompts/short_drama_rules.py:红果向短剧创作纪律常量与纯函数(字幕安全区、微表情配额、口播节奏、动作拍点数量、抽象词拦截)。backend/app/chains/prompts/ir.py:IRPrompt/IRShot/IRReference/IRSubjectDefinition/IRDialogueLine与build_video_prompt_ir(...)。backend/app/chains/prompts/renderers/:uses_h3_prompt_format/get_video_renderer/render_video_prompt与 H3 六段式渲染器。backend/app/chains/prompts/style_pack.py:FORMAT_PACKS/STYLE_PACKS/style_pack_line(...)/negative_image_prompt(...)/is_anime(...)。backend/app/chains/agents/h3_video_prompt_agent.py:H3VideoPromptAgent与generate_h3_prose(...)。
- 数据库迁移
backend/sql/010-add-character-voice-and-audio-attachments.sql:角色音色与音频附件字段。backend/sql/012-rewrite-prompt-templates.sql:重写 14 个类别的模板(生成物,715 行)。backend/sql/013-add-dialog-line-emotion.sql:shot_dialog_lines.emotion与shot_extracted_dialogue_candidates.emotion。
- 视频版本
backend/app/services/studio/shot_video_versions.py:list_shot_video_versions/adopt_shot_video_version。GET /api/v1/studio/shots/{shot_id}/video-versions与POST .../video-versions/adopt。- 分镜视频区新增「重新抽卡」与「视频版本(抽卡历史)」列表。
- 准备度
- 分镜级新增
reference_images_ready检查。 - 新增
GET /api/v1/studio/projects/{project_id}/production-readiness项目级开工预检。
- 分镜级新增
- 测试
backend/tests/test_prompt_ir_and_h3_renderer.py、test_shot_dialogue_emotion.py、test_shot_video_versions.py、test_frame_reference_ordering.py。
Changed
- 参考图排序固定为角色优先:
_REFERENCE_KIND_PRIORITY保证角色卡永远是图1,同类内保持调用方顺序。 - 人物卡改为双重判定:角色既要有镜头关联,名字还要出现在该镜头的剧本语料里,纯空镜不再插入角色卡;未命中会追加可解释警告。
- 视频比例改为可继承:
ratio不再必填,按请求参数 → shot_details.override_video_ratio → projects.default_video_ratio解析。 - 角色图基础草稿改用
character_image_front:此前误用combined,而库里没有该模板行,导致回落到一句原始描述。 - 参考图缺图提示改为可执行:不再只说数量,而是说明原因并提示改用
text_only。 - 前端参考图模式自动回落:读
reference_images_ready结论,参考图不可用时自动切到text_only并给出提示。
Breaking Changes
- 空镜在参考图模式下的行为变了。过去准备度报“全部就绪”、提交后才收到
400 reference_mode=reference requires 1..9 reference images, got 0;现在准备度即判未就绪,生成端点返回 409。依赖旧行为(先就绪后失败)的自动化脚本需要调整。 ShotVideoReadinessRead.checks多出reference_images_ready一项。按 key 索引检查项的调用方无需改动;按固定下标访问的调用方需要更新。_resolve_audio_target返回值由 5 元组变为 6 元组。这是内部函数,但直接调用它的测试需要同步解包。
Deprecations
- 资产类提示词模板中
{{ view }}与{{ extra_details }}变量已废弃:它们从未被传值,渲染后恒为空字符串。请改用{{ view_angle }}/{{ tags }}。
Fixed
- 模板变量静默为空:
{{ view }}/{{ extra_details }}未在variables中声明,render_prompt_template_content会渲染成空串,导致“镜头方向:”后一直没内容。 - 角色卡提示词退化为原始描述:
build_character_image_base_draft使用不存在的combined模板类别,character_image_front成为死配置。 - 对白情绪被静默丢弃:LLM 契约已产出
emotion,但候选入库时未取,配音永远用默认语气。 - 视频生成覆写上一版:每次生成直接写
shots.generated_video_file_id,旧版本无任何找回入口。 - 参考图顺序不稳定:角色卡可能被排到场景之后,导致提示词中的图片编号与实际上传顺序错位。
ValueError落入 500:新增全局 handler,按消息后缀映射 404 / 400。
Security
- 本版本未引入新的外部网络入口;提示词模板与风格包均为本地数据与纯函数。
- 生成类端点复用既有的准备度校验,未就绪时不创建任务,避免无效的付费调用。
Known Issues
- 时间线 / 导出仍是占位:
backend/app/api/v1/routes/studio/timeline.py目前只有路由壳,没有 CRUD 端点。产品工作流第 ⑥ 步尚不可用。 video_prompt模板类别未播种:一旦库中存在该行,视频预览会走模板分支并绕过 IR → H3 渲染器,因此有意留空。若手工新增该行,会改变视频提示词的生成路径。- 首次参考图模式的 E2E 依赖真实对象存储:
file_id_to_data_url需要能从存储下载到内容,纯 DB 造数无法覆盖。
Migration Guide
按顺序应用迁移到运行中的 MySQL:
source scripts/dockerenv.sh
DB_PASS=$(grep -E '^MYSQL_ROOT_PASSWORD=' deploy/compose/.env | cut -d= -f2-)
docker exec -i compose-mysql-1 mysql -uroot -p"$DB_PASS" --default-character-set=utf8mb4 jellyfish \
< backend/sql/010-add-character-voice-and-audio-attachments.sql
cd backend && .venv/bin/python scripts/gen_prompt_templates_sql.py && cd ..
docker exec -i compose-mysql-1 mysql -uroot -p"$DB_PASS" --default-character-set=utf8mb4 jellyfish \
< backend/sql/012-rewrite-prompt-templates.sql
docker exec -i compose-mysql-1 mysql -uroot -p"$DB_PASS" --default-character-set=utf8mb4 jellyfish \
< backend/sql/013-add-dialog-line-emotion.sql三个迁移都是幂等的,重复执行不会重复建列或重复插行。校验:
SELECT COUNT(*) FROM prompt_templates; -- 期望 14
SHOW COLUMNS FROM shot_dialog_lines LIKE 'emotion'; -- 期望 varchar(64) / YES后端代码烘进镜像,改完必须重建:
docker compose -f deploy/compose/docker-compose.yml build backend celery-worker
docker compose -f deploy/compose/docker-compose.yml up -d backend celery-worker前端需要重新生成 OpenAPI 客户端:
cd front && pnpm run openapi:updateRollback Notes
- 012 可安全回滚:模板是数据行,恢复旧
content即可;表结构与业务代码无关。 - 013 回滚需要同时回退代码:先删除新代码里对
emotion的写入(否则查列会失败),再删列。 - 010 回滚会丢音色配置:删列前先导出
characters.voice_id/voice_source。 - 视频版本切换是纯指针写入:如需回到单一版本行为,把
shot_video_file_id固定即可,历史行不受影响。
Compatibility Matrix
| 组件 | 版本要求 |
|---|---|
| Python | 3.11+(运行时容器为 3.12) |
| MySQL | 8.x(迁移使用 information_schema + PREPARE/EXECUTE) |
| Node.js / pnpm | 与 front/package.json 一致 |
| 前端类型 | 需 pnpm run openapi:update 后与后端 spec 对齐 |
Validation Commands
# 后端全量测试
cd backend && .venv/bin/python -m pytest tests -q
# 前端类型检查
cd front && pnpm run typecheck
# 健康检查与 spec 路径数
curl -s http://127.0.0.1:8000/health
curl -s http://127.0.0.1:8000/openapi.json | python3 -c "import sys,json;print(len(json.load(sys.stdin)['paths']))"Upgrade Checklist
- 应用 010 / 012 / 013 三个迁移,并确认
prompt_templates为 14 行。 - 重建
backend与celery-worker镜像并重启。 - 执行
pnpm run openapi:update并确认VideoGenerationTaskRequest.reference_mode含reference。 - 跑通后端全量测试与前端
typecheck。 - 用一个空镜分镜验证:参考图模式应提示未就绪,而不是提交后才失败。
- 用一个有角色出场的分镜验证:参考图应解析出角色卡且为
图1。
References
Notes for Contributors
- 改提示词模板时不要直接改 SQL:改代码常量后重新运行
backend/scripts/gen_prompt_templates_sql.py。 - 新增模板变量时,必须同时更新
ASSET_VARS与调用侧的variables字典——不一致只会得到静默的空字符串。 - 区分
style(ProjectStyle,7 个题材)与visual_style(ProjectVisualStyle,现实/动漫),不要对调。 - 参考图模式与首尾帧模式互斥,改动
REQUIRED_FRAMES_BY_MODE时注意reference必须是空元组。
Acknowledgements
感谢在评审中提出「不要画布式」「空镜不该插角色卡」的反馈——前者避免了一次过度设计,后者直接暴露了一个必然失败的默认路径。