Skip to content
博客
v0.3.2 发布说明

v0.3.2 发布说明

2026年4月17日·Jellyfish Team

v0.3.2 在 v0.3.1 的生成参数化基础上，进一步推进“镜头语义默认化 + 动作拍点结构化 + 生成工作台联动化”。
本版本同时完善了发布流程：tag-release 工作流支持自动生成并回填发布摘要，优先采用 tag 注释内容。

Highlights

  • 新增镜头语义建议（ShotSemanticSuggestion）与动作拍点（action_beats）能力，提升分镜生成连贯性与可控性。
  • 新增镜头帧提示词任务服务，统一“提取结果 -> 语义默认 -> 预览提示词”链路，减少手工拼装差异。
  • 分镜工作台与编辑页升级，支持语义建议与动作拍点的展示、编辑与提交联动。
  • 视频与关键帧提示词预览逻辑增强，补齐帧级决策信息与渲染提示词结构输出。
  • CI 发布流程增强：tag-release 支持发布摘要字段，且优先读取标签注释作为发布说明摘要。

Added

  • 镜头语义与动作拍点能力
    • 新增 backend/app/services/studio/shot_semantic_defaults.py，为镜头补齐语义建议默认值。
    • 新增 backend/app/services/studio/action_beats.py，实现动作拍点阶段化生成与组织。
    • 新增数据库迁移 backend/sql/008-add-shot-action-beats.sql，为分镜动作拍点落库提供结构支持。
  • 提示词任务与契约扩展
    • 新增 backend/app/services/film/shot_frame_prompt_tasks.py，统一帧提示词任务编排与状态输出。
    • 新增/扩展 OpenAPI 模型：ShotSemanticSuggestion、ActionBeatPhaseRead、RenderedShotFramePromptRead、ShotVideoPromptPackRead、ShotPreparationStateRead 等。
  • 前端工作台联动能力
    • front/src/pages/aiStudio/chapter/ChapterStudio.tsx、ChapterShotEditPage.tsx 与 ChapterShotBasicInfoSection.tsx 新增语义建议与动作拍点相关交互。
    • 前端 generated client 同步新增对应类型与导出入口。
  • 测试覆盖补强
    • 新增/增强语义默认、帧提示词任务、图片任务与 API 响应相关测试，覆盖关键业务分支与响应结构。

Changed

  • 分镜提取与生成准备状态链路升级：shot_preparation_state、shot_video_prompt_pack、derive_preview 等服务改为消费语义建议与动作拍点结果。
  • 图片任务与视频生成相关 API/Service 响应结构调整，以承载帧级指导决策与提示词渲染信息。
  • script_processing 与相关 schema 更新，支持提取缓存和分镜草稿向新语义字段持续透传。
  • OpenAPI 与前端 generated client 已按本版本接口同步更新。
  • .github/workflows/tag-release.yml 更新发布摘要策略，支持“输入摘要 + tag 注释摘要 + 自动生成摘要”三层兜底。

Breaking Changes

  • 分镜详情读写契约新增语义建议与动作拍点相关字段；未同步 OpenAPI/generated client 的调用方会出现类型不匹配。
  • 若未执行 backend/sql/008-add-shot-action-beats.sql，动作拍点能力无法正常持久化，相关接口可能返回不完整数据。
  • 帧提示词预览响应结构扩展为包含更完整渲染与决策信息，依赖旧字段结构的前端解析逻辑需要调整。

Deprecations

  • 依赖前端本地硬编码镜头语义默认值的做法进入弃用路径，应统一以后端语义建议输出为准。
  • 依赖临时字段拼接动作节奏信息的做法进入弃用路径，应迁移到 action_beats 结构化字段。

Fixed

  • 修复部分分镜提示词生成链路中语义缺失导致的生成上下文不稳定问题。
  • 修复图片任务与生成视频响应在边界场景下字段回填不一致问题。
  • 修复发布流程中 tag 发布摘要缺失时说明不完整的问题，增强摘要兜底逻辑。

Security

本版本未包含已公开披露的安全漏洞修复项。
如发现潜在安全问题，请通过维护渠道私下反馈，避免公开披露可利用细节。

Known Issues

  • 历史分镜数据若未补齐语义字段，首次进入新链路时可能出现“默认建议回填”行为，与旧版本展示不完全一致。
  • 旧前端若未升级 generated client，可能无法完整消费新的帧提示词与动作拍点响应字段。

Migration Guide

建议按以下顺序完成升级：

  1. 执行数据库迁移：backend/sql/008-add-shot-action-beats.sql。
  2. 部署后端服务与任务执行组件（保持同版本）。
  3. 执行 pnpm run openapi:update，并部署前端 generated client 产物。
  4. 验证分镜编辑页与工作台中的语义建议、动作拍点、提示词预览链路。
  5. 若使用 tag 发布流程，建议在 tag 注释中填写发布摘要以获得更准确的 release 内容。

Rollback Notes

如需紧急回滚，请保持“数据库迁移状态 + 后端接口 + 前端 generated client”一致：

  1. 先回滚前端到与目标后端匹配的 OpenAPI 版本。
  2. 再回滚后端服务与任务执行组件。
  3. 若数据库已执行 008 迁移，优先采用兼容读写策略，不直接回退表结构。

Compatibility Matrix

组件v0.3.2 要求说明
Backendv0.3.2需要镜头语义建议、动作拍点与帧提示词任务链路
Frontend基于 v0.3.2 OpenAPI 重新生成必须同步 generated client 与工作台页面联动逻辑
Database已执行 008 迁移保障 action_beats 字段与分镜能力完整可用
Task Worker与后端同版本部署保障提示词任务与生成状态流转一致性
CI Workflow使用更新后的 tag-release支持发布摘要优先读取 tag 注释

Validation Commands 

# 同步 OpenAPI 与前端 generated client
pnpm run openapi:update

# 前端类型检查
pnpm exec tsc --noEmit

# 后端关键测试（本次改动相关）
uv run pytest backend/tests/test_shot_semantic_defaults_service.py -q
uv run pytest backend/tests/test_shot_frame_prompt_tasks_service.py -q
uv run pytest backend/tests/test_image_task_services.py -q

Upgrade Checklist

  • 数据库迁移执行完成并验证通过（008）。
  • 后端服务与任务执行组件已升级到 v0.3.2。
  • 前端 generated client 已与最新 OpenAPI 对齐。
  • 分镜编辑页/工作台语义建议与动作拍点链路验证通过。
  • 提示词预览与视频生成相关接口响应字段验证通过。
  • tag-release 发布摘要策略验证通过（含 tag 注释优先级）。

References

  • Tag 基线：v0.3.1
  • 变更范围：v0.3.1..HEAD
  • 关键提交：5f863b6（镜头语义建议与动作拍点能力）、c0b88cc（tag-release 发布摘要支持）
  • 关键目录：backend/app/services/studio、backend/app/services/film/shot_frame_prompt_tasks.py、backend/sql、front/src/pages/aiStudio、front/src/services/generated、.github/workflows/tag-release.yml

Notes for Contributors

  • 任何分镜语义、动作拍点、提示词响应结构变更后，必须同步 OpenAPI 与前端 generated client。
  • 涉及状态语义或页面职责边界的调整，需同步更新 site/content/docs/architecture 对应文档。
  • 发布流程若依赖自动摘要，建议在打 tag 时补充注释，避免摘要信息缺失。

Acknowledgements

感谢所有参与镜头语义建议、动作拍点能力、提示词任务链路升级以及发布流程完善的贡献者。

v0.3.1 发布说明