feat(#1970): 新 API 字段 + 叙事模式 PR3 - assembly_mode/script_id/tts_*/video_ratio #1976

Merged

auto-approve-bot merged 1 commits from feat/1970-assembly-narrative into develop 2026-09-18 07:30:43 +08:00

Conversation 2 Commits 1 Files Changed 9

+1521 -10

xiaoxia commented 2026-09-18 07:20:11 +08:00

Owner

Copy Link

Copy Source

#1970 智能剪辑流程重构 · PR3/3（末个 PR）

承接 #1974（PR1 原子切片）、#1975（PR2 智能降重），均已合入 develop。与前端 #1973（已上线）字段契约对齐。

新字段（CreateGenerationTaskRequest）

字段	默认	说明
assembly_mode	random	random=随机混剪（旧行为）/ narrative=叙事剪辑
script_id	空	narrative 必填，口播文案库 scripts.id
tts_voice_id	空	narrative 必填，preset=CosyVoice 音色 id，clone=克隆档案 id
tts_voice_source	preset	preset / clone
video_ratio	空	9:16/16:9/1:1/3:4/4:3；空串沿用模板/旧默认，前端固定传 9:16

dedup_enabled 已在 PR2 上线。模型校验：narrative 缺 script_id/tts_voice_id、非法枚举、非法比例直接 422。

叙事模式流程（入队前同步完成，失败返 4xx 不入队）

1. 读 scripts 表（归属校验），content 为空报错；
2. 按 tts_voice_source 解析音色（clone 校验档案归属 + voice_id 就绪；preset 直传，误传克隆 UUID 同样兼容）；
3. 复用 tts_job 现有 workflow 同步合成（提交即返回，未完成轮询兜底，180s 上限）；积分按 ai_voice 同口径扣点/失败退费；
4. 合成音频转存为配音库 audio asset（与 /tts/jobs/{id}/save-to-library 同一套存储路径/元信息），voice_library_id 指向该 asset，下游渲染链路零改动（worker 本就按 audio asset id 消费）；
5. 文案 tags 参与选片。

文案标签匹配（packages/domain/narrative_match.py，纯函数）

• 文案 tags 与素材标签（tag_ids 查 TagModel 名称，或素材自带 tags）归一化（strip/lower/去单字噪声）求交集；
• 命中池优先 + 复用 smart_select_assets 现有评分；数量不足从未命中池补齐；无任何命中/标签查询失败 → 完全降级旧随机逻辑，行为与改造前一致。

其他

• video_ratio → 输出分辨率映射（9:16=1080x1920 等），显式 output_width/height 非旧默认值时优先；空串保持旧 1280x720 行为。
• writeback plan.config 追加 assembly_mode/script_id/video_ratio（可追溯，不影响渲染）。
• EditingMode 中 one_take/pip/voice_pip 标记 deprecated（只加注释，不删代码），voice_over 保留。
• 全部外部依赖（TTS/OSS/DB）异常 try/except 降级或转 NarrativeError，不产生 500。

测试

• 新增 53 个：narrative_match 纯匹配/降级/分布 17 + narrative_service（音色解析/落库/积分扣退/失败码）18 + schema 校验/路由选片/标签索引/比例映射 18
• 全量 tests/unit：15736 passed, 28 skipped（502s）；black/isort/ruff 全过

向后兼容

不传任何新字段时 assembly_mode=random、video_ratio 空，全链路与当前线上行为一致；无 DB migration（复用 scripts/assets/tts_jobs 现有表）。

至此 #1970 三个 PR 全部提交。

## #1970 智能剪辑流程重构 · PR3/3（末个 PR） 承接 #1974（PR1 原子切片）、#1975（PR2 智能降重），均已合入 develop。与前端 #1973（已上线）字段契约对齐。 ### 新字段（CreateGenerationTaskRequest） | 字段 | 默认 | 说明 | |---|---|---| | assembly_mode | random | random=随机混剪（旧行为）/ narrative=叙事剪辑 | | script_id | 空 | narrative 必填，口播文案库 scripts.id | | tts_voice_id | 空 | narrative 必填，preset=CosyVoice 音色 id，clone=克隆档案 id | | tts_voice_source | preset | preset / clone | | video_ratio | 空 | 9:16/16:9/1:1/3:4/4:3；空串沿用模板/旧默认，前端固定传 9:16 | dedup_enabled 已在 PR2 上线。模型校验：narrative 缺 script_id/tts_voice_id、非法枚举、非法比例直接 422。 ### 叙事模式流程（入队前同步完成，失败返 4xx 不入队） 1. 读 scripts 表（归属校验），content 为空报错； 2. 按 tts_voice_source 解析音色（clone 校验档案归属 + voice_id 就绪；preset 直传，误传克隆 UUID 同样兼容）； 3. 复用 tts_job 现有 workflow 同步合成（提交即返回，未完成轮询兜底，180s 上限）；积分按 ai_voice 同口径扣点/失败退费； 4. 合成音频转存为配音库 audio asset（与 /tts/jobs/{id}/save-to-library 同一套存储路径/元信息），**voice_library_id 指向该 asset，下游渲染链路零改动**（worker 本就按 audio asset id 消费）； 5. 文案 tags 参与选片。 ### 文案标签匹配（packages/domain/narrative_match.py，纯函数） - 文案 tags 与素材标签（tag_ids 查 TagModel 名称，或素材自带 tags）归一化（strip/lower/去单字噪声）求交集； - 命中池优先 + 复用 smart_select_assets 现有评分；数量不足从未命中池补齐；**无任何命中/标签查询失败 → 完全降级旧随机逻辑，行为与改造前一致**。 ### 其他 - video_ratio → 输出分辨率映射（9:16=1080x1920 等），显式 output_width/height 非旧默认值时优先；空串保持旧 1280x720 行为。 - writeback plan.config 追加 assembly_mode/script_id/video_ratio（可追溯，不影响渲染）。 - EditingMode 中 one_take/pip/voice_pip 标记 **deprecated（只加注释，不删代码）**，voice_over 保留。 - 全部外部依赖（TTS/OSS/DB）异常 try/except 降级或转 NarrativeError，不产生 500。 ### 测试 - 新增 53 个：narrative_match 纯匹配/降级/分布 17 + narrative_service（音色解析/落库/积分扣退/失败码）18 + schema 校验/路由选片/标签索引/比例映射 18 - **全量 tests/unit：15736 passed, 28 skipped（502s）**；black/isort/ruff 全过 ### 向后兼容 不传任何新字段时 assembly_mode=random、video_ratio 空，全链路与当前线上行为一致；无 DB migration（复用 scripts/assets/tts_jobs 现有表）。 至此 #1970 三个 PR 全部提交。

xiaoxia added 1 commit 2026-09-18 07:20:12 +08:00

feat(#1970): 新 API 字段 + 叙事模式 PR3 - assembly_mode/script_id/tts_*/video_ratio ... 797a220d43

- CreateGenerationTaskRequest 新增 assembly_mode(random 默认/narrative)、
  script_id、tts_voice_id、tts_voice_source(preset/clone)、video_ratio；
  模型校验：narrative 必须带 script_id+tts_voice_id，比例枚举白名单
- 叙事模式入队前同步完成 TTS：读文案(归属校验) → 解析音色(preset/clone)
  → 复用 tts_job workflow 同步合成(失败 4xx 不入队,积分按 ai_voice 口径扣退)
  → 转存配音库 audio asset，voice_library_id 指向它，下游渲染零改动
- narrative_match 纯模块：文案 tags 与素材标签归一化求交集，命中池优先
  + smart_match 评分，不足/无匹配自动降级现有随机逻辑(行为与旧版一致)
- video_ratio→输出分辨率映射(9:16/16:9/1:1/3:4/4:3)，显式分辨率优先
- writeback 落 assembly_mode/script_id/video_ratio 便于追溯
- one_take/pip/voice_pip 标记 deprecated(不删代码)，voice_over 保留
- 新增 53 个测试；全量 tests/unit 15736 passed / 28 skipped

gitea-actions bot commented 2026-09-18 07:21:27 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1976
预览链接	https://pr-1976.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1976 | | 预览链接 | [https://pr-1976.preview.xiaoxiajianji.com](https://pr-1976.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

auto-approve-bot merged commit 4fa3e4eb92 into develop 2026-09-18 07:30:43 +08:00

auto-approve-bot deleted branch feat/1970-assembly-narrative 2026-09-18 07:30:47 +08:00

gitea-actions bot commented 2026-09-18 07:31:19 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1976 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1976 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot frontend-dev xiaoxia

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1976