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

v0.3.1 发布说明

2026年4月15日·Jellyfish Team

v0.3.1 延续 v0.3.0 的能力化方向，重点推进“生成参数动态下发、项目风格可配置化、视频比例默认/覆盖语义”三条主线。
本版本同时完成了后端契约重构、OpenAPI 同步与前端生成调用链路对齐。

Highlights

  • 新增图片与视频生成选项接口，前端可基于默认模型动态获取可用比例、分辨率档位和默认值。
  • 新增项目风格候选接口，统一 visual_style -> style 的映射与默认值规则，减少前端硬编码。
  • 视频生成输入契约扩展 ratio、seed、watermark，并强化边界校验与适配器透传。
  • 引入项目级默认视频比例与分镜级覆盖比例字段，建立“项目默认 + 分镜覆盖”的参数继承机制。
  • 前端工作台与项目大厅完成 OpenAPI generated client 对齐，风格与生成参数选择体验同步升级。

Added

  • 生成选项 API
    • 新增图片生成选项接口：返回默认图片模型支持比例、默认分辨率档位与尺寸映射。
    • 新增视频生成选项接口：返回默认视频模型允许比例与默认比例。
  • 项目风格候选 API
    • 新增项目风格候选接口：提供 visual_styles、styles_by_visual_style、default_style_by_visual_style。
    • 新增项目创建/更新时的风格组合校验，非法组合会被拒绝。
  • 视频比例层级字段
    • projects 新增 default_video_ratio，用于项目级默认视频比例。
    • shot_details 新增 override_video_ratio，用于分镜级覆盖项目默认值。
  • 能力适配与测试覆盖
    • 补齐 OpenAI/火山引擎图像与视频能力查询实现。
    • 新增图片/视频能力与适配器相关测试用例，覆盖关键参数透传与返回语义。

Changed

  • 生成能力通用契约统一收敛到 app/core/contracts，任务层与集成层依赖边界更清晰。
  • 视频输入契约更新为“业务主参数优先”：ratio 成为核心字段，并新增 seed/watermark 约束。
  • llm、studio/projects 路由与 schema 扩展，支持新选项接口与风格约束。
  • 前端项目大厅与工作台改造为消费后端动态选项，减少静态枚举分叉。
  • OpenAPI 与前端 generated client 已按本版本接口同步更新。

Breaking Changes

  • 视频生成请求契约发生变化：调用方需按新字段语义传递 ratio，并兼容 seed 的取值边界（-1 或 [0, 2^32-1]）。
  • 项目风格不再建议自由组合：visual_style 与 style 必须满足后端映射约束，旧前端硬编码组合可能被 400 拒绝。
  • 若未执行本版本数据库迁移，项目与分镜的视频比例继承链路将无法按预期工作。
  • 若未同步最新 OpenAPI 与 generated client，前端类型将与后端响应产生偏差。

Deprecations

  • 前端本地硬编码图片/视频生成参数候选的做法进入弃用路径，应改为调用生成选项 API。
  • 前端自由拼装项目风格组合（不校验视觉风格归属）的做法进入弃用路径。
  • 在任务或集成模块中重复定义跨层 DTO 的做法进入弃用路径，应统一复用 app/core/contracts。

Fixed

  • 修复部分图像/视频适配链路参数透传不一致问题（含比例、时长、种子、水印）。
  • 修复项目大厅样式与交互细节问题，提升标签与描述区域在不同布局下的一致性。
  • 修复视频输入边界校验覆盖不足问题，补齐关键边界测试断言。

Security

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

Known Issues

  • 旧版本前端若仍依赖静态候选项，可能在新增模型或能力变更时出现选项不一致。
  • 部分历史数据若未设置项目默认比例，可能在首次进入新链路时表现为“使用模型默认值”而非业务预期值。

Migration Guide

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

  1. 执行 backend/sql/006-migrate-model-defaults-to-model-settings-and-drop-is-default.sql 与 backend/sql/007-add-video-size-ratio-defaults-and-overrides.sql。
  2. 部署后端服务与任务执行组件（保持同版本）。
  3. 执行 pnpm run openapi:update，并部署前端 generated client 产物。
  4. 验证项目风格候选接口、图片/视频生成选项接口以及视频比例继承链路。

Rollback Notes

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

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

Compatibility Matrix

组件v0.3.1 要求说明
Backendv0.3.1需要生成选项 API、风格候选 API 与新契约字段
Frontend基于 v0.3.1 OpenAPI 重新生成必须同步 generated client 与页面调用链路
Database已执行 006、007 迁移保障模型默认策略与视频比例继承语义
Task Worker与后端同版本部署保障图像/视频任务参数透传与状态一致性

Validation Commands 

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

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

# 后端关键集成测试
uv run pytest backend/tests/core/integrations -q

Upgrade Checklist

  • 数据库迁移执行完成并验证通过（006、007）。
  • 后端服务与任务执行组件已升级到 v0.3.1。
  • 前端 generated client 已与最新 OpenAPI 对齐。
  • 项目风格候选接口与风格组合校验链路验证通过。
  • 图片/视频生成选项接口与视频比例继承链路验证通过。

References

  • Tag 基线：v0.3.0
  • 变更范围：v0.3.0..HEAD
  • 关键目录：backend/app/core/contracts、backend/app/core/integrations、backend/app/api/v1/routes/llm.py、backend/app/api/v1/routes/studio/projects.py、backend/sql、front/src/pages/aiStudio、front/src/services/generated

Notes for Contributors

  • 后端新增或调整生成参数后，必须同步能力查询实现、OpenAPI、generated client 与集成测试。
  • 涉及 visual_style / style 语义变更时，需同步更新候选映射逻辑、接口契约与前端表单约束。
  • 生成契约应优先沉淀在 app/core/contracts，避免跨层重复定义导致漂移。

Acknowledgements

感谢所有参与生成能力参数化、项目风格候选统一与视频比例继承机制建设的贡献者。

v0.3.0 发布说明v0.3.2 发布说明