Skip to content
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 从脚本提取一路带到 TTS emotion_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:update

Rollback Notes

  • 012 可安全回滚:模板是数据行,恢复旧 content 即可;表结构与业务代码无关。
  • 013 回滚需要同时回退代码:先删除新代码里对 emotion 的写入(否则查列会失败),再删列。
  • 010 回滚会丢音色配置:删列前先导出 characters.voice_id / voice_source。
  • 视频版本切换是纯指针写入:如需回到单一版本行为,把 shot_video_file_id 固定即可,历史行不受影响。

Compatibility Matrix

组件版本要求
Python3.11+(运行时容器为 3.12)
MySQL8.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

感谢在评审中提出「不要画布式」「空镜不该插角色卡」的反馈——前者避免了一次过度设计,后者直接暴露了一个必然失败的默认路径。