fix: 更新 test_1280 ASR跳过测试以匹配 PR #1294 的 voice_id 条件变更

从 main 分支 PR #1308 手动适配到 develop 分支，保留 develop 现有功能：

Schema 层：
- 新增 ConfirmGenerationRequest schema
- CreateGenerationTaskRequest 增加 6 个新字段（is_preview, source_task_id, output_width, output_height, cover_url, custom_title）
- GenerationTaskResponse 增加对应字段

Domain 层：
- GenerationTask 实体增加 source_task_id, output_width, output_height, cover_url, custom_title 字段
- create() 工厂方法增加对应参数

Application 层：
- CreateGenerationTaskCommand 增加对应字段
- UseCase 执行时传递新字段

DB 层：
- GenerationTaskModel 增加 5 个新列（is_preview 已存在于 develop）
- 仓储 _to_domain/create/update 映射更新

API 路由：
- 新增 POST /tasks/{task_id}/confirm 端点
- 使用 safe_enqueue_generation_task 适配 develop 任务入队机制
- 更新 _to_generation_task_response 和 retry 端点

Worker 层：
- _load_task_info 返回新字段
- generate_video 支持动态分辨率（output_width/output_height 覆盖默认分辨率）

Alembic 迁移 054：
- generation_tasks 表增加 source_task_id, output_width, output_height, cover_url, custom_title 列

单元测试：
- tests/unit/test_confirm_generation.py（7 个测试用例全部通过）
- 适配 develop 的 safe_enqueue_generation_task 入队机制

.gitea/workflows/ci-pipeline.yml

@@ -21,9 +21,8 @@ on:
 permissions:
   contents: read
 concurrency:
-  group: ci-pipeline-${{ gitea.event_name }}-${{ gitea.ref }}
-  # PR事件取消进行中的旧run，push事件不取消（确保完整CI跑完）
-  cancel-in-progress: ${{ gitea.event_name == 'pull_request' }}
+  group: ci-pipeline-${{ gitea.ref }}
+  cancel-in-progress: true
 jobs:
   check-frontend-only:
     name: Check if frontend-only change
@@ -1087,26 +1086,7 @@ jobs:
     - name: Run Playwright E2E on staging
       shell: bash
       run: |
-        set -eu
-        # DooD模式下不能用-v挂载（宿主机路径与CI容器路径不一致）
-        # 改用 docker create + docker cp 方式把代码拷进容器
-        CONTAINER_NAME="staging-e2e-$$"
-        # 强制清理可能残留的同名容器（上一次异常退出时未清理）
-        docker rm -f "$CONTAINER_NAME" 2>/dev/null || true
-        docker create --name "$CONTAINER_NAME" --ipc=host \
-          -e E2E_BASE_URL=https://staging.xiaoxiajianji.com \
-          -e E2E_API_BASE=https://staging-api.xiaoxiajianji.com/api/v1 \
-          -e E2E_BROWSER_CHANNEL=chromium \
-          -e PLAYWRIGHT_HEADLESS=1 \
-          -w /workspace/apps/web \
-          git.xiaoxiajianji.com/xiaoxia/base/playwright:v1.45.0-jammy \
-          sh -lc "npm ci && npx playwright test --reporter=line --project=chromium e2e/auth.spec.ts e2e/auth-guard.spec.ts e2e/core-upload.spec.ts e2e/core-generation.spec.ts"
-        docker cp apps "$CONTAINER_NAME:/workspace/"
-        docker cp package-lock.json "$CONTAINER_NAME:/workspace/" 2>/dev/null || true
-        docker start -a "$CONTAINER_NAME"
-        EXIT_CODE=$(docker wait "$CONTAINER_NAME")
-        docker rm "$CONTAINER_NAME" 2>/dev/null || true
-        exit $EXIT_CODE
+        bash scripts/ci/run_staging_tests.sh e2e
 
     - name: Job duration summary
       if: always()
@@ -1153,22 +1133,7 @@ jobs:
     - name: Run API integration tests on staging
       shell: bash
       run: |
-        set -eu
-        # DooD模式下不能用-v挂载（宿主机路径与CI容器路径不一致）
-        # 改用 docker create + docker cp 方式把代码拷进容器
-        CONTAINER_NAME="staging-api-tests-$$"
-        docker create --name "$CONTAINER_NAME" \
-          -e E2E_BASE_URL=https://staging.xiaoxiajianji.com \
-          -e E2E_API_BASE=https://staging-api.xiaoxiajianji.com/api/v1 \
-          -w /workspace/apps/web \
-          git.xiaoxiajianji.com/xiaoxia/base/playwright:v1.45.0-jammy \
-          sh -lc 'npm ci && npx playwright test --reporter=line e2e/test_auth.spec.ts e2e/test_asset.spec.ts e2e/test_project.spec.ts'
-        docker cp apps "$CONTAINER_NAME:/workspace/"
-        docker cp package-lock.json "$CONTAINER_NAME:/workspace/" 2>/dev/null || true
-        docker start -a "$CONTAINER_NAME"
-        EXIT_CODE=$(docker wait "$CONTAINER_NAME")
-        docker rm "$CONTAINER_NAME" 2>/dev/null || true
-        exit $EXIT_CODE
+        bash scripts/ci/run_staging_tests.sh api
 
     - name: Job duration summary
       if: always()
@@ -1495,9 +1460,8 @@ jobs:
       shell: sh
       run: bash scripts/ci/step_timer_start.sh
     - name: Run production browser E2E
-      shell: sh
+      shell: bash
       run: |
-        set -eu
         docker run --rm --ipc=host \
           -e E2E_BASE_URL=https://saas.xiaoxiajianji.com \
           -e E2E_API_BASE=https://api.xiaoxiajianji.com/api/v1 \
@@ -1506,7 +1470,7 @@ jobs:
           -v "$PWD:/workspace" \
           -w /workspace/apps/web \
           git.xiaoxiajianji.com/xiaoxia/base/playwright:v1.45.0-jammy \
-          sh -lc 'npm ci && npx playwright test --reporter=line --project=chromium e2e/auth.spec.ts e2e/auth-guard.spec.ts e2e/core-upload.spec.ts e2e/core-generation.spec.ts e2e/core-titles.spec.ts'
+          bash -c 'for i in 1 2 3; do npm ci --registry=https://registry.npmmirror.com && break; echo "npm ci attempt $i failed, retrying..."; sleep 15; done && npx playwright test --reporter=line --project=chromium e2e/auth.spec.ts e2e/auth-guard.spec.ts e2e/core-upload.spec.ts e2e/core-generation.spec.ts e2e/core-titles.spec.ts'
 
     - name: Job duration summary
       if: always()
@@ -1862,4 +1826,4 @@ jobs:
           [ "${{ steps.gate.outputs.gate_result }}" = "success" ] || STATUS="error"
           START_TIME=""
           [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
-          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true

.gitea/workflows/preview-deploy.yml

@@ -95,12 +95,9 @@ jobs:
         set -eu
         cd apps/web
 
-        # Config npm mirror for speed
-        npm config set registry https://registry.npmmirror.com
-
         # Install dependencies with retry
         for i in 1 2 3; do
-          npm ci --no-audit --no-fund && break
+          npm ci --registry=https://registry.npmmirror.com --no-audit --no-fund && break
           echo "npm install failed, retry $i/3..."
           [ $i -eq 3 ] && exit 1
           rm -rf node_modules
@@ -109,12 +106,12 @@ jobs:
 
         # TypeScript check
         echo "=== TypeScript check ==="
-        npx --no-install tsc --noEmit
+        ./node_modules/.bin/tsc --noEmit
 
         # Vite build
         echo "=== Vite build ==="
         export VITE_API_URL=https://staging-api.xiaoxiajianji.com
-        npx --no-install vite build
+        ./node_modules/.bin/vite build
 
         echo "=== Build completed ==="
         ls -la dist/

1197_preview_generation_proposal.md

@@ -0,0 +1,222 @@
+---
+AIGC:
+    Label: "1"
+    ContentProducer: 001191110102MACQD9K64018705
+    ProduceID: 15868733686388_0/project_7655981463858544923-files/docs/1197_preview_generation_proposal.md
+    ReservedCode1: ""
+    ContentPropagator: 001191110102MACQD9K64028705
+    PropagateID: 15868733686388#1785468313901
+    ReservedCode2: ""
+---
+# #1197 预览生成接口方案评估
+
+## 背景
+
+智能剪辑「一键生成」流程中，第3步预览生成当前被跳过，直接进入下一步。需要实现真正的预览生成功能，让用户在正式生成前能看到效果预览。
+
+## 现状分析
+
+### 现有生成链路
+
+```
+API 触发生成 → GenerationTask入库 → Celery异步任务 → UnifiedRenderService渲染 → OSS上传 → 更新状态
+```
+
+**关键节点：**
+1. **API层**：`POST /generation-tasks` 或 `POST /templates/{id}/generate` 触发生成
+2. **任务调度**：Celery task `worker.generate_video`
+3. **渲染引擎**：`UnifiedRenderService`（统一渲染引擎，已接入9个效果层）
+4. **输出配置**：默认 720p (1280x720)，支持 `resolution` 字段自定义
+5. **产物存储**：`GeneratedVideo` 表记录，OSS 存储视频文件
+
+### 已有可复用能力
+
+| 能力 | 位置 | 是否可复用 |
+|------|------|-----------|
+| 任务创建与状态管理 | `GenerationTask` + `CreateGenerationTaskUseCase` | ✅ 是 |
+| 素材下载与预处理 | `_download_video_assets` / `_download_voice_asset` | ✅ 是 |
+| 统一渲染引擎 | `UnifiedRenderService` | ✅ 是 |
+| 分辨率配置 | `resolution` 字段已支持 | ✅ 是 |
+| 混音与后处理 | `_render_video` 内流程 | ✅ 是 |
+| OSS 上传与查重 | `_upload_and_dedup` | ✅ 是 |
+| 进度追踪 | `append_log` / `progress` 字段 | ✅ 是 |
+
+## 方案对比
+
+### 方案A：复用现有生成链路 + is_preview 标记（推荐）
+
+**思路**：在现有 GenerationTask 上加 `is_preview` 标记，预览生成走完整链路但参数降级。
+
+**改动点：**
+1. **数据模型**：`GenerationTask` 加 `is_preview: bool` 字段（默认 false）；`GeneratedVideo` 加 `is_preview: bool`
+2. **API 层**：生成接口加 `is_preview` 参数，预览任务不计入配额
+3. **渲染参数**：预览模式下自动调整
+   - 分辨率：480p (854x480)
+   - 时长：限制前 15 秒（或模板第一个片段）
+   - 码率：降低至 1.5Mbps（正式 4Mbps）
+   - 效果层：跳过高级转场/粒子特效等耗时效果
+4. **任务调度**：预览任务走低优先级队列（或复用现有队列，标记优先级）
+5. **前端对接**：预览生成结果带 `is_preview=true` 标记，前端展示"预览"标签
+
+**优点：**
+- 代码复用率 90%+，改动最小
+- 与正式生成逻辑一致，预览效果真实可信
+- 进度查询、结果展示等功能直接复用
+- 后续可平滑升级：预览满意后一键转正式生成
+
+**缺点：**
+- 需要区分预览和正式任务，避免数据混淆
+- 预览任务和正式任务竞争同一队列资源（可后续优化为独立队列）
+
+**开发量估算**：2-3 天
+- 数据模型 + 迁移：0.5 天
+- API 层改造：0.5 天
+- 渲染参数降级：1 天
+- 测试 + 联调：1 天
+
+---
+
+### 方案B：新建独立预览接口 + 轻量渲染逻辑
+
+**思路**：新建独立的预览生成接口，使用简化的渲染逻辑（如只拼接素材+基础配音，跳过大部分效果）。
+
+**改动点：**
+1. 新增 `PreviewTask` 数据模型
+2. 新增 `POST /api/v1/preview/generate` 接口
+3. 新增独立的 Celery task `worker.generate_preview`
+4. 简化渲染流程：只做素材裁剪+拼接+配音，跳过转场/滤镜/字幕特效等
+
+**优点：**
+- 完全隔离，不影响正式生成链路
+- 可以做极致优化，预览生成速度快
+- 数据模型清晰，不会混淆
+
+**缺点：**
+- 代码重复率高，两套生成逻辑维护成本翻倍
+- 预览效果与正式生成可能不一致（效果层差异）
+- 前端需要对接两套接口
+- 无法从预览升级为正式生成（需重新走完整流程）
+
+**开发量估算**：4-5 天
+- 数据模型 + 接口：1 天
+- 简化渲染逻辑：2 天
+- 测试 + 联调：1-2 天
+
+---
+
+### 方案C：图片预览（首帧/关键帧截图）
+
+**思路**：不生成视频，只生成几张关键帧的预览图片。
+
+**优点：**
+- 生成速度极快（秒级）
+- 资源消耗小
+
+**缺点：**
+- 预览效果差，用户无法感知动态效果
+- 无法验证配音、转场、节奏等时间维度的效果
+- 用户体验不佳，不如"真预览"有说服力
+
+**开发量估算**：1-2 天
+
+---
+
+## 推荐方案：方案A（复用现有生成链路）
+
+### 核心理由
+
+1. **效果保真**：预览和正式生成用同一套渲染引擎，效果一致，用户信任度高
+2. **开发效率**：90% 代码复用，2-3 天可上线
+3. **可扩展性强**：后续可加「预览转正式」「低分辨率快速预览」等增强功能
+4. **维护成本低**：一套生成逻辑，bug 修复和新功能同时生效
+
+### 详细设计
+
+#### 1. 数据模型变更
+
+```python
+# GenerationTask 新增字段
+is_preview: bool = False
+"""是否为预览生成"""
+
+preview_of: str = ""
+"""预览对应的正式任务 ID（或反向关联）"""
+
+# GeneratedVideo 新增字段
+is_preview: bool = False
+"""是否为预览视频"""
+```
+
+**迁移**：alembic 新增 migration，两个表各加 1-2 个字段。
+
+#### 2. API 层
+
+```
+POST /api/v1/generation-tasks
+  Body 增加 is_preview: bool = false
+  
+POST /api/v1/templates/{id}/generate
+  Query 增加 is_preview: bool = false
+```
+
+**配额处理**：预览生成不计入用户配额，不占用生成次数限制。
+
+#### 3. 渲染参数降级
+
+| 参数 | 正式生成 | 预览生成 |
+|------|---------|---------|
+| 分辨率 | 720p (1280x720) | 480p (854x480) |
+| 码率 | 4 Mbps | 1.5 Mbps |
+| 时长 | 完整时长 | 前 15 秒（或第一段） |
+| 帧率 | 30 fps | 24 fps |
+| 转场效果 | 完整转场 | 仅淡入淡出（或简单切） |
+| 特效滤镜 | 全部启用 | 跳过粒子/光效等高级效果 |
+| 字幕 | 完整渲染 | 正常渲染（字幕是核心信息） |
+| 配音 | 完整混音 | 正常混音（配音是核心信息） |
+
+**实现方式**：在 `_render_video` 或 UnifiedRenderService 入口处，根据 `is_preview` 标记调整渲染配置。
+
+#### 4. 任务调度
+
+- 初期复用现有队列，预览任务正常排队
+- 后续如需优化，可拆分独立预览队列（低优先级）
+- 预览任务可设置较短超时时间
+
+#### 5. 前端对接
+
+- 调用生成接口时传 `is_preview=true`
+- 结果列表中预览视频带「预览」标签
+- 预览满意后可一键「升级为正式生成」（重新触发全分辨率生成，可复用素材下载缓存）
+
+### 实施步骤
+
+**Phase 1（MVP，2天）：**
+1. 数据模型 + 迁移
+2. API 层支持 is_preview 参数
+3. 渲染分辨率降级（480p）
+4. 不计入配额
+5. 基础测试
+
+**Phase 2（优化，1-2天）：**
+1. 时长限制（前15秒）
+2. 效果层降级（跳高级效果）
+3. 预览任务低优先级队列
+4. 预览转正式生成功能
+
+## 与前端对齐点
+
+1. 预览生成的触发时机（第3步自动生成？用户点击才生成？）
+2. 预览时长是固定15秒还是完整但低清？
+3. 是否需要「预览转正式生成」功能
+4. 预览视频的展示形态（和正式视频一样还是有特殊UI）
+
+## 风险与注意事项
+
+1. **数据混淆**：确保统计、计费、列表展示时正确区分预览和正式任务
+2. **存储成本**：预览视频也占 OSS 空间，可设置自动清理（7天后自动删除）
+3. **用户预期**：要明确告诉用户这是预览，效果和正式生成一致但清晰度低
+4. **并发压力**：如果用户频繁生成预览，可能增加系统负载，需要限流
+
+---
+
+> 本内容由 Coze AI 生成，请遵循相关法律法规及《人工智能生成合成内容标识办法》使用与传播。

1197_preview_generation_proposal_v2.md

@@ -0,0 +1,382 @@
+# #1197 预览生成接口技术方案（v2）
+
+> 更新说明：v2 新增「多版本预览生成」能力，支持一个模板生成多个不重复的预览视频，左侧列表展示，用户可挑选满意的版本转正式生成。
+
+## 1. 背景与目标
+
+**现状**：智能剪辑「一键生成」第3步预览生成被跳过，用户直接进入正式生成，缺少效果预览环节。
+
+**目标**：
+1. ✅ 实现真正的预览生成（低分辨率快速出片）
+2. ✅ **支持生成 1~N 个不重复的预览版本**（默认 3 个），左侧列表展示
+3. ✅ 预览满意后可一键转正式生成（复用素材下载缓存）
+4. ✅ 不计入用户配额，不占用正式生成次数
+
+---
+
+## 2. 现有生成链路分析
+
+### 2.1 链路总览
+
+```
+API 触发生成 → GenerationTask入库 → Celery异步任务
+  → 下载素材 → 构建plan/clips → UnifiedRenderService渲染
+  → 混音后处理 → OSS上传 + 查重 → 更新状态
+```
+
+### 2.2 决定视频差异的变量
+
+要做"多个不重复版本"，先分析哪些环节可以引入变化：
+
+| 变量 | 当前行为 | 能否引入变化 | 影响程度 |
+|------|---------|------------|---------|
+| 素材选择 | 按 asset_ids 顺序全用 | ✅ 可随机选择子集/不同组合 | 大 |
+| 素材排序 | 按 asset_ids 顺序 | ✅ 可 shuffle 重排 | 大 |
+| 配音选择 | 固定 voice_library_id | ✅ 可选不同音色 | 中 |
+| 标题选择 | 固定 title_ids 或随机选 | ✅ 可选不同标题 | 中 |
+| BGM | 固定 bgm_config | ✅ 可选不同BGM | 小 |
+| 转场效果 | 模板固定 | ✅ 可随机化转场类型 | 小 |
+| 播放速度 | 模板固定 | ✅ 可微调速度 | 小 |
+| 分辨率/码率 | 固定 | ✅ 预览可降级 | 不影响内容 |
+
+### 2.3 可复用能力
+
+- 任务创建与状态管理：`GenerationTask` + `CreateGenerationTaskUseCase`
+- 素材下载与预处理：`_download_all_assets`
+- 统一渲染引擎：`UnifiedRenderService`
+- 分辨率配置：`resolution` 字段已支持
+- 批量任务：`batch_id` 字段已存在（可用于预览组）
+
+---
+
+## 3. 总体方案：复用现有链路 + 多变体引擎
+
+**核心思路**：沿用 v1 的"复用现有生成链路 + is_preview 标记"方案，在此基础上增加「多版本生成」能力。
+
+**架构**：
+```
+预览生成请求（count=N）
+    ↓
+创建预览批次（preview_batch）
+    ↓
+变体引擎生成 N 个变体参数（variation seed + 参数组合）
+    ↓
+为每个变体创建 1 个 GenerationTask（is_preview=true）
+    ↓
+N 个 Celery 任务并行执行（走现有生成链路，参数降级）
+    ↓
+N 个结果汇聚，前端左侧列表展示
+```
+
+---
+
+## 4. 详细设计
+
+### 4.1 数据模型变更
+
+#### 4.1.1 GenerationTask 新增字段
+
+```python
+# 现有字段保留，新增：
+is_preview: bool = False
+"""是否为预览生成"""
+
+preview_batch_id: str = ""
+"""预览批次 ID（同批次的 N 个预览共享一个 batch）"""
+
+variant_seed: int = 0
+"""变体种子，用于控制随机化行为（素材选择、排序、转场等）"""
+
+variant_params: dict = field(default_factory=dict)
+"""变体参数快照（记录本次使用了哪些素材、标题、配音等，可追溯）
+   {
+     "asset_ids": [...],      # 实际选用的素材子集
+     "title_id": "",         # 选用的标题
+     "voice_id": "",         # 选用的配音
+     "transition_style": "", # 转场风格
+     "bgm_track": "",        # BGM 音轨
+   }
+"""
+```
+
+#### 4.1.2 GeneratedVideo 新增字段
+
+```python
+is_preview: bool = False
+"""是否为预览视频"""
+
+preview_batch_id: str = ""
+"""所属预览批次"""
+
+variant_index: int = 0
+"""在批次中的序号（0, 1, 2...）"""
+```
+
+#### 4.1.3 迁移方案
+
+alembic 新增 migration，两个表各加 4 个字段，默认值为空/false，无数据回填成本。
+
+---
+
+### 4.2 变体引擎（Variant Engine）
+
+**核心组件**：根据 count 和 seed，生成 N 组互不相同的生成参数。
+
+#### 4.2.1 变纬度设计
+
+| 维度 | 策略 | 说明 |
+|------|------|------|
+| **素材子集选择** | 从素材池中随机选 M 个（M=min(素材数, 模板clip数*2)） | 版本差异最大的来源 |
+| **素材排序** | 随机打乱顺序 | 影响叙事节奏 |
+| **标题选择** | 从 title_ids 中随机选 1 个 | 影响文案内容 |
+| **配音选择** | 从 voice_ids 中随机选 1 个（如有多个） | 影响听觉体验 |
+| **转场风格** | 从预设转场池中随机选 1 种 | 影响视觉过渡 |
+| **BGM 选择** | 从 bgm 列表中随机选 1 首（如有配置） | 影响氛围 |
+
+#### 4.2.2 去重机制
+
+- 同一批次内，变体参数必须两两不同（至少素材组合或排序不同）
+- 使用 `variant_seed` 保证可复现（相同 seed → 相同变体）
+- 如果素材数量不足导致无法生成 N 个不同版本，按实际能生成的数量返回
+
+#### 4.2.3 接口设计
+
+```python
+def generate_variants(
+    count: int,
+    seed: int,
+    asset_pool: list[str],        # 可用素材 ID 列表
+    title_pool: list[str] = [],    # 可用标题 ID 列表
+    voice_pool: list[str] = [],    # 可用配音 ID 列表
+    template_id: str = "",
+) -> list[dict]:
+    """
+    生成 count 组变体参数。
+    
+    每组参数包含：asset_ids（选用的素材+排序）、title_id、voice_id、
+    transition_style 等，确保两两不同。
+    """
+```
+
+---
+
+### 4.3 API 层设计
+
+#### 4.3.1 预览生成接口
+
+```
+POST /api/v1/templates/{template_id}/generate-preview
+```
+
+**请求体**：
+```json
+{
+  "asset_library_id": "lib_xxx",
+  "asset_ids": ["asset_1", "asset_2", ...],
+  "title_ids": ["title_1", "title_2"],
+  "voice_ids": ["voice_1", "voice_2"],
+  "bgm_config": {},
+  "count": 3,
+  "seed": 0
+}
+```
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| template_id | path | ✅ | - | 模板 ID |
+| asset_library_id | body | ✅ | - | 素材库 ID |
+| asset_ids | body | ✅ | - | 素材池（从中选子集/排序） |
+| title_ids | body | - | [] | 标题池（可选，不传则不用标题） |
+| voice_ids | body | - | [] | 配音池（可选） |
+| bgm_config | body | - | {} | BGM 配置 |
+| count | body | - | 3 | 生成几个预览版本（1~10） |
+| seed | body | - | 0 | 随机种子，0 表示随机 |
+
+**响应**：
+```json
+{
+  "preview_batch_id": "pb_xxx",
+  "count": 3,
+  "tasks": [
+    {
+      "task_id": "gen_xxx_0",
+      "variant_index": 0,
+      "status": "processing"
+    },
+    {
+      "task_id": "gen_xxx_1",
+      "variant_index": 1,
+      "status": "processing"
+    },
+    ...
+  ]
+}
+```
+
+#### 4.3.2 预览批次查询接口
+
+```
+GET /api/v1/preview-batches/{batch_id}
+```
+
+返回批次内所有预览任务的状态、结果（已完成的带 video_url）。
+
+**响应**：
+```json
+{
+  "preview_batch_id": "pb_xxx",
+  "count": 3,
+  "completed_count": 2,
+  "tasks": [
+    {
+      "task_id": "gen_xxx_0",
+      "variant_index": 0,
+      "status": "completed",
+      "video_url": "https://oss.xxx/preview/xxx.mp4",
+      "duration": 15.5,
+      "thumbnail_url": "https://oss.xxx/preview/xxx.jpg"
+    },
+    ...
+  ]
+}
+```
+
+#### 4.3.3 预览转正式生成
+
+```
+POST /api/v1/preview-batches/{batch_id}/tasks/{task_id}/promote
+```
+
+将某个预览版本升级为正式生成（复用素材缓存，重新全分辨率渲染）。
+
+---
+
+### 4.4 渲染参数降级
+
+预览模式下自动调整以下参数：
+
+| 参数 | 正式生成 | 预览生成 |
+|------|---------|---------|
+| 分辨率 | 720p (1280x720) | 480p (854x480) |
+| 码率 | 4 Mbps | 1.5 Mbps |
+| 帧率 | 30 fps | 24 fps |
+| 时长 | 完整时长 | 前 15 秒（或第一段完整clip） |
+| 转场效果 | 完整转场 | 仅淡入淡出 |
+| 高级特效 | 全部启用 | 跳过粒子/光效等 |
+| 字幕 | 完整渲染 | 正常渲染 |
+| 配音 | 完整混音 | 正常混音 |
+| 输出质量 | high | medium |
+
+**实现位置**：`_render_video` 函数入口处，根据 `is_preview` 标记调整渲染配置。
+
+---
+
+### 4.5 任务调度
+
+- **并行执行**：N 个预览任务并行提交到 Celery，不排队等待
+- **低优先级**：预览任务走独立队列（`preview_queue`），不抢占正式生成资源
+- **超时控制**：预览任务超时时间 5 分钟（正式 30 分钟）
+- **自动清理**：预览视频 7 天后自动从 OSS 删除，任务记录标记为 archived
+
+---
+
+## 5. 前端对接要点
+
+### 5.1 交互流程
+
+```
+第2步选素材 → 第3步点击"生成预览"
+  → 显示 loading + 进度
+  → 预览陆续完成，左侧列表逐张出现
+  → 用户点击左侧不同版本，右侧预览区切换
+  → 用户选中满意版本 → 点击"正式生成"
+```
+
+### 5.2 需要对齐的接口
+
+1. **预览创建**：`POST /templates/{id}/generate-preview`
+2. **批次状态轮询**：`GET /preview-batches/{id}`（建议 2s 轮询，或走 SSE）
+3. **预览转正式**：`POST /preview-batches/{id}/tasks/{task_id}/promote`
+
+### 5.3 数据格式对齐
+
+预览视频条目结构：
+```json
+{
+  "id": "gen_xxx",
+  "variant_index": 0,
+  "status": "completed",
+  "video_url": "https://...",
+  "duration": 15.5,
+  "file_size": 2850000,
+  "thumbnail_url": "https://...",
+  "is_preview": true
+}
+```
+
+---
+
+## 6. 配额与计费
+
+- 预览生成**不计入**用户配额
+- 同一模板 + 同一素材池，每天最多生成 3 次多版本预览（防滥用）
+- 单个预览批次最多 10 个版本
+
+---
+
+## 7. 实施步骤
+
+### Phase 1：单版本预览（MVP，2 天）
+1. 数据模型 + 迁移（is_preview 字段）
+2. API 层支持 is_preview 参数
+3. 渲染分辨率降级（480p）
+4. 不计入配额
+5. 基础测试
+
+### Phase 2：多版本预览（3 天）
+1. 变体引擎实现（素材随机选择 + 排序 + 去重）
+2. preview_batch 批次管理
+3. 批量创建 N 个预览任务
+4. 批次查询接口
+5. 前端联调
+
+### Phase 3：预览转正式 + 优化（2 天）
+1. 预览转正式生成接口（promote）
+2. 素材下载缓存复用
+3. 独立预览队列（低优先级）
+4. 自动清理机制
+5. 完整测试 + 压测
+
+---
+
+## 8. 风险与注意事项
+
+| 风险 | 影响 | 应对 |
+|------|------|------|
+| 并发预览任务过多打满 worker | 正式生成被阻塞 | 独立预览队列 + 限流 |
+| 变体生成的视频差异不够大 | 用户觉得"都一样" | 优先素材子集+排序差异，保证视觉差异 |
+| 预览视频占用 OSS 存储 | 存储成本上升 | 7 天自动清理 + 低码率 |
+| N 个版本同时下载重复素材 | 带宽浪费 | 批次内共享一次下载（Phase 3 优化） |
+| 用户预期管理 | 以为预览就是最终效果 | 明确标注"预览版"，说明分辨率差异 |
+
+---
+
+## 9. 开发量估算
+
+| 阶段 | 后端 | 前端 | 合计 |
+|------|------|------|------|
+| Phase 1 单版本预览 | 2 天 | 1 天 | 3 天 |
+| Phase 2 多版本预览 | 3 天 | 2 天 | 5 天 |
+| Phase 3 转正式+优化 | 2 天 | 1 天 | 3 天 |
+| **总计** | **7 天** | **4 天** | **~7 天（并行）** |
+
+---
+
+## 10. 与 v1 方案的差异总结
+
+1. **新增多版本能力**：从"生成1个预览"升级为"生成N个不重复预览"
+2. **新增变体引擎**：负责素材选择/排序/配音/标题的随机化
+3. **新增批次概念**：preview_batch 管理一组预览任务
+4. **新增 promote 接口**：预览转正式生成
+5. **独立队列**：预览不抢占正式生成资源
+6. **开发量**：从 2-3 天增加到约 7 天（后端）

alembic/versions/053_generation_task_is_preview.py

@@ -0,0 +1,61 @@
+"""#1197 - 预览生成：generation_tasks 表新增 is_preview 字段
+
+Revision ID: 053
+Revises: 052
+Create Date: 2026-08-15
+
+Changes:
+1. generation_tasks 表新增 is_preview 字段，标记是否为预览生成任务（低清 480p）
+2. 默认 False，与现有正式生成任务兼容
+3. 加索引以支持按预览/正式任务筛选
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "053_generation_task_is_preview"
+down_revision = "052_generation_task_bgm_config"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    if context.get_context().dialect.name == "postgresql":
+        # 检查列是否已存在（幂等）
+        result = conn.execute(
+            sa.text(
+                "SELECT column_name FROM information_schema.columns "
+                "WHERE table_name = 'generation_tasks' AND column_name = 'is_preview'"
+            )
+        )
+        if result.scalar() is not None:
+            return
+
+    op.add_column(
+        "generation_tasks",
+        sa.Column("is_preview", sa.Boolean, nullable=False, server_default=sa.text("false")),
+    )
+    # 加索引
+    op.create_index(
+        "ix_generation_tasks_is_preview",
+        "generation_tasks",
+        ["is_preview"],
+    )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    if context.get_context().dialect.name == "postgresql":
+        result = conn.execute(
+            sa.text(
+                "SELECT column_name FROM information_schema.columns "
+                "WHERE table_name = 'generation_tasks' AND column_name = 'is_preview'"
+            )
+        )
+        if result.scalar() is None:
+            return
+
+    op.drop_index("ix_generation_tasks_is_preview", table_name="generation_tasks")
+    op.drop_column("generation_tasks", "is_preview")

alembic/versions/054_confirm_gen_fields.py

@@ -0,0 +1,82 @@
+"""确认生成 API 改造：为 generation_tasks 表添加 source_task_id、output_width、output_height、cover_url、custom_title 字段
+
+Revision ID: 054_confirm_gen_fields
+Revises: 053_generation_task_is_preview
+Create Date: 2026-08-16
+
+Changes:
+1. generation_tasks 表新增 source_task_id（来源预览任务 ID，带索引）
+2. generation_tasks 表新增 output_width / output_height（动态输出分辨率）
+3. generation_tasks 表新增 cover_url / custom_title（自定义封面和标题）
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "054_confirm_gen_fields"
+down_revision = "053_generation_task_is_preview"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    is_pg = conn.dialect.name == "postgresql"
+
+    if is_pg:
+        # 幂等检查：source_task_id 列是否已存在
+        result = conn.execute(
+            sa.text(
+                "SELECT column_name FROM information_schema.columns "
+                "WHERE table_name = 'generation_tasks' AND column_name = 'source_task_id'"
+            )
+        )
+        if result.scalar() is not None:
+            return
+
+    # source_task_id
+    op.add_column(
+        "generation_tasks",
+        sa.Column("source_task_id", sa.String(32), nullable=False, server_default=""),
+    )
+
+    # output_width
+    op.add_column(
+        "generation_tasks",
+        sa.Column("output_width", sa.Integer, nullable=False, server_default=sa.text("1280")),
+    )
+
+    # output_height
+    op.add_column(
+        "generation_tasks",
+        sa.Column("output_height", sa.Integer, nullable=False, server_default=sa.text("720")),
+    )
+
+    # cover_url
+    op.add_column(
+        "generation_tasks",
+        sa.Column("cover_url", sa.String(1000), nullable=False, server_default=""),
+    )
+
+    # custom_title
+    op.add_column(
+        "generation_tasks",
+        sa.Column("custom_title", sa.String(500), nullable=False, server_default=""),
+    )
+
+    # 索引
+    op.create_index(
+        "ix_generation_tasks_source_task_id",
+        "generation_tasks",
+        ["source_task_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_generation_tasks_source_task_id", table_name="generation_tasks")
+    op.drop_column("generation_tasks", "custom_title")
+    op.drop_column("generation_tasks", "cover_url")
+    op.drop_column("generation_tasks", "output_height")
+    op.drop_column("generation_tasks", "output_width")
+    op.drop_column("generation_tasks", "source_task_id")

apps/api/app/api/router.py

@@ -7,6 +7,7 @@ from app.api.routes.chunked_upload import router as chunked_upload_router
 from app.api.routes.classification_jobs import router as classification_jobs_router
 from app.api.routes.duplication import router as duplication_router
 from app.api.routes.feature_flags import router as feature_flags_router
+from app.api.routes.generation_preview import router as generation_preview_router
 from app.api.routes.generation_tasks import router as generation_tasks_router
 from app.api.routes.health import router as health_check_router
 from app.api.routes.ingest_jobs import router as ingest_jobs_router
@@ -87,6 +88,11 @@ api_router.include_router(
     prefix="/generation",
     tags=["Generation"],
 )
+api_router.include_router(
+    generation_preview_router,
+    prefix="/generation",
+    tags=["Generation"],
+)
 api_router.include_router(
     titles_router,
     prefix="/titles",

apps/api/app/api/routes/assets.py

@@ -19,6 +19,9 @@ from app.schemas.asset import (
     BatchTagRequest,
     CreateAssetRequest,
     ListAssetsResponse,
+    SmartMatchItem,
+    SmartMatchRequest,
+    SmartMatchResponse,
     UpdateAssetRequest,
     UpdateAssetReviewRequest,
 )
@@ -30,6 +33,7 @@ from packages.application import (
     CreateAssetUseCase,
 )
 from packages.domain import AssetStatus, ClassificationStatus
+from packages.domain.smart_match import smart_select_assets
 
 logger = logging.getLogger(__name__)
 
@@ -519,6 +523,51 @@ def batch_mark_assets(
     )
 
 
+@router.post("/smart-match", response_model=SmartMatchResponse)
+def smart_match_assets(
+    request: SmartMatchRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    asset_library_repository: Any = Depends(get_asset_library_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> SmartMatchResponse:
+    """智能选素材：根据素材库内容，按质量分+时长均衡+新鲜度+未使用偏好综合评分，返回 Top N 素材。"""
+    library = asset_library_repository.get(request.library_id)
+    if library is None:
+        raise HTTPException(status_code=404, detail=f"AssetLibrary {request.library_id} not found")
+    check_project_access(library.project_id, authenticated_user.user.id, project_repository)
+
+    # 获取素材库中所有 ready 素材（DB 层按 kind 过滤，避免加载不必要的数据到内存）
+    # kind → file_type 映射：schema 已校验只允许 video/image/audio，与 file_type 一致
+    if request.kind:
+        filtered_assets = asset_repository.find_by_library_and_file_type(
+            request.library_id, request.kind, status=["ready"], limit=10000
+        )
+    else:
+        filtered_assets = asset_repository.find_by_library(
+            request.library_id, status=["ready"], limit=10000
+        )
+    total_candidates = len(filtered_assets)
+
+    # 调用统一智能选素材算法（kind 已在 DB 层过滤，无需重复过滤）
+    results = smart_select_assets(
+        filtered_assets,
+        limit=request.limit,
+        kind=None,
+    )
+
+    items = [
+        SmartMatchItem(
+            asset=_to_asset_response(r.asset),
+            score=r.score,
+            breakdown=r.breakdown,
+        )
+        for r in results
+    ]
+
+    return SmartMatchResponse(items=items, total_candidates=total_candidates)
+
+
 @router.get("/{asset_id}", response_model=AssetResponse)
 def get_asset(
     asset_id: str,
@@ -622,20 +671,28 @@ def create_asset(
     asset_library_repository: Any = Depends(get_asset_library_repository),
     project_repository: Any = Depends(get_project_repository),
 ) -> AssetResponse:
-    project = project_repository.find_by_id(request.project_id)
+    # 先获取素材库，用于推导 project_id（前端可能不传）
+    library = asset_library_repository.get(request.library_id)
+    if library is None:
+        raise HTTPException(status_code=404, detail=f"AssetLibrary {request.library_id} not found")
+
+    # project_id 自动推导：优先用请求值，否则从 library 关联的项目获取
+    project_id = request.project_id or library.project_id
+
+    project = project_repository.find_by_id(project_id)
     if project is None:
-        raise HTTPException(status_code=404, detail=f"Project {request.project_id} not found")
+        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
     if not project.can_access(authenticated_user.user.id):
         raise HTTPException(status_code=403, detail="Access denied to project")
 
-    library = asset_library_repository.get(request.library_id)
-    if library is None or library.project_id != request.project_id:
-        raise HTTPException(status_code=404, detail=f"AssetLibrary {request.library_id} not found")
+    # 确保 library 和 project 归属一致
+    if library.project_id != project_id:
+        raise HTTPException(status_code=400, detail="AssetLibrary does not belong to the specified project")
 
     use_case = CreateAssetUseCase(asset_repository)
     item = use_case.execute(
         CreateAssetCommand(
-            project_id=request.project_id,
+            project_id=project_id,
             library_id=request.library_id,
             name=request.name,
             storage_key=request.storage_key,

apps/api/app/api/routes/generation_preview.py

@@ -0,0 +1,403 @@
+"""预览生成路由 — Phase 1：单版本预览接口（创建 + 查询）。
+
+路径前缀：/api/v1/generation/preview（与 /generation/tasks 同体系）
+"""
+
+from __future__ import annotations
+
+import logging
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.core.storage import get_storage_service
+from app.core.task_enqueue import (
+    GLOBAL_PENDING_LIMIT,
+    USER_PENDING_LIMIT,
+    GlobalQueueFull,
+    UserPendingLimitExceeded,
+    safe_enqueue_generation_task,
+)
+from app.dependencies import (
+    get_db_session,
+    get_generated_video_repository,
+    get_generation_task_repository,
+)
+from app.schemas.generation_task import (
+    CreatePreviewGenerationTaskRequest,
+    PreviewGenerationTaskResponse,
+)
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.edit_template_repository import (
+    SQLAlchemyEditTemplateRepository,
+)
+from packages.adapters.sqlalchemy_impl.template_repository import (
+    SQLAlchemyTemplateRepository,
+)
+from packages.application import (
+    CreateGenerationTaskCommand,
+    CreateGenerationTaskUseCase,
+    GetGenerationTaskUseCase,
+    ListGeneratedVideosByTaskUseCase,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+PREVIEW_RESOLUTION = "854x480"
+
+# 模板 mode → 视频比例映射
+_TEMPLATE_MODE_TO_RATIO = {
+    "pip": "9:16",
+    "standard": "16:9",
+    "square": "1:1",
+}
+
+
+def _calc_preview_resolution(video_ratio: str = "") -> str:
+    """根据视频比例计算预览分辨率（短边 480，长边按比例）。
+
+    支持的比例：16:9, 9:16, 1:1, 4:3, 3:4, 其他默认 16:9。
+    """
+    ratio_map = {
+        "16:9": "854x480",
+        "9:16": "480x854",
+        "1:1": "480x480",
+        "4:3": "640x480",
+        "3:4": "480x640",
+    }
+    return ratio_map.get(video_ratio.strip(), PREVIEW_RESOLUTION)
+
+
+def _infer_video_ratio_from_template(
+    template_id: str, db: Session, user_id: str = ""
+) -> str:
+    """从模板 mode 推断视频比例，前端未传 video_ratio 时使用。
+
+    Returns:
+        视频比例字符串（如 "9:16"），查询失败返回空字符串。
+    """
+    if not template_id:
+        return ""
+    try:
+        repo = SQLAlchemyTemplateRepository(db)
+        template = repo.get(template_id, user_id)
+        if template:
+            mode = getattr(template, "mode", "") or ""
+            ratio = _TEMPLATE_MODE_TO_RATIO.get(mode.strip(), "")
+            if ratio:
+                logger.info(
+                    "[预览生成] 从模板 mode=%s 推断 video_ratio=%s",
+                    mode,
+                    ratio,
+                )
+            return ratio
+    except Exception:
+        logger.warning(
+            "[预览生成] 查询模板失败，跳过 video_ratio 推断: template_id=%s",
+            template_id,
+            exc_info=True,
+        )
+    return ""
+
+
+def _resolve_strategy_id_from_template(
+    template_id: str, db: Session, user_id: str = ""
+) -> str:
+    """从模板读取 editing_mode / mode 作为 strategy_id。
+
+    优先查新模板系统（EditTemplate.editing_mode），fallback 旧模板（Template.mode）。
+    Worker 端使用 strategy_id 作为渲染 mode，为空则默认 one_take。
+    """
+    if not template_id:
+        return ""
+
+    # 优先查新模板系统
+    try:
+        new_repo = SQLAlchemyEditTemplateRepository(db)
+        new_template = new_repo.get(template_id)
+        if new_template and getattr(new_template, "editing_mode", ""):
+            mode = new_template.editing_mode.strip()
+            if mode:
+                logger.info(
+                    "[预览生成] 从新模板 editing_mode=%s (template_id=%s)",
+                    mode,
+                    template_id,
+                )
+                # 画中画已下线，pip/voice_pip 统一映射为 one_take
+                if mode in ("pip", "voice_pip"):
+                    logger.info("[预览生成] %s → one_take (画中画已下线)", mode)
+                    mode = "one_take"
+                return mode
+    except Exception:
+        logger.debug(
+            "[预览生成] 新模板查询失败，尝试旧模板: template_id=%s",
+            template_id,
+            exc_info=True,
+        )
+
+    # fallback 旧模板系统
+    try:
+        old_repo = SQLAlchemyTemplateRepository(db)
+        old_template = old_repo.get(template_id, user_id)
+        if old_template:
+            mode = getattr(old_template, "mode", "") or ""
+            mode = mode.strip()
+            if mode:
+                logger.info(
+                    "[预览生成] 从旧模板 mode=%s (template_id=%s)",
+                    mode,
+                    template_id,
+                )
+                # 画中画已下线，pip/voice_pip 统一映射为 one_take
+                if mode in ("pip", "voice_pip"):
+                    logger.info("[预览生成] %s → one_take (画中画已下线)", mode)
+                    mode = "one_take"
+                return mode
+    except Exception:
+        logger.warning(
+            "[预览生成] 旧模板查询也失败，strategy_id 留空: template_id=%s",
+            template_id,
+            exc_info=True,
+        )
+
+    return ""
+
+
+def _mark_task_failed(repo, task, reason: str) -> None:
+    """入队失败时将任务标记为 failed，避免产生僵尸 pending 数据。"""
+    try:
+        task.mark_failed(error_message=f"入队失败：{reason}")
+        repo.update(task)
+    except Exception:
+        logger.exception("[预览生成] 标记任务失败时异常: task_id=%s", task.id)
+
+
+def _sign_video_url(raw_url: str) -> str:
+    """为私有 OSS bucket 的视频 URL 生成预签名下载链接。
+
+    有效期 2 小时，签名失败时降级返回原始 URL。
+    """
+    if not raw_url:
+        return ""
+    try:
+        storage = get_storage_service()
+        signed = storage.get_download_url(raw_url, expires_seconds=7200)
+        # 如果返回的 URL 与原始 URL 完全不同且不是签名 URL（说明 bucket 未配置），
+        # 降级返回原始 URL
+        if signed and signed != raw_url:
+            return signed
+        if signed == raw_url:
+            return raw_url
+        # signed 为空或与 raw_url 无关，返回原始
+        return raw_url
+    except Exception:
+        logger.warning("[预览] URL签名失败，降级返回原始URL: %s", raw_url[:100], exc_info=True)
+        return raw_url
+
+
+def _to_preview_response(task, generated_videos: list | None = None) -> PreviewGenerationTaskResponse:
+    """将领域任务对象转换为预览响应 DTO。
+
+    Args:
+        task: GenerationTask 领域对象
+        generated_videos: 生成的视频列表（可选），取第一个作为 video_url
+
+    Returns:
+        PreviewGenerationTaskResponse
+    """
+    video_url = ""
+    duration = 0.0
+    file_size = 0
+    if generated_videos:
+        first_video = generated_videos[0]
+        raw_url = getattr(first_video, "file_url", "") or ""
+        # P0 修复：私有 bucket 需要预签名 URL，否则前端 403 → 黑屏
+        video_url = _sign_video_url(raw_url)
+        duration = float(getattr(first_video, "duration", 0.0) or 0.0)
+        file_size = int(getattr(first_video, "file_size", 0) or 0)
+
+    # 从 extra_meta / metadata 中提取统计信息（如果有）
+    extra_meta = getattr(task, "extra_meta", {}) or {}
+    clip_count = int(extra_meta.get("clip_count", len(getattr(task, "asset_ids", [])) or 0))
+    transition_count = int(extra_meta.get("transition_count", max(0, clip_count - 1)))
+    material_usage = extra_meta.get("material_usage", {}) or {}
+
+    # 计算生成耗时
+    generate_duration = 0.0
+    started_at = getattr(task, "started_at", None)
+    completed_at = getattr(task, "completed_at", None)
+    if started_at and completed_at:
+        generate_duration = (completed_at - started_at).total_seconds()
+
+    return PreviewGenerationTaskResponse(
+        task_id=task.id,
+        status=task.status.value if hasattr(task.status, "value") else str(task.status),
+        progress=float(task.progress or 0.0),
+        is_preview=bool(getattr(task, "is_preview", True)),
+        resolution=getattr(task, "resolution", PREVIEW_RESOLUTION) or PREVIEW_RESOLUTION,
+        video_url=video_url,
+        duration=duration,
+        file_size=file_size,
+        clip_count=clip_count,
+        transition_count=transition_count,
+        material_usage=material_usage,
+        error_message=task.error_message or "",
+        created_at=task.created_at,
+        started_at=started_at,
+        finished_at=completed_at,
+        generate_duration=generate_duration,
+    )
+
+
+@router.post("/preview", response_model=PreviewGenerationTaskResponse, status_code=201)
+def create_preview_generation_task(
+    request: CreatePreviewGenerationTaskRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    generation_task_repository=Depends(get_generation_task_repository),
+    db: Session = Depends(get_db_session),
+) -> PreviewGenerationTaskResponse:
+    """创建预览生成任务。
+
+    预览为完整时长的低清版（480p + 低码率），效果与正式生成一致，仅清晰度降低。
+
+    Args:
+        request: 预览任务创建请求（template_id + asset_ids 等）
+
+    Returns:
+        201 + 预览任务详情
+    """
+    user_id = authenticated_user.user.id
+    logger.info(
+        "[预览生成] 接收请求: user_id=%s, template_id=%s, asset_count=%d, preview_count=%d",
+        user_id,
+        request.template_id,
+        len(request.asset_ids),
+        request.preview_count,
+    )
+
+    # 预检查队列限流
+    try:
+        user_pending = generation_task_repository.count_pending_by_user(user_id)
+        global_pending = generation_task_repository.count_pending_total()
+        if user_pending + 1 > USER_PENDING_LIMIT:
+            raise UserPendingLimitExceeded(user_id=user_id, pending_count=user_pending + 1, limit=USER_PENDING_LIMIT)
+        if global_pending + 1 > GLOBAL_PENDING_LIMIT:
+            raise GlobalQueueFull(pending_count=global_pending + 1, limit=GLOBAL_PENDING_LIMIT)
+    except UserPendingLimitExceeded as e:
+        raise HTTPException(
+            status_code=429,
+            detail=f"您的待处理任务过多（当前 {e.pending_count - 1}/{e.limit}），请等待后再提交",
+        ) from e
+    except GlobalQueueFull as e:
+        raise HTTPException(
+            status_code=503,
+            detail="系统繁忙，请稍后再试",
+        ) from e
+
+    # 确定视频比例：优先前端传入，否则从模板 mode 推断
+    video_ratio = request.video_ratio or ""
+    if not video_ratio and request.template_id:
+        video_ratio = _infer_video_ratio_from_template(request.template_id, db, user_id)
+
+    # 从模板读取 editing_mode / mode 作为 strategy_id（渲染 pipeline 的 mode 参数）
+    strategy_id = _resolve_strategy_id_from_template(request.template_id, db, user_id)
+
+    use_case = CreateGenerationTaskUseCase(generation_task_repository)
+
+    try:
+        task = use_case.execute(
+            CreateGenerationTaskCommand(
+                project_id="",
+                asset_library_id="",
+                strategy_id=strategy_id,
+                voice_library_id="",
+                template_id=request.template_id,
+                asset_ids=list(request.asset_ids),
+                title_ids=list(request.title_ids),
+                voice_ids=list(request.voice_ids),
+                created_by_user_id=user_id,
+                source_edit_plan_id="",
+                asset_select_mode="",
+                batch_id="",
+                video_title=request.video_title,
+                resolution=_calc_preview_resolution(video_ratio),
+                bgm_config=request.bgm_config or {},
+                auto_retry_enabled=False,
+                auto_retry_max=0,
+                is_preview=True,
+            )
+        )
+    except ValueError as e:
+        logger.warning("[预览生成] 创建失败: %s", e)
+        raise HTTPException(status_code=400, detail=str(e)) from e
+    except Exception as e:
+        logger.error("[预览生成] 创建失败: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail="创建预览生成任务失败，请稍后再试") from e
+
+    # 入队执行；若入队失败则标记任务为 failed 避免僵尸数据
+    try:
+        if not safe_enqueue_generation_task(
+            task,
+            generation_task_repository,
+            user_id=user_id,
+            log_prefix="[预览生成]",
+            log_task_status=True,
+        ):
+            logger.warning("[预览生成] 任务入队失败: task_id=%s", task.id)
+            _mark_task_failed(generation_task_repository, task, "任务入队失败")
+            raise HTTPException(status_code=500, detail="任务入队失败，请稍后重试")
+    except UserPendingLimitExceeded as e:
+        _mark_task_failed(generation_task_repository, task, "待处理任务超限")
+        raise HTTPException(
+            status_code=429,
+            detail=f"您的待处理任务过多（当前 {e.pending_count - 1}/{e.limit}），请等待后再提交",
+        ) from None
+    except GlobalQueueFull:
+        _mark_task_failed(generation_task_repository, task, "系统队列已满")
+        raise HTTPException(
+            status_code=503,
+            detail="系统繁忙，请稍后再试",
+        ) from None
+
+    return _to_preview_response(task)
+
+
+@router.get("/preview/{task_id}", response_model=PreviewGenerationTaskResponse)
+def get_preview_generation_task(
+    task_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    generation_task_repository=Depends(get_generation_task_repository),
+    generated_video_repository=Depends(get_generated_video_repository),
+) -> PreviewGenerationTaskResponse:
+    """查询预览生成任务状态。
+
+    Args:
+        task_id: 任务 ID
+
+    Returns:
+        预览任务详情（含状态、进度、结果 URL 等）
+    """
+    use_case = GetGenerationTaskUseCase(generation_task_repository)
+    task = use_case.execute(task_id)
+    if task is None:
+        raise HTTPException(status_code=404, detail=f"预览任务 {task_id} 不存在")
+
+    # 权限校验：任务必须属于当前用户（统一转 str 比较，避免 UUID/str 类型差异）
+    task_user_id = str(getattr(task, "created_by_user_id", "") or "")
+    if not task_user_id or task_user_id != str(authenticated_user.user.id):
+        raise HTTPException(status_code=403, detail="无权访问该任务")
+
+    # 校验是否为预览任务
+    if not getattr(task, "is_preview", False):
+        raise HTTPException(status_code=404, detail=f"预览任务 {task_id} 不存在")
+
+    # 查询生成的视频（取第一个）
+    generated_videos = []
+    status_val = task.status.value if hasattr(task.status, "value") else str(task.status)
+    if status_val == "completed":
+        list_use_case = ListGeneratedVideosByTaskUseCase(generated_video_repository)
+        generated_videos = list_use_case.execute(task_id)
+
+    return _to_preview_response(task, generated_videos=generated_videos)

apps/api/app/api/routes/generation_tasks.py

@@ -26,6 +26,7 @@ from app.schemas.generated_video import (
 )
 from app.schemas.generation_task import (
     BatchGenerationTaskResponse,
+    ConfirmGenerationRequest,
     CreateGenerationTaskRequest,
     GenerationTaskResponse,
     ListGenerationTasksResponse,
@@ -38,6 +39,7 @@ from packages.application import (
     GetGenerationTaskUseCase,
     ListGeneratedVideosByTaskUseCase,
 )
+from packages.domain.smart_match import smart_select_assets
 
 logger = logging.getLogger(__name__)
 
@@ -61,6 +63,12 @@ def _to_generation_task_response(task) -> GenerationTaskResponse:
         video_title=getattr(task, "video_title", ""),
         resolution=getattr(task, "resolution", ""),
         bgm_config=getattr(task, "bgm_config", {}) or {},
+        is_preview=getattr(task, "is_preview", False),
+        source_task_id=getattr(task, "source_task_id", ""),
+        output_width=getattr(task, "output_width", 1280),
+        output_height=getattr(task, "output_height", 720),
+        cover_url=getattr(task, "cover_url", ""),
+        custom_title=getattr(task, "custom_title", ""),
         logs=getattr(task, "logs", "[]"),
         status=task.status,
         progress=task.progress,
@@ -124,19 +132,11 @@ def _select_assets_from_library(
         return [a.id for a in selected]
 
     if mode == "smart":
-        # 智能匹配：按质量分降序 + 时长降序作为tiebreaker
-        # 注意：这里使用简单的 quality_score 排序保持向后兼容
-        # 更复杂的4维评分+多样性策略由 SmartAssetSelector 服务提供（用于 AI 精选等场景）
-        scored_assets = sorted(
-            ready_video_assets,
-            key=lambda a: (
-                -(a.quality_score if a.quality_score is not None else 0.0),
-                -(getattr(a, "duration", 0.0) or 0.0),
-            ),
-        )
-        if count > 0:
-            scored_assets = scored_assets[:count]
-        return [a.id for a in scored_assets]
+        # 智能匹配：统一使用 packages/domain/smart_match.py 的多维评分+多样性选取
+        # 评分维度：质量分(40%) + 时长适配(30%) + 新鲜度(20%) + 未使用加分(10%)
+        limit = count if count > 0 else None
+        results = smart_select_assets(ready_video_assets, limit=limit, kind="video")
+        return [r.asset.id for r in results]
 
     # 默认 all 模式：返回全部 ready 视频素材
     return [a.id for a in ready_video_assets]
@@ -271,13 +271,19 @@ def create_generation_task(
             detail="系统繁忙，请稍后再试",
         ) from e
 
+    # 画中画已下线：strategy_id 中的 pip/voice_pip 统一映射为 one_take
+    effective_strategy_id = request.strategy_id
+    if effective_strategy_id in ("pip", "voice_pip"):
+        logger.info("画中画已下线，strategy_id %s → one_take", effective_strategy_id)
+        effective_strategy_id = "one_take"
+
     try:
         for _ in range(count):
             task = use_case.execute(
                 CreateGenerationTaskCommand(
                     project_id=project_id,
                     asset_library_id=asset_library_id,
-                    strategy_id=request.strategy_id,
+                    strategy_id=effective_strategy_id,
                     voice_library_id=request.voice_library_id,
                     template_id=request.template_id,
                     asset_ids=resolved_asset_ids,
@@ -292,6 +298,12 @@ def create_generation_task(
                     bgm_config=request.bgm_config,
                     auto_retry_enabled=request.auto_retry_enabled,
                     auto_retry_max=request.auto_retry_max,
+                    is_preview=request.is_preview,
+                    source_task_id=request.source_task_id,
+                    output_width=request.output_width,
+                    output_height=request.output_height,
+                    cover_url=request.cover_url,
+                    custom_title=request.custom_title,
                 )
             )
             try:
@@ -332,6 +344,83 @@ def create_generation_task(
     return BatchGenerationTaskResponse(items=items, total=len(items))
 
 
+@router.post("/tasks/{task_id}/confirm", response_model=BatchGenerationTaskResponse)
+def confirm_generation(
+    task_id: str,
+    request: ConfirmGenerationRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    generation_task_repository: Any = Depends(get_generation_task_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> BatchGenerationTaskResponse:
+    """确认生成 — 基于预览任务创建正式生成任务。
+
+    查找预览任务，复制其配置，创建新的正式生成任务（is_preview=False），
+    使用高分辨率，复用 worker.generate_video 渲染路径。
+    """
+    # 1. 查找源预览任务
+    source_task = generation_task_repository.get(task_id)
+    if source_task is None:
+        raise HTTPException(status_code=404, detail=f"Preview task {task_id} not found")
+
+    # 2. 权限检查
+    if source_task.created_by_user_id and source_task.created_by_user_id != authenticated_user.user.id:
+        raise HTTPException(status_code=403, detail="Access denied to this task")
+    if source_task.project_id:
+        check_project_access(source_task.project_id, authenticated_user.user.id, project_repository)
+
+    # 3. 创建正式生成任务，复制预览任务的配置
+    use_case = CreateGenerationTaskUseCase(generation_task_repository)
+    new_task = use_case.execute(
+        CreateGenerationTaskCommand(
+            project_id=source_task.project_id,
+            asset_library_id=source_task.asset_library_id,
+            strategy_id=source_task.strategy_id,
+            voice_library_id=source_task.voice_library_id,
+            template_id=source_task.template_id,
+            asset_ids=source_task.asset_ids,
+            title_ids=source_task.title_ids,
+            voice_ids=source_task.voice_ids,
+            created_by_user_id=authenticated_user.user.id,
+            source_edit_plan_id=source_task.source_edit_plan_id or "",
+            asset_select_mode=source_task.asset_select_mode,
+            video_title=getattr(source_task, "video_title", ""),
+            resolution=getattr(source_task, "resolution", ""),
+            is_preview=False,
+            source_task_id=task_id,
+            output_width=request.output_width,
+            output_height=request.output_height,
+            cover_url=request.cover_url,
+            custom_title=request.custom_title,
+        )
+    )
+
+    # 4. 调度 worker.generate_video（同一条渲染路径）
+    try:
+        if not safe_enqueue_generation_task(
+            new_task,
+            generation_task_repository,
+            user_id=authenticated_user.user.id,
+            log_prefix="[确认生成]",
+            log_task_status=True,
+        ):
+            logger.warning("[确认生成] 入队失败: task_id=%s", new_task.id)
+    except UserPendingLimitExceeded:
+        raise HTTPException(
+            status_code=429,
+            detail="您的待处理任务过多，请等待完成后再提交",
+        ) from None
+    except GlobalQueueFull:
+        raise HTTPException(
+            status_code=503,
+            detail="系统繁忙，请稍后再试",
+        ) from None
+
+    return BatchGenerationTaskResponse(
+        items=[_to_generation_task_response(new_task)],
+        total=1,
+    )
+
+
 @router.get("/tasks", response_model=ListGenerationTasksResponse)
 def list_generation_tasks(
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -429,6 +518,12 @@ def retry_generation_task(
             asset_select_mode=getattr(task, "asset_select_mode", ""),
             video_title=getattr(task, "video_title", ""),
             resolution=getattr(task, "resolution", ""),
+            is_preview=getattr(task, "is_preview", False),
+            source_task_id=getattr(task, "source_task_id", ""),
+            output_width=getattr(task, "output_width", 1280),
+            output_height=getattr(task, "output_height", 720),
+            cover_url=getattr(task, "cover_url", ""),
+            custom_title=getattr(task, "custom_title", ""),
         )
     )
     try:

apps/api/app/api/routes/templates_editor/_fallback.py

@@ -98,6 +98,15 @@ def _auto_fallback_assign_assets(
     clips_without_asset = [c for c in all_clips if not c.asset_id]
     config_asset_ids = (plan_check.config or {}).get("asset_ids", [])
 
+    logger.info(
+        "模板编辑器自动兜底3 诊断: plan=%s total_clips=%d "
+        "clips_without_asset=%d config_asset_ids=%r",
+        plan_id,
+        len(all_clips),
+        len(clips_without_asset),
+        config_asset_ids[:5] if config_asset_ids else [],
+    )
+
     if clips_without_asset and config_asset_ids:
         logger.info(
             "模板编辑器自动兜底3: plan=%s 为 %d 个无素材片段分配 %d 个指定素材",
@@ -105,11 +114,42 @@ def _auto_fallback_assign_assets(
             len(clips_without_asset),
             len(config_asset_ids),
         )
+        assigned = 0
         for i, clip in enumerate(clips_without_asset):
             asset_idx = i % len(config_asset_ids)
-            svc.assign_asset(clip.id, config_asset_ids[asset_idx])
-        logger.info("模板编辑器自动兜底3: plan=%s 素材分配完成", plan_id)
-        clips_without_asset = []
+            try:
+                svc.assign_asset(clip.id, config_asset_ids[asset_idx])
+                assigned += 1
+            except Exception as exc:
+                logger.error(
+                    "模板编辑器自动兜底3: plan=%s clip=%s 分配素材 %s 失败: %s",
+                    plan_id,
+                    clip.id,
+                    config_asset_ids[asset_idx],
+                    exc,
+                )
+        logger.info(
+            "模板编辑器自动兜底3: plan=%s 素材分配完成 assigned=%d/%d",
+            plan_id,
+            assigned,
+            len(clips_without_asset),
+        )
+        # 重新检查剩余无素材片段
+        all_clips_after = svc.list_clips(plan_id)
+        clips_without_asset = [c for c in all_clips_after if not c.asset_id]
+        if clips_without_asset:
+            logger.warning(
+                "模板编辑器自动兜底3: plan=%s 仍有 %d 个片段无素材",
+                plan_id,
+                len(clips_without_asset),
+            )
+    elif not clips_without_asset:
+        logger.info("模板编辑器自动兜底3: plan=%s 所有片段已有素材，跳过", plan_id)
+    elif not config_asset_ids:
+        logger.info(
+            "模板编辑器自动兜底3: plan=%s config.asset_ids 为空，跳过分配",
+            plan_id,
+        )
 
     return clips_without_asset
 

apps/api/app/api/routes/templates_editor/ai_features.py

@@ -24,6 +24,94 @@ logger = logging.getLogger(__name__)
 router = APIRouter(tags=["Template Editor"])
 
 
+def _build_asset_analyses(
+    asset_ids: list[str],
+    db: Session,
+) -> dict[str, str]:
+    """调用 MediaKit 视频理解，返回 {asset_id: 分析文本}.
+
+    如果 MediaKit 不可用或分析失败，返回空 dict（调用方降级处理）。
+    """
+    if not asset_ids:
+        return {}
+
+    try:
+        from packages.adapters.sqlalchemy_impl.asset_repository import SQLAlchemyAssetRepository
+        from packages.shared.mediakit_client import get_mediakit_client
+        from packages.shared.storage import get_shared_storage_service
+
+        client = get_mediakit_client()
+        if not client.is_available:
+            logger.info("MediaKit 未配置，跳过视频理解分析")
+            return {}
+
+        asset_repo = SQLAlchemyAssetRepository(db)
+        storage_svc = get_shared_storage_service()
+
+        # 查找素材并获取下载 URL（使用并行列表保持索引对应，避免 URL 重复导致映射覆盖）
+        video_urls: list[str] = []
+        valid_asset_ids: list[str] = []
+
+        for aid in asset_ids[:10]:  # MediaKit 单次最多 10 个视频
+            asset = asset_repo.get(aid)
+            if not asset or not asset.storage_key:
+                continue
+            # 只处理视频素材
+            mime = getattr(asset, "mime_type", "")
+            if not mime.startswith("video/"):
+                continue
+            try:
+                url = storage_svc.get_download_url(asset.storage_key)
+                if url:
+                    video_urls.append(url)
+                    valid_asset_ids.append(aid)
+            except Exception as e:
+                logger.warning("获取素材URL失败: asset_id=%s error=%s", aid, str(e))
+
+        if not video_urls:
+            logger.info("无可用视频素材，跳过视频理解分析")
+            return {}
+
+        # 调用 MediaKit 视频理解
+        prompt = (
+            "请简要描述这段视频的主要内容，包括：场景（室内/室外/具体场所）、"
+            "主体（人物/物体/动物）、动作/活动、氛围/情绪、主要色调。"
+            "控制在100字以内。"
+        )
+
+        # 限制轮询参数以适配 API 网关超时（nginx 60s）
+        # 视频理解最多 30s（poll_interval=2s * max_poll_attempts=15）
+        # 剩余 30s 留给 LLM 调用
+        contents = client.analyze_videos(
+            video_urls=video_urls,
+            prompt=prompt,
+            level="Economy",
+            poll_interval=2.0,
+            max_poll_attempts=15,
+        )
+
+        if not contents:
+            logger.warning("MediaKit 视频理解未返回结果")
+            return {}
+
+        # 将结果映射回 asset_id（通过索引对应）
+        analyses: dict[str, str] = {}
+        for i, content in enumerate(contents):
+            if i < len(valid_asset_ids) and content:
+                analyses[valid_asset_ids[i]] = content
+
+        logger.info(
+            "MediaKit 视频理解完成: total=%d analyzed=%d",
+            len(video_urls),
+            len(analyses),
+        )
+        return analyses
+
+    except Exception as e:
+        logger.warning("MediaKit 视频理解异常，将降级到无分析模式: %s", str(e))
+        return {}
+
+
 @router.post("/ai-recommend", response_model=AIRecommendResponse)
 def editor_ai_recommend(
     template_id: str,
@@ -46,12 +134,16 @@ def editor_ai_recommend(
 
     from packages.shared.ai_service import run_ai_recommend
 
+    # 调用 MediaKit 视频理解，获取素材内容分析
+    asset_analyses = _build_asset_analyses(body.asset_ids, db)
+
     result = run_ai_recommend(
         plan_id=plan_id,
         template_id=plan.template_id,
         asset_ids=body.asset_ids,
         editing_mode=body.editing_mode,
         target_duration=body.target_duration,
+        asset_analyses=asset_analyses,
     )
 
     try:

apps/api/app/api/routes/templates_editor/cover.py

@@ -184,6 +184,29 @@ def editor_generate_cover(
     _, plan_svc = services
     plan = plan_svc.get_plan_or_raise(plan_id)
 
+    # 获取第一个视频的下载 URL（用于 MediaKit 抽帧）
+    primary_video_url = None
+    if body.asset_ids and body.cover_type in ("ai_frame", "ai_regenerate"):
+        try:
+            from app.database import get_db_session
+
+            from packages.adapters.sqlalchemy_impl.asset_repository import SQLAlchemyAssetRepository
+            from packages.shared.storage import get_shared_storage_service
+
+            with get_db_session() as session:
+                asset_repo = SQLAlchemyAssetRepository(session)
+                first_asset = asset_repo.get(body.asset_ids[0])
+                if first_asset and first_asset.storage_key:
+                    storage_svc = get_shared_storage_service()
+                    primary_video_url = storage_svc.get_download_url(first_asset.storage_key)
+                    logger.info(
+                        "获取视频URL用于封面生成: asset_id=%s url=%s",
+                        body.asset_ids[0],
+                        primary_video_url[:80] if primary_video_url else None,
+                    )
+        except Exception as e:
+            logger.warning("获取视频URL失败，将使用stub封面: %s", str(e))
+
     from packages.shared.ai_service import run_generate_cover
 
     cover_data = run_generate_cover(
@@ -191,6 +214,7 @@ def editor_generate_cover(
         asset_ids=body.asset_ids,
         cover_type=body.cover_type,
         frame_time=body.frame_time,
+        primary_video_url=primary_video_url,
     )
 
     current_config = dict(plan.config) if plan.config else {}

apps/api/app/api/routes/templates_editor/generation.py

@@ -74,7 +74,7 @@ def generate_editor_draft(
         plan_svc, plan_id, plan_check, clips_without_asset, asset_library_repo, asset_repo
     )
 
-    # 检查是否可生成
+    # 检查是否可生成（含最后防线自动修复 + 诊断日志）
     try:
         can_gen, reason = plan_svc.can_generate(plan_id)
     except ValueError as exc:

apps/api/app/api/routes/voices.py

@@ -5,6 +5,8 @@
 
 from __future__ import annotations
 
+import logging
+import time
 from typing import Literal, Optional
 
 from app.api.routes._helpers import get_user_plan
@@ -42,6 +44,7 @@ from packages.domain.preset_voices import PRESET_VOICES, get_preset_voice_by_id
 from packages.ports.user_repository import UserRepository
 
 router = APIRouter()
+logger = logging.getLogger(__name__)
 
 # 预置音色试听音频缓存（内存缓存，减少重复TTS调用）
 # key: voice_id, value: (audio_url, timestamp)
@@ -51,6 +54,65 @@ PREVIEW_CACHE_TTL = 7 * 24 * 3600  # 7天TTL
 PREVIEW_TEMPLATE = "你好，我是{name}，很高兴认识你。"
 
 
+def _resolve_preset_preview_url(
+    voice_id: str,
+    fallback_url: str,
+    cosyvoice: CosyVoiceService,
+) -> str:
+    """为预置音色获取有效的 preview_url.
+
+    优先从内存缓存读取；缓存失效时调用 CosyVoice 重新合成；
+    合成失败时降级返回硬编码 URL（可能已过期，但不会报错）。
+    """
+    # 检查缓存
+    if voice_id in _preset_preview_cache:
+        audio_url, cached_at = _preset_preview_cache[voice_id]
+        if time.time() - cached_at < PREVIEW_CACHE_TTL:
+            return audio_url
+
+    # 缓存失效，调用 CosyVoice 合成
+    preset = get_preset_voice_by_id(voice_id)
+    if preset is None:
+        return fallback_url
+
+    preview_text = PREVIEW_TEMPLATE.format(name=preset.name)
+    try:
+        result = cosyvoice.synthesize_speech(
+            text=preview_text,
+            voice_id=voice_id,
+            format="mp3",
+            speed=1.0,
+        )
+        audio_url = result.audio_url
+        _preset_preview_cache[voice_id] = (audio_url, time.time())
+        logger.info("Preset voice preview generated: %s", voice_id)
+        return audio_url
+    except Exception as e:
+        logger.warning("Failed to generate preview for %s, using fallback: %s", voice_id, e)
+        return fallback_url
+
+
+def _resolve_all_preset_preview_urls(
+    presets: list,
+    cosyvoice: CosyVoiceService,
+) -> dict[str, str]:
+    """顺序解析所有预置音色的 preview_url.
+
+    采用顺序调用（而非并行）以避免触发 DashScope API 速率限制。
+    首次调用后结果缓存 7 天，后续请求直接命中缓存。
+
+    Returns:
+        voice_id -> preview_url 映射
+    """
+    result_map: dict[str, str] = {}
+    for p in presets:
+        try:
+            result_map[p.voice_id] = _resolve_preset_preview_url(p.voice_id, p.preview_url, cosyvoice)
+        except Exception:
+            result_map[p.voice_id] = p.preview_url
+    return result_map
+
+
 def _get_voice_repository(session: Session = Depends(get_db_session)) -> SQLAlchemyVoiceLibraryRepository:
     return SQLAlchemyVoiceLibraryRepository(session)
 
@@ -118,8 +180,16 @@ def _to_unified_response(item, profile_id_map: dict | None = None, sign_url=None
     )
 
 
-def _preset_to_unified_response(preset) -> UnifiedVoiceItemResponse:
-    """将预置音色转换为统一响应格式。"""
+def _preset_to_unified_response(preset, preview_url_map: dict[str, str] | None = None) -> UnifiedVoiceItemResponse:
+    """将预置音色转换为统一响应格式。
+
+    Args:
+        preset: 预置音色对象
+        preview_url_map: voice_id -> preview_url 动态映射，优先使用
+    """
+    preview_url = preset.preview_url
+    if preview_url_map and preset.voice_id in preview_url_map:
+        preview_url = preview_url_map[preset.voice_id]
     return UnifiedVoiceItemResponse(
         id=preset.voice_id,
         type="preset",
@@ -129,7 +199,7 @@ def _preset_to_unified_response(preset) -> UnifiedVoiceItemResponse:
         language=preset.language,
         voice_id=preset.voice_id,
         voice_provider="cosyvoice",
-        preview_url=preset.preview_url,
+        preview_url=preview_url,
         tags=preset.tags or [],
     )
 
@@ -179,6 +249,7 @@ def list_voices_unified(
     voice_repository: SQLAlchemyVoiceLibraryRepository = Depends(_get_voice_repository),
     clone_profile_repository: SQLAlchemyVoiceCloneProfileRepository = Depends(_get_clone_profile_repository),
     sign_url=Depends(get_audio_url_signer),
+    cosyvoice: CosyVoiceService = Depends(get_cosyvoice_service),
 ) -> UnifiedVoiceListResponse:
     """获取配音列表（预置音色 + 用户克隆音色）。
 
@@ -194,9 +265,10 @@ def list_voices_unified(
     has_preset = type is None or type == "preset"
     has_clone = type is None or type == "clone"
 
-    # 获取预置音色
+    # 获取预置音色（动态生成 preview_url）
     if has_preset:
-        preset_items = [_preset_to_unified_response(p) for p in PRESET_VOICES]
+        preview_url_map = _resolve_all_preset_preview_urls(PRESET_VOICES, cosyvoice)
+        preset_items = [_preset_to_unified_response(p, preview_url_map) for p in PRESET_VOICES]
         preset_count = len(preset_items)
 
     # 获取克隆音色（从 voice_clone_profile 读取，ready 状态的克隆音色）
@@ -243,11 +315,15 @@ def list_voices_unified(
 
 
 @router.get("/presets", response_model=PresetVoiceListResponse)
-def list_preset_voices() -> PresetVoiceListResponse:
+def list_preset_voices(
+    cosyvoice: CosyVoiceService = Depends(get_cosyvoice_service),
+) -> PresetVoiceListResponse:
     """获取预置音色列表。
 
     不需要认证，返回所有系统预置的 CosyVoice 音色。
+    preview_url 通过 CosyVoice 动态生成，不依赖硬编码的过期 URL。
     """
+    preview_url_map = _resolve_all_preset_preview_urls(PRESET_VOICES, cosyvoice)
     items = [
         PresetVoiceItemResponse(
             voice_id=p.voice_id,
@@ -255,7 +331,7 @@ def list_preset_voices() -> PresetVoiceListResponse:
             description=p.description,
             gender=p.gender,
             language=p.language,
-            preview_url=p.preview_url,
+            preview_url=preview_url_map.get(p.voice_id, p.preview_url),
             tags=p.tags or [],
         )
         for p in PRESET_VOICES
@@ -275,8 +351,6 @@ def get_preset_voice_preview(
     - 相同 voice_id 重复调用直接返回缓存的音频URL
     - 可传入自定义 text 参数试听不同文本
     """
-    import time
-
     preset = get_preset_voice_by_id(voice_id)
     if preset is None:
         raise HTTPException(status_code=404, detail=f"预置音色不存在: {voice_id}")

apps/api/app/schemas/asset.py

@@ -2,7 +2,7 @@ from pydantic import BaseModel, Field
 
 
 class CreateAssetRequest(BaseModel):
-    project_id: str = Field(..., min_length=1)
+    project_id: str | None = Field(default=None, description="可选，不传时从 library.project_id 自动推导")
     library_id: str = Field(..., min_length=1)
     name: str = Field(..., min_length=1, max_length=100)
     storage_key: str = Field(..., min_length=1, max_length=255)
@@ -101,3 +101,30 @@ class ListAssetsResponse(BaseModel):
     total: int = Field(default=0, ge=0)
     skip: int = Field(default=0, ge=0)
     limit: int = Field(default=100, ge=1)
+
+
+class SmartMatchRequest(BaseModel):
+    """智能选素材请求。"""
+
+    library_id: str = Field(..., min_length=1, description="素材库 ID")
+    limit: int | None = Field(default=None, ge=1, le=200, description="最大返回数量，不传则返回全部匹配素材")
+    kind: str | None = Field(
+        default=None,
+        pattern="^(video|image|audio)$",
+        description="按文件类型过滤，不传则返回所有类型",
+    )
+
+
+class SmartMatchItem(BaseModel):
+    """智能选素材结果条目。"""
+
+    asset: AssetResponse
+    score: float = Field(..., ge=0, le=100, description="综合得分 0-100")
+    breakdown: dict[str, float] = Field(default_factory=dict, description="各维度得分明细")
+
+
+class SmartMatchResponse(BaseModel):
+    """智能选素材响应。"""
+
+    items: list[SmartMatchItem]
+    total_candidates: int = Field(default=0, ge=0, description="参与评分的候选素材总数")

apps/api/app/schemas/generation_task.py

@@ -1,8 +1,18 @@
 import json
+from datetime import datetime
 
 from pydantic import BaseModel, Field, field_validator, model_validator
 
 
+class ConfirmGenerationRequest(BaseModel):
+    """确认生成请求体 — 基于预览任务创建正式生成任务"""
+
+    output_width: int = Field(default=1080, description="输出视频宽度")
+    output_height: int = Field(default=1920, description="输出视频高度")
+    cover_url: str = Field(default="", description="自定义封面图片 URL")
+    custom_title: str = Field(default="", description="自定义视频标题")
+
+
 class CreateGenerationTaskRequest(BaseModel):
     """创建生成任务请求。
 
@@ -56,6 +66,13 @@ class CreateGenerationTaskRequest(BaseModel):
         default_factory=dict,
         description="自定义BGM配置，覆盖模板BGM设置。支持 enabled/source/asset_id/preset_id/audio_url/volume 等字段",
     )
+    # ── 预览 / 确认生成 ──
+    is_preview: bool = Field(default=False, description="是否为预览任务")
+    source_task_id: str = Field(default="", description="来源预览任务 ID（确认生成时传入）")
+    output_width: int = Field(default=1280, description="输出视频宽度")
+    output_height: int = Field(default=720, description="输出视频高度")
+    cover_url: str = Field(default="", description="封面图片 URL")
+    custom_title: str = Field(default="", description="自定义视频标题")
 
     @model_validator(mode="after")
     def _check_at_least_one_mode(self) -> "CreateGenerationTaskRequest":
@@ -86,6 +103,12 @@ class GenerationTaskResponse(BaseModel):
     video_title: str = ""
     resolution: str = ""
     bgm_config: dict = Field(default_factory=dict)
+    is_preview: bool = False
+    source_task_id: str = ""
+    output_width: int = 1280
+    output_height: int = 720
+    cover_url: str = ""
+    custom_title: str = ""
     status: str
     progress: float
     result_count: int
@@ -122,3 +145,68 @@ class ListGenerationTasksResponse(BaseModel):
     """用户级生成任务列表响应（跨 project）。"""
 
     items: list[GenerationTaskResponse]
+
+
+# ── 预览生成（Phase 1） ───────────────────────────────────────────────────────
+
+
+class CreatePreviewGenerationTaskRequest(BaseModel):
+    """创建预览生成任务请求。
+
+    仅支持模板模式：template_id + asset_ids 等素材 ID 列表。
+    预览为完整时长低清版（480p + 低码率）。
+    """
+
+    template_id: str
+    asset_ids: list[str] = Field(default_factory=list)
+    title_ids: list[str] = Field(default_factory=list)
+    voice_ids: list[str] = Field(default_factory=list)
+    video_title: str = Field(default="", description="生成视频的标题/名称，为空则使用默认命名")
+    duration: float = Field(default=0.0, ge=0, description="期望视频时长（秒），0 表示由模板决定")
+    video_ratio: str = Field(default="", description="视频比例，如 16:9 / 9:16，为空使用模板默认")
+    bgm_config: dict = Field(
+        default_factory=dict,
+        description="自定义BGM配置，覆盖模板BGM设置。支持 enabled/source/asset_id/preset_id/audio_url/volume 等字段",
+    )
+    preview_count: int = Field(
+        default=1,
+        ge=1,
+        le=10,
+        description="预览视频生成数量，范围 1-10，默认 1",
+    )
+
+    @model_validator(mode="after")
+    def _check_template_id(self) -> "CreatePreviewGenerationTaskRequest":
+        if not self.template_id.strip():
+            raise ValueError("template_id 不能为空")
+        return self
+
+    @model_validator(mode="after")
+    def _check_asset_ids(self) -> "CreatePreviewGenerationTaskRequest":
+        if not self.asset_ids and not self.title_ids and not self.voice_ids:
+            raise ValueError("asset_ids/title_ids/voice_ids 至少需要提供一个")
+        return self
+
+
+class PreviewGenerationTaskResponse(BaseModel):
+    """预览生成任务响应。
+
+    包含任务状态、进度、分辨率、生成结果 URL 等关键字段。
+    """
+
+    task_id: str
+    status: str
+    progress: float
+    is_preview: bool = True
+    resolution: str = ""
+    video_url: str = ""
+    duration: float = 0.0
+    file_size: int = 0
+    clip_count: int = 0
+    transition_count: int = 0
+    material_usage: dict = Field(default_factory=dict)
+    error_message: str = ""
+    created_at: datetime | None = None
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    generate_duration: float = 0.0

apps/api/app/services/edit_plan_service.py

@@ -571,6 +571,10 @@ class EditPlanService:
     def can_generate(self, plan_id: str) -> tuple[bool, str]:
         """检查是否可以触发渲染
 
+        包含最后一道防线的自动修复：
+        - 如果 clips 存在但都没有 asset_id，且 config.asset_ids 非空，
+          直接在内部执行素材分配，不再依赖前置 fallback 链路。
+
         Returns:
             tuple: (can_generate, reason)
         """
@@ -585,10 +589,69 @@ class EditPlanService:
         if not clips:
             return False, "请先添加片段后再生成视频"
 
+        # 检查是否至少有一个片段分配了素材
+        has_asset = any(c.asset_id for c in clips)
+        config_asset_ids_count = len((plan.config or {}).get("asset_ids", []))
+        clips_with_asset_count = sum(1 for c in clips if c.asset_id)
+        logger.info(
+            "can_generate 诊断: plan=%s status=%s total_clips=%d " "clips_with_asset=%d config_asset_ids_count=%d",
+            plan_id,
+            plan.status,
+            len(clips),
+            clips_with_asset_count,
+            config_asset_ids_count,
+        )
+        if not has_asset:
+            # ── 最后防线：自动从 config.asset_ids 分配素材 ──
+            config_asset_ids = (plan.config or {}).get("asset_ids", [])
+            if config_asset_ids:
+                logger.warning(
+                    "can_generate 最后防线触发: plan=%s clips=%d 均无素材，" "从 config.asset_ids(%d个) 自动分配",
+                    plan_id,
+                    len(clips),
+                    len(config_asset_ids),
+                )
+                clips_without_asset = [c for c in clips if not c.asset_id]
+                assigned_count = 0
+                for i, clip in enumerate(clips_without_asset):
+                    asset_idx = i % len(config_asset_ids)
+                    try:
+                        self.assign_asset(clip.id, config_asset_ids[asset_idx])
+                        assigned_count += 1
+                    except Exception as exc:
+                        logger.warning(
+                            "can_generate 最后防线: plan=%s clip=%s 分配素材 %s 失败: %s",
+                            plan_id,
+                            clip.id,
+                            config_asset_ids[asset_idx],
+                            exc,
+                        )
+                logger.info(
+                    "can_generate 最后防线: plan=%s 已为 %d/%d 个片段分配素材",
+                    plan_id,
+                    assigned_count,
+                    len(clips_without_asset),
+                )
+                # 重新加载 clips 验证分配结果
+                clips = self._clip_repo.list_by_plan(plan_id)
+                if not any(c.asset_id for c in clips):
+                    return False, "没有可渲染的就绪片段，自动修复后仍未分配素材"
+            else:
+                logger.warning(
+                    "can_generate 失败: plan=%s clips=%d 均无素材，" "且 config.asset_ids 为空，无法自动修复",
+                    plan_id,
+                    len(clips),
+                )
+                return False, "没有可渲染的就绪片段，请确保已选择素材"
+
         return True, ""
 
     def mark_clips_ready(self, plan_id: str) -> int:
-        """将所有 pending 状态的片段标记为 ready
+        """将已分配素材的 pending 片段标记为 ready
+
+        只标记同时满足以下条件的片段：
+        - status == PENDING
+        - asset_id 非空（已分配素材）
 
         Returns:
             int: 标记的片段数量
@@ -599,10 +662,16 @@ class EditPlanService:
         )
         count = 0
         for clip in clips:
-            clip.mark_ready()
-            self._clip_repo.update(clip)
-            count += 1
-        logger.info("标记片段就绪: plan_id=%s count=%d", plan_id, count)
+            if clip.asset_id:
+                clip.mark_ready()
+                self._clip_repo.update(clip)
+                count += 1
+        logger.info(
+            "标记片段就绪: plan_id=%s marked=%d total_pending=%d",
+            plan_id,
+            count,
+            len(clips),
+        )
         return count
 
     def update_plan_config(self, plan_id: str, config_updates: Dict[str, Any]) -> EditPlan:

apps/api/app/services/plan_generator_service.py

@@ -49,9 +49,10 @@ class PlanGeneratorService:
     基于模板 + 素材，自动生成 EditPlan 及 EditPlanClip 列表。
     """
 
-    def __init__(self, db: Session) -> None:
+    def __init__(self, db: Session, asset_repo=None) -> None:
         self._plan_repo = SQLAlchemyEditPlanRepository(db)
         self._clip_repo = SQLAlchemyEditPlanClipRepository(db)
+        self._asset_repo = asset_repo
 
     # ── 公开接口 ─────────────────────────────────────────────────────────────
 
@@ -64,6 +65,7 @@ class PlanGeneratorService:
         project_id: str = "",
         created_by_user_id: str = "",
         name: str = "",
+        random_preview: bool = False,
     ) -> dict[str, Any]:
         """基于模板+素材生成剪辑计划
 
@@ -74,6 +76,7 @@ class PlanGeneratorService:
             project_id: 所属项目 ID
             created_by_user_id: 创建者用户 ID
             name: 计划名称（为空则自动取模板名）
+            random_preview: 是否启用随机预览模式（随机选素材+随机截取片段）
 
         Returns:
             dict: {"plan": EditPlan, "clips": List[EditPlanClip]}
@@ -115,7 +118,17 @@ class PlanGeneratorService:
 
         # 4. 按 editing_mode 分配素材
         if asset_ids:
-            self._distribute_assets(clips, asset_ids, editing_mode)
+            # 如果是随机预览模式，获取素材时长信息
+            asset_durations = None
+            if random_preview and self._asset_repo:
+                asset_durations = self._fetch_asset_durations(asset_ids)
+            self._distribute_assets(
+                clips,
+                asset_ids,
+                editing_mode,
+                random_selection=random_preview,
+                asset_durations=asset_durations,
+            )
 
         # 5. 持久化所有 clips 并计算总时长
         created_clips: List[EditPlanClip] = []
@@ -199,9 +212,34 @@ class PlanGeneratorService:
         clips: List[EditPlanClip],
         asset_ids: List[str],
         editing_mode: str,
+        *,
+        random_selection: bool = False,
+        asset_durations: dict[str, float] | None = None,
     ) -> None:
         """按 editing_mode 将素材分配到 clips（就地修改，未持久化）.
 
         委托给 plan_generator_utils.distribute_assets 纯函数。
         """
-        distribute_assets(clips, asset_ids, editing_mode)
+        distribute_assets(
+            clips,
+            asset_ids,
+            editing_mode,
+            random_selection=random_selection,
+            asset_durations=asset_durations,
+        )
+
+    def _fetch_asset_durations(self, asset_ids: List[str]) -> dict[str, float]:
+        """从数据库获取素材时长信息.
+
+        Args:
+            asset_ids: 素材 ID 列表
+
+        Returns:
+            dict: 素材 ID -> 时长（秒）映射
+        """
+        durations: dict[str, float] = {}
+        for asset_id in asset_ids:
+            asset = self._asset_repo.get(asset_id)
+            if asset and hasattr(asset, "duration"):
+                durations[asset_id] = float(asset.duration or 0.0)
+        return durations

apps/api/app/services/smart_asset_selector.py

@@ -1,164 +0,0 @@
-"""SmartAssetSelector — 智能素材选择服务.
-
-根据多维度评分从素材库中自动选择最优视频素材，
-用于一键生成等需要自动选取素材的场景。
-
-评分维度（加权求和，总分 0-1）：
-  - 质量分（quality_score）：权重 0.5 — 来自人工或AI的质量评分
-  - 分辨率适配：权重 0.2 — 分辨率越接近 1080p 得分越高
-  - 时长合理性：权重 0.2 — 3-30 秒区间最佳，过短/过长扣分
-  - 码率质量：权重 0.1 — 用文件大小/时长估算，码率适中得分高
-
-特性：
-  - 最低质量分门槛：自动过滤低质量素材
-  - 时长多样性：保证选出的素材时长分布均匀（短/中/长各占一定比例）
-  - 兼容全部模式：素材库模式和项目模式都可用
-
-纯逻辑部分已抽离到 packages.domain.asset_scoring。
-"""
-
-from __future__ import annotations
-
-import logging
-
-from packages.domain.asset_scoring import MEDIUM_BUCKET_MAX as _MEDIUM_BUCKET_MAX  # noqa: F401 - re-export for tests
-from packages.domain.asset_scoring import SHORT_BUCKET_MAX as _SHORT_BUCKET_MAX  # noqa: F401 - re-export for tests
-from packages.domain.asset_scoring import (
-    AssetScoreDetail,
-    SmartSelectResult,
-    diverse_selection,
-    filter_candidates,
-    score_asset_detail,
-)
-
-logger = logging.getLogger(__name__)
-
-
-class SmartAssetSelector:
-    """智能素材选择器.
-
-    从一组素材中按综合评分选择最优的 N 个，
-    同时保证时长分布的多样性。
-    """
-
-    def __init__(
-        self,
-        min_quality_score: float = 30.0,
-        target_width: int = 1920,
-        target_height: int = 1080,
-    ):
-        self.min_quality_score = min_quality_score
-        self.target_width = target_width
-        self.target_height = target_height
-
-    # ── 公开方法 ──────────────────────────────────────────────────────────────
-
-    def select(
-        self,
-        assets: list,
-        count: int = 0,
-        *,
-        ensure_diversity: bool = True,
-    ) -> SmartSelectResult:
-        """从素材列表中智能选择最优素材.
-
-        Args:
-            assets: Asset 实体列表（需要有 id/quality_score/width/height/duration/file_size 属性）
-            count: 选取数量，0 表示全部符合条件的
-            ensure_diversity: 是否保证时长多样性（默认开启）
-
-        Returns:
-            SmartSelectResult 选择结果
-        """
-        # 1. 过滤：只保留 ready 状态的视频素材 + 最低质量分门槛
-        candidates, filtered_out = filter_candidates(assets, self.min_quality_score)
-
-        if not candidates:
-            return SmartSelectResult(
-                selected_ids=[],
-                total_candidates=0,
-                filtered_out=filtered_out,
-                avg_score=0.0,
-                details=[],
-            )
-
-        # 2. 对每个候选素材评分
-        scored: list[AssetScoreDetail] = []
-        for asset in candidates:
-            detail = score_asset_detail(
-                asset_id=asset.id,
-                quality=getattr(asset, "quality_score", None),
-                width=getattr(asset, "width", None),
-                height=getattr(asset, "height", None),
-                duration=getattr(asset, "duration", None),
-                file_size=getattr(asset, "file_size", 0) or 0,
-                target_width=self.target_width,
-                target_height=self.target_height,
-            )
-            scored.append(detail)
-
-        # 3. 按总分降序排列
-        scored.sort(key=lambda d: d.total_score, reverse=True)
-
-        # 4. 多样性选择（如果需要且数量有限制）
-        if ensure_diversity and count > 0 and len(scored) > count:
-            selected = diverse_selection(scored, count)
-        else:
-            # 无数量限制或不要求多样性，直接按排名取
-            selected = scored if count <= 0 else scored[:count]
-
-        avg_score = sum(d.total_score for d in selected) / len(selected) if selected else 0.0
-
-        result = SmartSelectResult(
-            selected_ids=[d.asset_id for d in selected],
-            total_candidates=len(candidates),
-            filtered_out=filtered_out,
-            avg_score=avg_score,
-            details=selected,
-        )
-
-        logger.info(
-            "智能素材选择完成: 候选=%d, 过滤=%d, 选中=%d, 平均分=%.3f",
-            result.total_candidates,
-            result.filtered_out,
-            len(result.selected_ids),
-            result.avg_score,
-        )
-        return result
-
-    # ── 向后兼容：私有方法别名（委托给 asset_scoring 纯函数） ────────────────
-
-    def _score_asset(self, asset) -> AssetScoreDetail:
-        """对单个素材进行多维度评分（向后兼容）."""
-        return score_asset_detail(
-            asset_id=asset.id,
-            quality=getattr(asset, "quality_score", None),
-            width=getattr(asset, "width", None),
-            height=getattr(asset, "height", None),
-            duration=getattr(asset, "duration", None),
-            file_size=getattr(asset, "file_size", 0) or 0,
-            target_width=self.target_width,
-            target_height=self.target_height,
-        )
-
-    def _score_resolution(self, width: int | None, height: int | None) -> float:
-        """分辨率评分（向后兼容）."""
-        from packages.domain.asset_scoring import score_resolution
-
-        return score_resolution(width, height, self.target_width, self.target_height)
-
-    def _score_duration(self, duration: float | None) -> float:
-        """时长评分（向后兼容）."""
-        from packages.domain.asset_scoring import score_duration
-
-        return score_duration(duration)
-
-    def _score_bitrate(self, file_size: int, duration: float | None) -> float:
-        """码率评分（向后兼容）."""
-        from packages.domain.asset_scoring import score_bitrate
-
-        return score_bitrate(file_size, duration)
-
-    def _diverse_selection(self, scored: list[AssetScoreDetail], count: int) -> list[AssetScoreDetail]:
-        """多样性选择（向后兼容）."""
-        return diverse_selection(scored, count)

apps/web/e2e/core-generation.spec.ts

@@ -196,24 +196,33 @@ test.describe("Core generation flow", () => {
     await materialLabel.locator("input[type='checkbox']").check()
     await page.getByRole("button", { name: "下一步" }).click()
 
-    // Step 3: preview (纯展示页，AI 智能匹配预览)
-    await expect(page.getByRole("heading", { name: /生成预览/ })).toBeVisible()
+    // Step 3: voice (可选步骤，新注册用户无配音素材，直接跳过)
+    await expect(page.getByRole("heading", { name: /选择配音/ })).toBeVisible({ timeout: 15000 })
     await page.getByRole("button", { name: "下一步" }).click()
 
-    // Step 4: title
-    await expect(page.getByRole("heading", { name: /选择标题/ })).toBeVisible()
+    // Step 4: preview — 需要先生成预览视频，才能进入下一步
+    await expect(page.getByRole("heading", { name: /生成预览/ })).toBeVisible({ timeout: 15000 })
+    // 点击"生成预览"按钮触发预览生成
+    await page.locator(".xx-preview-generate-btn").click()
+    // 等待预览生成完成（后端渲染，可能需要较长时间）
+    await expect(page.getByText("预览生成成功")).toBeVisible({ timeout: 120_000 })
+    await page.getByRole("button", { name: "下一步" }).click()
+
+    // Step 5: title
+    await expect(page.getByRole("heading", { name: /选择标题/ })).toBeVisible({ timeout: 15000 })
+    // 如果 AI 自动选择标题模式开启，先切换到手动模式以显示输入框
+    const aiSwitch = page.locator(".xx-title-ai-toggle .xx-switch.active")
+    if (await aiSwitch.isVisible({ timeout: 2000 }).catch(() => false)) {
+      await aiSwitch.click()
+      // 等待输入框出现（条件渲染，需要等待 DOM 更新）
+      await expect(page.getByPlaceholder("输入或从标题库选择…")).toBeVisible({ timeout: 5000 })
+    }
     const titleText = `E2E Test ${suffix}`
-    await page.getByPlaceholder("输入自定义标题…").fill(titleText)
-    await page.getByRole("button", { name: "下一步" }).click()
-
-    // Step 5: voice
-    await expect(page.getByRole("heading", { name: /选择配音/ })).toBeVisible()
-    const firstVoiceCard = page.locator(".xx-voice-choice-item").first()
-    await firstVoiceCard.click()
+    await page.getByPlaceholder("输入或从标题库选择…").fill(titleText)
     await page.getByRole("button", { name: "下一步" }).click()
 
     // Step 6: cover (默认 AI 智能选帧模式，直接下一步)
-    await expect(page.getByRole("heading", { name: /选择封面/ })).toBeVisible()
+    await expect(page.getByRole("heading", { name: /选择封面/ })).toBeVisible({ timeout: 15000 })
     await page.getByRole("button", { name: "下一步" }).click()
 
     // Step 7: confirm and generate

apps/web/package-lock.json

@@ -1847,7 +1847,7 @@
     },
     "node_modules/@testing-library/dom": {
       "version": "10.4.1",
-      "resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz",
+      "resolved": "https://registry.npmmirror.com/@testing-library/dom/-/dom-10.4.1.tgz",
       "integrity": "sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==",
       "dev": true,
       "license": "MIT",
@@ -1937,7 +1937,7 @@
     },
     "node_modules/@types/aria-query": {
       "version": "5.0.4",
-      "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz",
+      "resolved": "https://registry.npmmirror.com/@types/aria-query/-/aria-query-5.0.4.tgz",
       "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==",
       "dev": true,
       "license": "MIT",
@@ -3112,7 +3112,7 @@
     },
     "node_modules/dom-accessibility-api": {
       "version": "0.5.16",
-      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz",
+      "resolved": "https://registry.npmmirror.com/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz",
       "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==",
       "dev": true,
       "license": "MIT",
@@ -4028,18 +4028,6 @@
         "node": ">= 4"
       }
     },
-    "node_modules/immer": {
-      "version": "10.2.0",
-      "resolved": "https://registry.npmjs.org/immer/-/immer-10.2.0.tgz",
-      "integrity": "sha512-d/+XTN3zfODyjr89gM3mPq1WNX2B8pYsu7eORitdwyA2sBubnTl3laYlBk4sXY5FUa5qTZGBDPJICVbvqzjlbw==",
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/immer"
-      }
-    },
     "node_modules/import-fresh": {
       "version": "3.3.1",
       "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.1.tgz",
@@ -4468,7 +4456,7 @@
     },
     "node_modules/lz-string": {
       "version": "1.5.0",
-      "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz",
+      "resolved": "https://registry.npmmirror.com/lz-string/-/lz-string-1.5.0.tgz",
       "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==",
       "dev": true,
       "license": "MIT",
@@ -5010,7 +4998,7 @@
     },
     "node_modules/pretty-format": {
       "version": "27.5.1",
-      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-27.5.1.tgz",
+      "resolved": "https://registry.npmmirror.com/pretty-format/-/pretty-format-27.5.1.tgz",
       "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==",
       "dev": true,
       "license": "MIT",
@@ -5026,7 +5014,7 @@
     },
     "node_modules/pretty-format/node_modules/ansi-styles": {
       "version": "5.2.0",
-      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz",
+      "resolved": "https://registry.npmmirror.com/ansi-styles/-/ansi-styles-5.2.0.tgz",
       "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==",
       "dev": true,
       "license": "MIT",
@@ -5038,14 +5026,6 @@
         "url": "https://github.com/chalk/ansi-styles?sponsor=1"
       }
     },
-    "node_modules/pretty-format/node_modules/react-is": {
-      "version": "17.0.2",
-      "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz",
-      "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==",
-      "dev": true,
-      "license": "MIT",
-      "peer": true
-    },
     "node_modules/proxy-from-env": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-2.1.0.tgz",
@@ -5743,6 +5723,14 @@
         "react": "^18.3.1"
       }
     },
+    "node_modules/react-is": {
+      "version": "17.0.2",
+      "resolved": "https://registry.npmmirror.com/react-is/-/react-is-17.0.2.tgz",
+      "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true
+    },
     "node_modules/react-refresh": {
       "version": "0.17.0",
       "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.17.0.tgz",

apps/web/src/api/assets/assets.ts

@@ -49,6 +49,17 @@ export const getAssetsByKind = async (
   return response.data.items || []
 }
 
+/**
+ * 智能匹配素材（后端 AI 选素材）
+ * 调用后端 smart-match 端点，由后端根据素材库内容智能选择素材
+ */
+export const smartMatchAssets = async (libraryId: string): Promise<{ items: AssetItem[] }> => {
+  const response = await apiClient.post("/assets/smart-match", {
+    library_id: libraryId,
+  })
+  return response.data
+}
+
 /** 创建素材（上传文件后调用，附带 metadata） */
 export const createAsset = async (data: {
   library_id: string

apps/web/src/api/assets/index.ts

@@ -29,10 +29,11 @@ export {
   deleteAssetLibrary,
 } from "./libraries"
 
-// 素材 CRUD
+// 素材 CRUD + 智能匹配
 export {
   getAssets,
   getAssetsByKind,
+  smartMatchAssets,
   createAsset,
   updateAsset,
   updateAssetReviewStatus,

apps/web/src/api/client.ts

@@ -57,7 +57,21 @@ apiClient.interceptors.response.use(
     }
 
     // 401 → 尝试刷新 Token
-    if (error.response?.status === 401 && originalRequest && !originalRequest._retry) {
+    // 排除 auth 端点：登录/注册/找回密码的 401 是正常业务响应（如密码错误），
+    // 不应触发 token 刷新或登出跳转，走后面的错误提示逻辑即可
+    const requestUrl = originalRequest?.url || ""
+    const isAuthEndpoint =
+      requestUrl.includes("/auth/login") ||
+      requestUrl.includes("/auth/register") ||
+      requestUrl.includes("/auth/forgot-password") ||
+      requestUrl.includes("/auth/reset-password")
+
+    if (
+      error.response?.status === 401 &&
+      originalRequest &&
+      !originalRequest._retry &&
+      !isAuthEndpoint
+    ) {
       const refreshToken = useAuthStore.getState().refreshToken
 
       // 无 refresh_token → 直接登出

apps/web/src/api/template-editor/mediaAssets.ts

@@ -18,6 +18,7 @@ const mapAssetToMediaAsset = (asset: AssetItem): MediaAsset => {
     id: asset.id,
     name: asset.name,
     type: inferMediaType(asset.mime_type || ""),
+    source_url: asset.file_url,
     thumbnail_url: asset.thumbnail_url,
     duration: asset.duration ?? metaDuration,
     size: asset.file_size ?? undefined,

apps/web/src/api/template-editor/types.ts

@@ -424,6 +424,8 @@ export interface MediaAsset {
   id: string
   name: string
   type: "video" | "image" | "audio"
+  /** 源文件 URL（视频/原图），用于悬浮预览播放 */
+  source_url?: string
   /** 缩略图 URL */
   thumbnail_url?: string
   /** 时长（秒），仅 video/audio */

apps/web/src/api/voice-clone/clones.ts

@@ -11,6 +11,7 @@ import type {
   VoiceCloneListParams,
   ListVoiceCloneResponse,
   VoiceCloneStatusResponse,
+  VoiceClonePreviewResponse,
 } from "./types"
 
 /** 获取克隆音色列表（返回前端兼容数组） */
@@ -85,3 +86,17 @@ export const retryVoiceClone = async (id: string): Promise<VoiceCloneProfile> =>
   const response = await apiClient.post<VoiceCloneProfile>(`/voice-clones/${id}/retry`)
   return response.data
 }
+
+/** 获取克隆音色试听音频（实时 TTS 合成） */
+export const getVoiceClonePreview = async (
+  cloneId: string,
+  text?: string,
+): Promise<VoiceClonePreviewResponse> => {
+  const searchParams = new URLSearchParams()
+  if (text) searchParams.set("text", text)
+  const qs = searchParams.toString()
+  const response = await apiClient.get<VoiceClonePreviewResponse>(
+    `/voice-clones/${cloneId}/preview${qs ? `?${qs}` : ""}`,
+  )
+  return response.data
+}

apps/web/src/api/voice-clone/index.ts

@@ -14,6 +14,7 @@ export type {
   VoiceCloneStatusResponse,
   CreateVoiceCloneRequestFull,
   VoiceCloneListParams,
+  VoiceClonePreviewResponse,
 } from "./types"
 
 // 工具函数
@@ -29,4 +30,5 @@ export {
   updateVoiceClone,
   getVoiceCloneStatus,
   retryVoiceClone,
+  getVoiceClonePreview,
 } from "./clones"

apps/web/src/api/voice-clone/types.ts

@@ -90,3 +90,24 @@ export interface VoiceCloneListParams {
   skip?: number
   limit?: number
 }
+
+/** 克隆音色试听响应 */
+export interface VoiceClonePreviewResponse {
+  clone_id: string
+  /** 音色克隆档案 ID */
+
+  voice_id: string
+  /** CosyVoice 音色 ID */
+
+  audio_url: string
+  /** 试听音频 URL */
+
+  text: string
+  /** 试听文本 */
+
+  duration: number
+  /** 音频时长（秒） */
+
+  file_size: number
+  /** 文件大小（字节） */
+}

apps/web/src/components/asset-selector/AssetSelector.css

@@ -456,7 +456,8 @@
   margin-bottom: 8px;
 }
 
-.as-preview-overlay-thumb img {
+.as-preview-overlay-thumb img,
+.as-preview-overlay-thumb video {
   width: 100%;
   height: 100%;
   object-fit: cover;

apps/web/src/components/asset-selector/PreviewOverlay.tsx

@@ -12,7 +12,16 @@ const PreviewOverlay: React.FC<PreviewOverlayProps> = ({ asset, position }) => {
   return (
     <div className="as-preview-overlay" style={{ left: position.x, top: position.y }}>
       <div className="as-preview-overlay-thumb">
-        {asset.thumbnail_url ? (
+        {asset.type === "video" && asset.source_url ? (
+          <video
+            src={asset.source_url}
+            autoPlay
+            muted
+            loop
+            playsInline
+            poster={asset.thumbnail_url}
+          />
+        ) : asset.thumbnail_url ? (
           <img src={asset.thumbnail_url} alt={asset.name} />
         ) : (
           <span className="as-preview-overlay-thumb-icon">{MATERIAL_TYPE_ICONS[asset.type]}</span>

apps/web/src/hooks/useAuth.ts

@@ -31,8 +31,8 @@ export const useLogin = () => {
     const user = await authApi.getCurrentUser()
     setAuth(user, data.access_token, refreshToken)
 
-    // 跳转到登录前页面或首页
-    const redirect = localStorage.getItem("login_redirect") || "/"
+    // 跳转到登录前页面或仪表盘（与 Login.tsx onFinish 保持一致）
+    const redirect = localStorage.getItem("login_redirect") || "/app/dashboard"
     localStorage.removeItem("login_redirect")
     navigate(redirect, { replace: true })
     return data

apps/web/src/pages/editing-planner/EditingPlanner.css

@@ -6408,4 +6408,3 @@
   padding: 16px;
   text-align: center;
 }
-

apps/web/src/pages/editing-planner/components/TtsPanel/components/VoiceSelector.tsx

@@ -1,5 +1,6 @@
 import React, { useState } from "react"
 import type { UnifiedVoiceItem } from "@/api/voices"
+import { LoadingOutlined } from "@ant-design/icons"
 
 export interface VoiceSelectorProps {
   presetVoices: UnifiedVoiceItem[]
@@ -7,8 +8,9 @@ export interface VoiceSelectorProps {
   selectedVoiceId: string
   loading: boolean
   playingVoiceId: string | null
+  loadingSampleVoiceId: string | null
   onSelect: (voiceId: string) => void
-  onPlaySample: (voiceId: string, previewUrl: string | null) => void
+  onPlaySample: (voice: UnifiedVoiceItem) => void
 }
 
 type VoiceTab = "preset" | "clone"
@@ -25,6 +27,7 @@ export const VoiceSelector: React.FC<VoiceSelectorProps> = ({
   selectedVoiceId,
   loading,
   playingVoiceId,
+  loadingSampleVoiceId,
   onSelect,
   onPlaySample,
 }) => {
@@ -70,6 +73,7 @@ export const VoiceSelector: React.FC<VoiceSelectorProps> = ({
           {currentList.map((voice) => {
             const isSelected = selectedVoiceId === voice.voice_id
             const isPlaying = playingVoiceId === voice.voice_id
+            const isLoadingSample = loadingSampleVoiceId === voice.voice_id
             const icon = GENDER_ICON[voice.gender] ?? "✨"
             return (
               <div
@@ -86,11 +90,12 @@ export const VoiceSelector: React.FC<VoiceSelectorProps> = ({
                   className="tts-voice-item-play"
                   onClick={(e) => {
                     e.stopPropagation()
-                    onPlaySample(voice.voice_id, voice.preview_url ?? voice.audio_url)
+                    onPlaySample(voice)
                   }}
-                  title={isPlaying ? "暂停" : "试听"}
+                  disabled={isLoadingSample}
+                  title={isPlaying ? "暂停" : isLoadingSample ? "合成中" : "试听"}
                 >
-                  {isPlaying ? "⏸" : "▶"}
+                  {isLoadingSample ? <LoadingOutlined /> : isPlaying ? "⏸" : "▶"}
                 </button>
               </div>
             )

apps/web/src/pages/editing-planner/components/TtsPanel/hooks/useTtsPanel.ts

@@ -3,6 +3,7 @@ import { message } from "antd"
 import type { TtsConfig, TtsMode } from "../../../types"
 import { DEFAULT_TTS_CONFIG } from "../../../types"
 import { previewTts } from "@/api/tts"
+import { getVoiceClonePreview } from "@/api/voice-clone"
 import { fetchVoices, type UnifiedVoiceItem } from "@/api/voices"
 
 interface UseTtsPanelOptions {
@@ -59,7 +60,6 @@ export const useTtsPanel = ({ open, config, onChange, onClose }: UseTtsPanelOpti
     return () => {
       active = false
     }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [open])
 
   /* ── 组件卸载时清理音频资源 ── */
@@ -167,8 +167,10 @@ export const useTtsPanel = ({ open, config, onChange, onClose }: UseTtsPanelOpti
 
   /* ── 单音色示例试听 ── */
   const [playingVoiceId, setPlayingVoiceId] = useState<string | null>(null)
+  const [loadingSampleVoiceId, setLoadingSampleVoiceId] = useState<string | null>(null)
   const handlePlayVoiceSample = useCallback(
-    (voiceId: string, previewUrl: string | null) => {
+    async (voice: UnifiedVoiceItem) => {
+      const voiceId = voice.voice_id
       if (playingVoiceId === voiceId) {
         audioRef.current?.pause()
         audioRef.current = null
@@ -180,11 +182,34 @@ export const useTtsPanel = ({ open, config, onChange, onClose }: UseTtsPanelOpti
         audioRef.current.onended = null
         audioRef.current.pause()
       }
-      if (!previewUrl) {
+
+      let audioUrl: string | null = voice.preview_url ?? voice.audio_url
+
+      // 克隆音色：调用试听接口实时合成
+      if (voice.type === "clone" && voice.voice_clone_profile_id) {
+        setLoadingSampleVoiceId(voiceId)
+        try {
+          const preview = await getVoiceClonePreview(voice.voice_clone_profile_id)
+          audioUrl = preview.audio_url
+        } catch {
+          if (mountedRef.current) {
+            message.error("试听音频生成失败，请重试")
+          }
+          setLoadingSampleVoiceId(null)
+          return
+        } finally {
+          if (mountedRef.current) {
+            setLoadingSampleVoiceId(null)
+          }
+        }
+      }
+
+      if (!audioUrl) {
         message.warning("该音色暂无示例音频")
         return
       }
-      const audio = new Audio(previewUrl)
+
+      const audio = new Audio(audioUrl)
       audioRef.current = audio
       audio
         .play()
@@ -230,6 +255,7 @@ export const useTtsPanel = ({ open, config, onChange, onClose }: UseTtsPanelOpti
     voicesLoading,
     previewLoading,
     playingVoiceId,
+    loadingSampleVoiceId,
     handleModeChange,
     handleTextChange,
     handleVoiceSelect,

apps/web/src/pages/editing-planner/components/TtsPanel/index.tsx

@@ -26,6 +26,7 @@ const TtsPanel: React.FC<TtsPanelProps> = ({ open, onClose, config, onChange })
     voicesLoading,
     previewLoading,
     playingVoiceId,
+    loadingSampleVoiceId,
     handleModeChange,
     handleTextChange,
     handleVoiceSelect,
@@ -91,6 +92,7 @@ const TtsPanel: React.FC<TtsPanelProps> = ({ open, onClose, config, onChange })
             selectedVoiceId={config.voice_id}
             loading={voicesLoading}
             playingVoiceId={playingVoiceId}
+            loadingSampleVoiceId={loadingSampleVoiceId}
             onSelect={handleVoiceSelect}
             onPlaySample={handlePlayVoiceSample}
           />

apps/web/src/pages/generate/GeneratePage.tsx

@@ -1,6 +1,6 @@
 /**
- * 智能剪辑页面 — V21 原型 1:1 还原
- * 7 步向导：选择模板 → 选择素材 → 生成预览 → 选择标题 → 选择配音 → 选择封面 → 确认生成
+ * 智能剪辑页面 — V22 多预览 + 配音前置
+ * 7 步向导：选择模板 → 选择素材 → 选择配音 → 生成预览 → 选择标题 → 选择封面 → 确认生成
  * 左右布局：左侧 generate-form + 右侧 generate-preview
  * 主组件仅保留整体布局与事件编排
  * 状态管理 → hooks/useGenerateFormState
@@ -9,7 +9,7 @@
  * 底部按钮 → components/GenerateStepActions
  * 生成核心逻辑 → hooks/useGenerateVideo
  */
-import React from "react"
+import React, { useState, useMemo } from "react"
 import { Modal, message } from "antd"
 import { useNavigate } from "react-router-dom"
 import type { VoiceClone } from "@/api/voice-clone"
@@ -24,7 +24,7 @@ import GenerateStepActions from "./components/GenerateStepActions"
 import { useGenerateFormState } from "./hooks/useGenerateFormState"
 import { useStepNavigation } from "./hooks/useStepNavigation"
 import { useGenerateVideo } from "./hooks/useGenerateVideo"
-import { useStep3Preview } from "./hooks/useStep3Preview"
+import { useStep4Preview } from "./hooks/useStep4Preview"
 import "./generate.css"
 
 const GeneratePage: React.FC = () => {
@@ -80,8 +80,24 @@ const GeneratePage: React.FC = () => {
     message.success("音色克隆成功！")
   }
 
-  /* ── Step3 预览生成 ── */
-  const step3Preview = useStep3Preview({
+  /* ── 预览数量（多预览） ── */
+  const [previewCount, setPreviewCount] = useState(1)
+
+  /* ── 根据 voiceMode 构建 voiceIds 传给预览接口 ── */
+  /* selectedVoice / selectedClonedVoice 均为 string 类型（voice ID），
+     见 useGenerateFormState 返回值类型定义 */
+  const previewVoiceIds = useMemo((): string[] => {
+    if (voiceMode === "clone") {
+      const id: string = selectedClonedVoice
+      return id ? [id] : []
+    }
+    // preset / custom 模式
+    const id: string = selectedVoice
+    return id ? [id] : []
+  }, [voiceMode, selectedVoice, selectedClonedVoice])
+
+  /* ── Step4 预览生成（多预览 + voice_ids） ── */
+  const step4Preview = useStep4Preview({
     templates: userTemplates,
     selectedTemplate,
     materialMode,
@@ -89,6 +105,8 @@ const GeneratePage: React.FC = () => {
     smartSelectedIds,
     duration,
     videoRatio,
+    voiceIds: previewVoiceIds,
+    previewCount,
   })
 
   /* ── 步骤导航 ── */
@@ -100,7 +118,7 @@ const GeneratePage: React.FC = () => {
     selectedMaterials,
     smartSelectedIds,
     titleSettings,
-    previewReady: step3Preview.canProceed,
+    previewReady: step4Preview.canProceed,
   })
 
   /* ── 视频生成核心逻辑 ── */
@@ -187,14 +205,20 @@ const GeneratePage: React.FC = () => {
             onDismissError={handleDismissError}
             presetVoices={presetVoices}
             videoRatio={videoRatio}
-            previewStatus={step3Preview.previewStatus}
-            previewResult={step3Preview.previewResult}
-            previewError={step3Preview.previewError}
-            previewTemplateName={step3Preview.templateName}
-            previewMaterialCount={step3Preview.materialCount}
-            previewProgress={step3Preview.progress}
-            onGeneratePreview={step3Preview.generatePreview}
-            onRegeneratePreview={step3Preview.regeneratePreview}
+            /* Step4 多预览 */
+            previewCount={previewCount}
+            onPreviewCountChange={setPreviewCount}
+            previewItems={step4Preview.items}
+            previewSelectedIndex={step4Preview.selectedIndex}
+            onSelectPreview={step4Preview.setSelectedIndex}
+            previewOverallStatus={step4Preview.previewStatus}
+            previewOverallError={step4Preview.previewError}
+            previewOverallProgress={step4Preview.progress}
+            previewAnyGenerating={step4Preview.anyGenerating}
+            previewTemplateName={step4Preview.templateName}
+            previewMaterialCount={step4Preview.materialCount}
+            onGeneratePreview={step4Preview.generatePreview}
+            onRegeneratePreview={step4Preview.regeneratePreview}
           />
 
           <GenerateStepActions
@@ -210,33 +234,37 @@ const GeneratePage: React.FC = () => {
 
         {/* ════ 右侧：预览 + 生成结果 ════ */}
         <div className="xx-generate-right-col">
-          {/* 预览视频面板（Step3+ 常驻） */}
-          {currentStep >= 3 && (
+          {/* 预览视频面板（Step4+ 常驻，展示选中的预览） */}
+          {currentStep >= 4 && (
             <PreviewVideoPanel
-              previewStatus={step3Preview.previewStatus}
-              previewResult={step3Preview.previewResult}
-              previewError={step3Preview.previewError}
-              progress={step3Preview.progress}
+              previewStatus={step4Preview.previewStatus}
+              previewResult={step4Preview.previewResult}
+              previewError={step4Preview.previewError}
+              progress={step4Preview.progress}
               videoRatio={videoRatio}
-              onRegenerate={step3Preview.regeneratePreview}
+              onRegenerate={step4Preview.regeneratePreview}
+              titleText={titleSettings.title}
+              titleSettings={currentStep >= 5 ? titleSettings : undefined}
             />
           )}
 
-          {/* 正式生成结果 */}
-          <GenerateResultPanel
-            generated={generated}
-            generating={generating}
-            progress={progress}
-            generateError={generateError}
-            generatedVideos={generatedVideos}
-            onVideoPreview={(video) => {
-              setPreviewVideo(video)
-              setPreviewModalOpen(true)
-            }}
-            onDownload={handleDownload}
-            onShare={handleShare}
-            onGoToLibrary={() => navigate("/app/products")}
-          />
+          {/* 正式生成结果（Step5+ 才显示） */}
+          {currentStep >= 5 && (
+            <GenerateResultPanel
+              generated={generated}
+              generating={generating}
+              progress={progress}
+              generateError={generateError}
+              generatedVideos={generatedVideos}
+              onVideoPreview={(video) => {
+                setPreviewVideo(video)
+                setPreviewModalOpen(true)
+              }}
+              onDownload={handleDownload}
+              onShare={handleShare}
+              onGoToLibrary={() => navigate("/app/products")}
+            />
+          )}
         </div>
       </div>
 

apps/web/src/pages/generate/components/GenerateStepContent.tsx

@@ -1,6 +1,7 @@
 /**
  * GeneratePage 步骤内容渲染
  * 根据当前步骤渲染对应的 Step 组件
+ * 步骤顺序：模板(1) → 素材(2) → 配音(3) → 预览(4) → 标题(5) → 封面(6) → 确认(7)
  */
 import React from "react"
 import type { EditingTemplate } from "@/api/editing-planner"
@@ -8,12 +9,12 @@ import type { PresetVoiceItem } from "@/api/voices"
 import type { VoiceClone } from "@/api/voice-clone"
 import type { CoverConfig } from "../../editing-planner/types"
 import type { TitleSettings } from "../types"
-import type { PreviewResult, PreviewStatus } from "../hooks/useStep3Preview"
+import type { PreviewItem, PreviewStatus } from "../hooks/useStep4Preview"
 import Step1TemplateSelect from "../components/Step1TemplateSelect"
 import Step2MaterialSelect from "../components/Step2MaterialSelect"
-import Step3GeneratePreview from "../components/Step3GeneratePreview"
-import Step4TitleSettings from "../components/Step4TitleSettings"
-import Step5VoiceSelect from "../components/Step5VoiceSelect"
+import Step3VoiceSelect from "../components/Step5VoiceSelect"
+import Step4GeneratePreview from "../components/Step4GeneratePreview"
+import Step5TitleSettings from "../components/Step4TitleSettings"
 import Step6CoverSettings from "../components/Step6CoverSettings"
 import Step7ConfirmGenerate from "../components/Step7ConfirmGenerate"
 import type { GeneratedVideo } from "@/api/template-editor"
@@ -63,13 +64,18 @@ export interface GenerateStepContentProps {
   /* 其他 */
   presetVoices: PresetVoiceItem[]
   videoRatio: string
-  /* Step3 预览 */
-  previewStatus: PreviewStatus
-  previewResult: PreviewResult | null
-  previewError: string
+  /* Step4 预览（多预览） */
+  previewCount: number
+  onPreviewCountChange: (count: number) => void
+  previewItems: PreviewItem[]
+  previewSelectedIndex: number
+  onSelectPreview: (index: number) => void
+  previewOverallStatus: PreviewStatus
+  previewOverallError: string
+  previewOverallProgress: number
+  previewAnyGenerating: boolean
   previewTemplateName: string
   previewMaterialCount: string
-  previewProgress: number
   onGeneratePreview: () => void
   onRegeneratePreview: () => void
 }
@@ -94,14 +100,8 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
     selectedVoice,
     onSelectedVoiceChange,
     voiceMode,
-    onVoiceModeChange,
     selectedClonedVoice,
-    onSelectedClonedVoiceChange,
     clonedVoices,
-    addClone,
-    hasProcessing,
-    cloneModalOpen,
-    onCloneModalOpenChange,
     generateCount,
     onGenerateCountChange,
     generating,
@@ -113,12 +113,17 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
     onDismissError,
     presetVoices,
     videoRatio,
-    previewStatus,
-    previewResult,
-    previewError,
+    previewCount,
+    onPreviewCountChange,
+    previewItems,
+    previewSelectedIndex,
+    onSelectPreview,
+    previewOverallStatus,
+    previewOverallError,
+    previewOverallProgress,
+    previewAnyGenerating,
     previewTemplateName,
     previewMaterialCount,
-    previewProgress,
     onGeneratePreview,
     onRegeneratePreview,
   } = props
@@ -145,41 +150,36 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
       )
     case 3:
       return (
-        <Step3GeneratePreview
-          templateName={previewTemplateName}
-          materialCount={previewMaterialCount}
-          duration={duration}
-          videoRatio={videoRatio}
-          previewStatus={previewStatus}
-          previewResult={previewResult}
-          previewError={previewError}
-          progress={previewProgress}
-          onGeneratePreview={onGeneratePreview}
-          onRegeneratePreview={onRegeneratePreview}
+        <Step3VoiceSelect
+          selectedVoice={selectedVoice}
+          onSelectedVoiceChange={onSelectedVoiceChange}
         />
       )
     case 4:
       return (
-        <Step4TitleSettings
-          titleSettings={titleSettings}
-          onTitleSettingsChange={onTitleSettingsChange}
+        <Step4GeneratePreview
+          templateName={previewTemplateName}
+          materialCount={previewMaterialCount}
+          duration={duration}
+          videoRatio={videoRatio}
+          previewCount={previewCount}
+          onPreviewCountChange={onPreviewCountChange}
+          items={previewItems}
+          selectedIndex={previewSelectedIndex}
+          onSelectPreview={onSelectPreview}
+          overallStatus={previewOverallStatus}
+          overallError={previewOverallError}
+          overallProgress={previewOverallProgress}
+          anyGenerating={previewAnyGenerating}
+          onGeneratePreview={onGeneratePreview}
+          onRegeneratePreview={onRegeneratePreview}
         />
       )
     case 5:
       return (
-        <Step5VoiceSelect
-          selectedVoice={selectedVoice}
-          onSelectedVoiceChange={onSelectedVoiceChange}
-          voiceMode={voiceMode}
-          onVoiceModeChange={onVoiceModeChange}
-          selectedClonedVoice={selectedClonedVoice}
-          onSelectedClonedVoiceChange={onSelectedClonedVoiceChange}
-          clonedVoices={clonedVoices}
-          addClone={addClone}
-          hasProcessing={hasProcessing}
-          cloneModalOpen={cloneModalOpen}
-          onCloneModalOpenChange={onCloneModalOpenChange}
-          titleText={titleSettings.title}
+        <Step5TitleSettings
+          titleSettings={titleSettings}
+          onTitleSettingsChange={onTitleSettingsChange}
         />
       )
     case 6:
@@ -188,6 +188,8 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
           coverSettings={coverSettings}
           onCoverSettingsChange={onCoverSettingsChange}
           duration={duration}
+          assetIds={materialMode === "auto" ? smartSelectedIds : selectedMaterials}
+          selectedTemplate={selectedTemplate}
         />
       )
     case 7:

apps/web/src/pages/generate/components/PreviewVideoPanel.tsx

@@ -1,10 +1,20 @@
 /**
  * 右侧预览视频面板
- * Step3 生成预览后常驻显示预览视频
+ * Step4 生成预览后常驻显示预览视频
+ * Step5+ 用 Canvas 绘制标题预览（替代 CSS overlay，与 ASS 渲染行为一致）
+ *
+ * 设计说明：标题预览仅在有视频时显示（叠加在视频画面上方）。
+ * 无视频状态（idle/loading/error）下不再单独显示标题预览，这是有意为之的设计简化。
+ *
+ * Canvas 居中修复说明：
+ * Canvas 的 CSS 位置和尺寸直接匹配视频实际渲染区域（通过 getBoundingClientRect），
+ * 绘制坐标系基于 Canvas 自身尺寸，x = w/2 即可实现水平居中，
+ * 避免容器与视频尺寸不一致时浏览器拉伸 Canvas 导致居中偏移。
  */
-import React from "react"
+import React, { useRef, useEffect, useCallback } from "react"
 import { PlayCircleOutlined, LoadingOutlined } from "@ant-design/icons"
-import type { PreviewResult, PreviewStatus } from "../hooks/useStep3Preview"
+import type { PreviewResult, PreviewStatus } from "../hooks/useStep4Preview"
+import type { TitleSettings } from "../types"
 
 interface PreviewVideoPanelProps {
   previewStatus: PreviewStatus
@@ -13,8 +23,138 @@ interface PreviewVideoPanelProps {
   progress: number
   videoRatio: string
   onRegenerate: () => void
+  /** 标题文字（Step5 起传入） */
+  titleText?: string
+  /** 标题样式设置（Step5 起传入） */
+  titleSettings?: TitleSettings
 }
 
+/* ── Canvas 绘制工具函数 ── */
+
+/**
+ * 将文本按 maxWidth 逐字换行，返回行数组。
+ * 与 ASS 字幕引擎的逐字换行行为一致。
+ */
+function wrapText(ctx: CanvasRenderingContext2D, text: string, maxWidth: number): string[] {
+  const lines: string[] = []
+  let currentLine = ""
+  for (const char of text) {
+    const testLine = currentLine + char
+    if (ctx.measureText(testLine).width > maxWidth && currentLine) {
+      lines.push(currentLine)
+      currentLine = char
+    } else {
+      currentLine = testLine
+    }
+  }
+  if (currentLine) lines.push(currentLine)
+  return lines
+}
+
+/**
+ * 在 canvas 上绘制标题文字（含描边/阴影/多行居中）
+ *
+ * Canvas 已通过 CSS 定位到视频实际渲染位置，
+ * 坐标系基于 Canvas 自身尺寸，居中直接使用 w/2。
+ *
+ * @param ctx canvas 上下文
+ * @param w canvas CSS 宽度（= 视频渲染宽度）
+ * @param h canvas CSS 高度（= 视频渲染高度）
+ * @param text 标题文字
+ * @param settings 标题样式
+ * @param paddingX 左右边距（px），与 ASS 的 MarginL/MarginR 对应
+ * @param position "top" | "center" | "bottom"
+ * @param topOffset 顶部/底部偏移量
+ */
+function drawTitleOnCanvas(
+  ctx: CanvasRenderingContext2D,
+  w: number,
+  h: number,
+  text: string,
+  settings: TitleSettings,
+  paddingX: number,
+  position: string,
+  topOffset: number,
+) {
+  const dpr = window.devicePixelRatio || 1
+
+  // 设置 canvas 物理像素尺寸（高清屏适配）
+  ctx.canvas.width = Math.round(w * dpr)
+  ctx.canvas.height = Math.round(h * dpr)
+  ctx.scale(dpr, dpr)
+
+  // 清除
+  ctx.clearRect(0, 0, w, h)
+
+  // 可用宽度 = 总宽 - 左右边距
+  const availableWidth = w - paddingX * 2
+  if (availableWidth <= 0) return
+
+  // 字体设置
+  const fontSize = Math.round(Math.min(settings.size, 36))
+  const fontWeight = settings.bold ? "bold" : "normal"
+  const fontStyle = settings.italic ? "italic" : "normal"
+  ctx.font = `${fontStyle} ${fontWeight} ${fontSize}px "${settings.font}"`
+
+  // 文字属性
+  ctx.textAlign = "center"
+  ctx.textBaseline = "middle"
+  ctx.fillStyle = settings.color
+
+  const lineHeight = fontSize * 1.4
+
+  // 描边 & 阴影
+  if (settings.stroke) {
+    ctx.strokeStyle = "rgba(0,0,0,0.6)"
+    ctx.lineWidth = 2
+    ctx.lineJoin = "round"
+  }
+  if (settings.shadow) {
+    ctx.shadowColor = "rgba(0,0,0,0.7)"
+    ctx.shadowBlur = 4
+    ctx.shadowOffsetX = 2
+    ctx.shadowOffsetY = 2
+  }
+
+  // 换行
+  const displayText = text && text.trim() ? text : "请选择或输入标题"
+  const lines = wrapText(ctx, displayText, availableWidth)
+
+  // 起始 Y：根据 position 计算
+  const totalTextHeight = lines.length * lineHeight
+  let startY: number
+  switch (position) {
+    case "top":
+      startY = topOffset
+      break
+    case "center":
+      startY = (h - totalTextHeight) / 2 + lineHeight / 2
+      break
+    case "bottom":
+    default:
+      startY = h - topOffset - totalTextHeight + lineHeight / 2
+      break
+  }
+
+  // 居中 x = w/2（Canvas 已定位到视频位置，无需额外偏移）
+  const x = w / 2
+  lines.forEach((line, i) => {
+    const y = startY + i * lineHeight
+    if (settings.stroke) ctx.strokeText(line, x, y)
+    ctx.fillText(line, x, y)
+  })
+
+  // 重置 shadow（避免影响后续绘制）
+  if (settings.shadow) {
+    ctx.shadowColor = "transparent"
+    ctx.shadowBlur = 0
+    ctx.shadowOffsetX = 0
+    ctx.shadowOffsetY = 0
+  }
+}
+
+/* ── 组件 ── */
+
 export const PreviewVideoPanel: React.FC<PreviewVideoPanelProps> = ({
   previewStatus,
   previewResult,
@@ -22,10 +162,133 @@ export const PreviewVideoPanel: React.FC<PreviewVideoPanelProps> = ({
   progress,
   videoRatio,
   onRegenerate,
+  titleText,
+  titleSettings,
 }) => {
   const hasPreview = previewStatus === "ready" && previewResult
   const isLoading = previewStatus === "pending" || previewStatus === "generating"
   const isError = previewStatus === "error"
+  const showTitlePreview = !!titleSettings
+  const videoAspectStyle = { aspectRatio: (videoRatio || "16:9").replace(":", "/") }
+
+  // video 模式 refs
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  const containerRef = useRef<HTMLDivElement>(null)
+  const videoRef = useRef<HTMLVideoElement>(null)
+
+  // 字体加载状态（ref 供 draw 回调同步读取，无需 state 避免触发不必要的重渲染）
+  const fontLoadedRef = useRef(false)
+
+  /** 在 video canvas 上绘制标题 */
+  const drawVideoTitle = useCallback(() => {
+    // 通过 ref 读取字体状态，避免 fontLoaded 进入依赖数组
+    if (!fontLoadedRef.current) return
+    const canvas = canvasRef.current
+    const container = containerRef.current
+    if (!canvas || !container || !titleSettings) return
+    const ctx = canvas.getContext("2d")
+    if (!ctx) return
+
+    const containerRect = container.getBoundingClientRect()
+    if (containerRect.width <= 0 || containerRect.height <= 0) return
+
+    // 使用 video 元素的 getBoundingClientRect 获取实际渲染尺寸和位置
+    const videoEl = videoRef.current
+    let drawW = containerRect.width
+    let drawH = containerRect.height
+    let offsetX = 0
+    let offsetY = 0
+
+    if (videoEl && videoEl.clientWidth > 0 && videoEl.clientHeight > 0) {
+      const videoRect = videoEl.getBoundingClientRect()
+      drawW = videoRect.width
+      drawH = videoRect.height
+      offsetX = videoRect.left - containerRect.left
+      offsetY = videoRect.top - containerRect.top
+    }
+
+    // 更新 Canvas CSS 位置和尺寸，使其与视频实际渲染区域完全对齐
+    canvas.style.left = `${offsetX}px`
+    canvas.style.top = `${offsetY}px`
+    canvas.style.width = `${drawW}px`
+    canvas.style.height = `${drawH}px`
+
+    // 绘制时，坐标系基于 Canvas 自身尺寸，无需额外偏移
+    drawTitleOnCanvas(
+      ctx,
+      drawW,
+      drawH,
+      titleText || "",
+      titleSettings,
+      40,
+      titleSettings.position,
+      60,
+    )
+  }, [titleText, titleSettings])
+
+  // video 模式：ResizeObserver 监听容器尺寸变化 → 重绘
+  useEffect(() => {
+    if (!showTitlePreview || !hasPreview) return
+    const container = containerRef.current
+    if (!container) return
+
+    const observer = new ResizeObserver(() => {
+      drawVideoTitle()
+    })
+    observer.observe(container)
+    requestAnimationFrame(drawVideoTitle)
+
+    return () => observer.disconnect()
+  }, [showTitlePreview, hasPreview, drawVideoTitle])
+
+  // 字体加载检测：字体变更时重新检测，确保 measureText 使用正确字体
+  useEffect(() => {
+    if (!showTitlePreview || !titleSettings) {
+      fontLoadedRef.current = false
+      return
+    }
+    let cancelled = false
+    fontLoadedRef.current = false
+
+    const fontWeight = titleSettings.bold ? "bold" : ""
+    const fontStyle = titleSettings.italic ? "italic" : ""
+    const fontSpec =
+      `${fontStyle} ${fontWeight} ${titleSettings.size}px "${titleSettings.font}"`.trim()
+
+    const onFontReady = () => {
+      if (cancelled) return
+      fontLoadedRef.current = true
+      // ref 已同步更新，显式触发重绘（draw 内部通过 ref 检查字体状态）
+      requestAnimationFrame(() => {
+        if (!cancelled) {
+          drawVideoTitle()
+        }
+      })
+    }
+
+    if (document.fonts.check(fontSpec)) {
+      onFontReady()
+      return
+    }
+
+    document.fonts
+      .load(fontSpec)
+      .then(() => onFontReady())
+      .catch(() => {
+        document.fonts.ready.then(() => onFontReady())
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [showTitlePreview, titleSettings, drawVideoTitle])
+
+  // video 加载完成后重绘
+  const handleVideoLoaded = useCallback(() => {
+    if (showTitlePreview) {
+      requestAnimationFrame(drawVideoTitle)
+    }
+  }, [showTitlePreview, drawVideoTitle])
 
   return (
     <div className="xx-generate-preview">
@@ -48,7 +311,7 @@ export const PreviewVideoPanel: React.FC<PreviewVideoPanelProps> = ({
       {/* 生成中 */}
       {isLoading && (
         <div className="xx-preview-loading-panel">
-          <div className="xx-preview-video">
+          <div className="xx-preview-video" style={videoAspectStyle}>
             <div className="xx-preview-loading-center">
               <LoadingOutlined style={{ fontSize: 36, color: "#fff" }} spin />
               <p style={{ marginTop: 12, color: "rgba(255,255,255,0.8)", fontSize: 14 }}>
@@ -65,20 +328,44 @@ export const PreviewVideoPanel: React.FC<PreviewVideoPanelProps> = ({
       {/* 生成失败 */}
       {isError && (
         <div className="xx-preview-error-panel">
-          <div className="xx-preview-video xx-preview-video--error">
+          <div className="xx-preview-video xx-preview-video--error" style={videoAspectStyle}>
             <p style={{ color: "rgba(255,255,255,0.8)", fontSize: 14 }}>预览生成失败</p>
           </div>
-          <p className="xx-preview-error-msg">{previewError || "请重试"}</p>
+          <p className="xx-preview-error-msg">
+            {typeof previewError === "string" && previewError ? previewError : "请重试"}
+          </p>
           <button className="xx-btn xx-btn-ghost xx-btn-block" onClick={onRegenerate}>
             重新生成
           </button>
         </div>
       )}
 
-      {/* 预览成功 */}
+      {/* 预览成功 + Canvas 标题叠加 */}
       {hasPreview && (
-        <div className="xx-preview-video">
-          <video src={previewResult.videoUrl} controls preload="metadata" />
+        <div ref={containerRef} style={{ position: "relative" }}>
+          <div className="xx-preview-video" style={videoAspectStyle}>
+            <video
+              ref={videoRef}
+              src={previewResult.videoUrl}
+              controls
+              preload="metadata"
+              onLoadedMetadata={handleVideoLoaded}
+            />
+          </div>
+          {showTitlePreview && (
+            <canvas
+              ref={canvasRef}
+              style={{
+                position: "absolute",
+                top: 0,
+                left: 0,
+                width: "100%",
+                height: "100%",
+                zIndex: 1,
+                pointerEvents: "none",
+              }}
+            />
+          )}
         </div>
       )}
 
@@ -87,7 +374,10 @@ export const PreviewVideoPanel: React.FC<PreviewVideoPanelProps> = ({
         <div className="xx-preview-info">
           <div className="xx-preview-info-row">
             <span>时长</span>
-            <span>{previewResult.duration.toFixed(1)} 秒</span>
+            <span>
+              {(typeof previewResult.duration === "number" ? previewResult.duration : 0).toFixed(1)}{" "}
+              秒
+            </span>
           </div>
           <div className="xx-preview-info-row">
             <span>片段数</span>

apps/web/src/pages/generate/components/Step2MaterialSelect.tsx

@@ -65,8 +65,6 @@ const Step2MaterialSelect: React.FC<Step2MaterialSelectProps> = (props) => {
       {m.materialMode === "auto" && (
         <div className="xx-smart-match-section">
           <SmartMatchInput
-            inputValue={m.smartMatchInput}
-            onInputChange={m.setSmartMatchInput}
             matching={m.smartMatching}
             onMatch={m.handleSmartMatch}
             hasMatched={m.hasMatched}
@@ -76,7 +74,7 @@ const Step2MaterialSelect: React.FC<Step2MaterialSelectProps> = (props) => {
           />
 
           <SmartMatchResults
-            results={m.smartMatchedResults}
+            matchedAssets={m.smartMatchedResults}
             selectedIds={m.smartSelectedIds}
             matching={m.smartMatching}
             hasMatched={m.hasMatched}

apps/web/src/pages/generate/components/Step3GeneratePreview.tsx

@@ -1,164 +0,0 @@
-/**
- * Step 3 生成预览组件
- * 调用后端预览生成接口，展示真实视频预览
- */
-import React from "react"
-import {
-  CheckCircleFilled,
-  LoadingOutlined,
-  ReloadOutlined,
-  PlayCircleOutlined,
-  ExclamationCircleFilled,
-  ClockCircleOutlined,
-} from "@ant-design/icons"
-import type { PreviewResult, PreviewStatus } from "../hooks/useStep3Preview"
-
-interface Step3GeneratePreviewProps {
-  templateName: string
-  materialCount: string
-  duration: number
-  videoRatio: string
-  previewStatus: PreviewStatus
-  previewResult: PreviewResult | null
-  previewError: string
-  progress: number
-  onGeneratePreview: () => void
-  onRegeneratePreview: () => void
-}
-
-const Step3GeneratePreview: React.FC<Step3GeneratePreviewProps> = ({
-  templateName,
-  materialCount,
-  videoRatio,
-  previewStatus,
-  previewResult,
-  previewError,
-  progress,
-  onGeneratePreview,
-  onRegeneratePreview,
-}) => {
-  return (
-    <div className="xx-form-section">
-      <h3>🎬 生成预览</h3>
-
-      {/* 预览生成按钮 */}
-      {previewStatus === "idle" && (
-        <div className="xx-preview-generate-section">
-          <div className="xx-preview-generate-hint">
-            <PlayCircleOutlined style={{ fontSize: 32, color: "#3b82f6", marginBottom: 12 }} />
-            <p className="xx-preview-generate-title">一键生成剪辑预览</p>
-            <p className="xx-preview-generate-desc">
-              AI 将根据您选择的模板和素材，智能生成完整视频预览（480p 低清版）
-            </p>
-          </div>
-          <button
-            className="xx-btn xx-btn-primary xx-preview-generate-btn"
-            onClick={onGeneratePreview}
-          >
-            ✨ 生成预览
-          </button>
-        </div>
-      )}
-
-      {/* 排队中 */}
-      {previewStatus === "pending" && (
-        <div className="xx-preview-loading">
-          <ClockCircleOutlined style={{ fontSize: 32, color: "#faad14" }} spin />
-          <p className="xx-preview-loading-text">预览排队中...</p>
-          <p className="xx-preview-loading-desc">正在等待渲染资源，请稍候</p>
-        </div>
-      )}
-
-      {/* 生成中 */}
-      {previewStatus === "generating" && (
-        <div className="xx-preview-loading">
-          <LoadingOutlined style={{ fontSize: 32, color: "#3b82f6" }} spin />
-          <p className="xx-preview-loading-text">正在生成预览视频... {progress}%</p>
-          <p className="xx-preview-loading-desc">AI 正在剪辑素材并合成预览视频</p>
-          <div className="xx-preview-progress-bar">
-            <div className="xx-preview-progress-fill" style={{ width: `${progress}%` }} />
-          </div>
-        </div>
-      )}
-
-      {/* 生成失败 */}
-      {previewStatus === "error" && (
-        <div className="xx-preview-error">
-          <ExclamationCircleFilled style={{ fontSize: 28, color: "#ef4444" }} />
-          <p className="xx-preview-error-text">预览生成失败</p>
-          <p className="xx-preview-error-desc">{previewError || "请稍后重试"}</p>
-          <button className="xx-btn xx-btn-primary" onClick={onRegeneratePreview}>
-            <ReloadOutlined /> 重新生成
-          </button>
-        </div>
-      )}
-
-      {/* 生成成功 - 视频预览 */}
-      {previewStatus === "ready" && previewResult && (
-        <>
-          <div className="xx-preview-tip">
-            <CheckCircleFilled style={{ color: "#52c41a", marginRight: 8 }} />
-            <span>预览生成成功，确认效果后进入下一步</span>
-            <button
-              className="xx-preview-regenerate-btn"
-              onClick={onRegeneratePreview}
-              title="重新生成"
-            >
-              <ReloadOutlined /> 重新生成
-            </button>
-          </div>
-
-          {/* 视频播放器 */}
-          <div className="xx-preview-video-wrapper">
-            <video
-              className="xx-preview-video"
-              src={previewResult.videoUrl}
-              controls
-              preload="metadata"
-            />
-          </div>
-
-          {/* 剪辑方案信息 */}
-          <div className="xx-preview-plan-card">
-            <div className="xx-preview-plan-title">剪辑方案信息</div>
-            <div className="xx-preview-plan-info">
-              <div className="xx-preview-plan-row">
-                <span className="xx-preview-plan-label">模板</span>
-                <span className="xx-preview-plan-value">{templateName}</span>
-              </div>
-              <div className="xx-preview-plan-row">
-                <span className="xx-preview-plan-label">素材数量</span>
-                <span className="xx-preview-plan-value">{materialCount}</span>
-              </div>
-              <div className="xx-preview-plan-row">
-                <span className="xx-preview-plan-label">片段数</span>
-                <span className="xx-preview-plan-value">{previewResult.clipCount} 段</span>
-              </div>
-              <div className="xx-preview-plan-row">
-                <span className="xx-preview-plan-label">转场次数</span>
-                <span className="xx-preview-plan-value">{previewResult.transitionCount} 次</span>
-              </div>
-              <div className="xx-preview-plan-row">
-                <span className="xx-preview-plan-label">素材使用率</span>
-                <span className="xx-preview-plan-value">{previewResult.materialUsage}%</span>
-              </div>
-              <div className="xx-preview-plan-row">
-                <span className="xx-preview-plan-label">实际时长</span>
-                <span className="xx-preview-plan-value">
-                  {previewResult.duration.toFixed(1)} 秒
-                </span>
-              </div>
-              <div className="xx-preview-plan-row">
-                <span className="xx-preview-plan-label">视频比例</span>
-                <span className="xx-preview-plan-value">{videoRatio}</span>
-              </div>
-            </div>
-            <div className="xx-preview-plan-hint">💡 这是 480p 预览版，正式生成将输出高清视频</div>
-          </div>
-        </>
-      )}
-    </div>
-  )
-}
-
-export default Step3GeneratePreview

apps/web/src/pages/generate/components/Step4GeneratePreview.tsx

@@ -0,0 +1,294 @@
+/**
+ * Step 4 生成预览组件（支持多预览）
+ * 调用后端预览生成接口，展示多个真实视频预览（网格布局）
+ */
+import React from "react"
+import {
+  CheckCircleFilled,
+  LoadingOutlined,
+  ReloadOutlined,
+  PlayCircleOutlined,
+  ExclamationCircleFilled,
+  ClockCircleOutlined,
+} from "@ant-design/icons"
+import { InputNumber } from "antd"
+import type { PreviewItem, PreviewStatus } from "../hooks/useStep4Preview"
+
+interface Step4GeneratePreviewProps {
+  templateName: string
+  materialCount: string
+  duration: number
+  videoRatio: string
+  previewCount: number
+  onPreviewCountChange: (count: number) => void
+  items: PreviewItem[]
+  selectedIndex: number
+  onSelectPreview: (index: number) => void
+  overallStatus: PreviewStatus
+  overallError: string
+  overallProgress: number
+  anyGenerating: boolean
+  onGeneratePreview: () => void
+  onRegeneratePreview: () => void
+}
+
+/** 预览数量选项 */
+const PREVIEW_COUNT_OPTIONS = [
+  { value: 1, label: "1个" },
+  { value: 2, label: "2个" },
+  { value: 3, label: "3个" },
+]
+
+const Step4GeneratePreview: React.FC<Step4GeneratePreviewProps> = ({
+  templateName: _templateName,
+  materialCount: _materialCount,
+  videoRatio,
+  previewCount,
+  onPreviewCountChange,
+  items,
+  selectedIndex,
+  onSelectPreview,
+  overallStatus,
+  overallError,
+  overallProgress,
+  anyGenerating,
+  onGeneratePreview,
+  onRegeneratePreview,
+}) => {
+  const aspectRatio = (videoRatio || "16:9").replace(":", "/") // "9:16" → "9/16", "16:9" → "16/9"
+  const isIdle = overallStatus === "idle"
+  const isError = overallStatus === "error" && !items.some((it) => it.status === "ready")
+
+  return (
+    <div className="xx-form-section">
+      <h3>🎬 生成预览</h3>
+
+      {/* 预览数量选择器（仅在 idle 状态显示） */}
+      {isIdle && (
+        <div style={{ marginBottom: 16, display: "flex", alignItems: "center", gap: 12 }}>
+          <span style={{ fontSize: 14, color: "#666" }}>预览数量：</span>
+          <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
+            {PREVIEW_COUNT_OPTIONS.map((opt) => (
+              <button
+                key={opt.value}
+                type="button"
+                onClick={() => onPreviewCountChange(opt.value)}
+                style={{
+                  padding: "4px 12px",
+                  borderRadius: 6,
+                  border: previewCount === opt.value ? "1px solid #1677ff" : "1px solid #d9d9d9",
+                  background: previewCount === opt.value ? "#e6f4ff" : "#fff",
+                  color: previewCount === opt.value ? "#1677ff" : "#666",
+                  cursor: "pointer",
+                  fontSize: 13,
+                  fontWeight: previewCount === opt.value ? 600 : 400,
+                }}
+              >
+                {opt.label}
+              </button>
+            ))}
+            <InputNumber
+              min={1}
+              max={10}
+              value={previewCount}
+              onChange={(val) => val && onPreviewCountChange(val)}
+              style={{ width: 70 }}
+              placeholder="自定义"
+            />
+            <span style={{ fontSize: 12, color: "#999", marginLeft: 4 }}>（1~10）</span>
+          </div>
+          {previewCount > 1 && (
+            <span style={{ fontSize: 12, color: "#999" }}>生成多个预览可对比不同剪辑效果</span>
+          )}
+        </div>
+      )}
+
+      {/* 预览生成按钮（idle 状态） */}
+      {isIdle && (
+        <div className="xx-preview-generate-section">
+          <div className="xx-preview-generate-hint">
+            <PlayCircleOutlined style={{ fontSize: 32, color: "#3b82f6", marginBottom: 12 }} />
+            <p className="xx-preview-generate-title">一键生成剪辑预览</p>
+            <p className="xx-preview-generate-desc">
+              AI 将根据您选择的模板、素材和配音，智能生成
+              {previewCount > 1 ? `${previewCount}个不同版本的` : ""}视频预览（480p 低清版）
+            </p>
+          </div>
+          <button
+            className="xx-btn xx-btn-primary xx-preview-generate-btn"
+            onClick={onGeneratePreview}
+          >
+            ✨ 生成预览{previewCount > 1 ? `（${previewCount}个）` : ""}
+          </button>
+        </div>
+      )}
+
+      {/* 整体排队中（所有都在 pending） */}
+      {anyGenerating && items.every((it) => it.status === "pending") && (
+        <div className="xx-preview-loading">
+          <ClockCircleOutlined style={{ fontSize: 32, color: "#faad14" }} spin />
+          <p className="xx-preview-loading-text">预览排队中...</p>
+          <p className="xx-preview-loading-desc">正在等待渲染资源，请稍候</p>
+        </div>
+      )}
+
+      {/* 多预览网格（生成中/完成/部分完成） */}
+      {(anyGenerating || overallStatus === "ready") && items.length > 0 && (
+        <div
+          className="xx-preview-grid"
+          style={{
+            display: "grid",
+            gridTemplateColumns: `repeat(${Math.min(items.length, 3)}, 1fr)`,
+            gap: 12,
+            maxWidth: `${Math.min(items.length, 3) * 280 + (Math.min(items.length, 3) - 1) * 12}px`,
+            margin: "0 auto 16px",
+          }}
+        >
+          {items.map((item) => {
+            const isSelected = item.index === selectedIndex
+            return (
+              <div
+                key={item.index}
+                onClick={() => {
+                  if (item.status === "ready") onSelectPreview(item.index)
+                }}
+                style={{
+                  borderRadius: 8,
+                  border: isSelected ? "2px solid #1677ff" : "1px solid #e8e8e8",
+                  overflow: "hidden",
+                  cursor: item.status === "ready" ? "pointer" : "default",
+                  opacity: item.status === "error" ? 0.6 : 1,
+                  transition: "all 0.2s",
+                }}
+              >
+                {/* 缩略图/状态区域 */}
+                <div
+                  style={{
+                    aspectRatio,
+                    background: "#000",
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    position: "relative",
+                  }}
+                >
+                  {item.status === "ready" && item.result && (
+                    <video
+                      src={item.result.videoUrl}
+                      controls
+                      autoPlay
+                      muted
+                      loop
+                      preload="metadata"
+                      style={{
+                        width: "100%",
+                        height: "100%",
+                        objectFit: "cover",
+                      }}
+                    />
+                  )}
+                  {(item.status === "pending" || item.status === "generating") && (
+                    <div style={{ textAlign: "center" }}>
+                      <LoadingOutlined style={{ fontSize: 24, color: "#fff" }} spin />
+                      <p style={{ color: "rgba(255,255,255,0.8)", fontSize: 12, marginTop: 8 }}>
+                        {item.status === "pending" ? "排队中..." : `生成中 ${item.progress}%`}
+                      </p>
+                    </div>
+                  )}
+                  {item.status === "error" && (
+                    <div style={{ textAlign: "center", padding: 8 }}>
+                      <ExclamationCircleFilled style={{ fontSize: 20, color: "#ef4444" }} />
+                      <p
+                        style={{
+                          color: "rgba(255,255,255,0.7)",
+                          fontSize: 11,
+                          marginTop: 4,
+                        }}
+                      >
+                        生成失败
+                      </p>
+                    </div>
+                  )}
+                  {/* 选中角标 */}
+                  {isSelected && item.status === "ready" && (
+                    <div
+                      style={{
+                        position: "absolute",
+                        top: 4,
+                        right: 4,
+                        background: "#1677ff",
+                        color: "#fff",
+                        fontSize: 10,
+                        padding: "2px 6px",
+                        borderRadius: 4,
+                      }}
+                    >
+                      预览 #{item.index + 1}
+                    </div>
+                  )}
+                </div>
+                {/* 底部信息 */}
+                {item.status === "ready" && item.result && (
+                  <div
+                    style={{
+                      padding: "6px 8px",
+                      background: "#fafafa",
+                      fontSize: 11,
+                      color: "#666",
+                      display: "flex",
+                      justifyContent: "space-between",
+                    }}
+                  >
+                    <span>{item.result.duration.toFixed(1)}秒</span>
+                    <span>{item.result.clipCount}段</span>
+                  </div>
+                )}
+              </div>
+            )
+          })}
+        </div>
+      )}
+
+      {/* 整体进度条（多预览生成中） */}
+      {anyGenerating && (
+        <div className="xx-preview-progress-bar" style={{ marginBottom: 12 }}>
+          <div className="xx-preview-progress-fill" style={{ width: `${overallProgress}%` }} />
+        </div>
+      )}
+
+      {/* 全部完成提示 */}
+      {overallStatus === "ready" && (
+        <div className="xx-preview-tip">
+          <CheckCircleFilled style={{ color: "#52c41a", marginRight: 8 }} />
+          <span>
+            {items.filter((it) => it.status === "ready").length} 个预览生成成功
+            {items.length > 1 ? "，点击选择要查看的版本" : "，确认效果后进入下一步"}
+          </span>
+          <button
+            className="xx-preview-regenerate-btn"
+            onClick={onRegeneratePreview}
+            title="重新生成"
+          >
+            <ReloadOutlined /> 重新生成
+          </button>
+        </div>
+      )}
+
+      {/* 全部失败 */}
+      {isError && (
+        <div className="xx-preview-error">
+          <ExclamationCircleFilled style={{ fontSize: 28, color: "#ef4444" }} />
+          <p className="xx-preview-error-text">预览生成失败</p>
+          <p className="xx-preview-error-desc">
+            {typeof overallError === "string" && overallError ? overallError : "请稍后重试"}
+          </p>
+          <button className="xx-btn xx-btn-primary" onClick={onRegeneratePreview}>
+            <ReloadOutlined /> 重新生成
+          </button>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default Step4GeneratePreview

apps/web/src/pages/generate/components/Step4TitleSettings.tsx

@@ -2,7 +2,7 @@
  * Step 4 标题设置组件
  */
 import React from "react"
-import { Select } from "antd"
+import { AutoComplete } from "antd"
 import { POSITION_OPTIONS, FONT_OPTIONS } from "../constants"
 import type { TitleSettings } from "../types"
 import { useStep4Title } from "../hooks/useStep4Title"
@@ -21,40 +21,73 @@ const Step4TitleSettings: React.FC<Step4TitleSettingsProps> = (props) => {
     <div className="xx-form-section">
       <h3>📝 选择标题</h3>
 
-      <AiTitleGenerator
-        inputValue={t.aiTitleInput}
-        onInputChange={t.setAiTitleInput}
-        generating={t.aiTitleGenerating}
-        onGenerate={t.handleGenerateAiTitles}
-        results={t.aiTitleResults}
-        hasGenerated={t.hasGeneratedTitles}
-        onSelect={t.handleSelectAiTitle}
-        selectedTitle={t.titleSettings.title}
-        onRefresh={t.handleRefreshAiTitles}
-      />
+      {/* AI 自动选择模式 */}
+      {t.titleSettings.aiAutoSelect && (
+        <>
+          <div className="xx-title-ai-toggle">
+            <span className="xx-toggle-label">AI 自动选择标题</span>
+            <div className="xx-switch active" onClick={t.toggleAiAutoSelect}>
+              <div className="xx-switch-knob" />
+            </div>
+          </div>
 
-      <div className="xx-divider">
-        <span>或手动选择</span>
-      </div>
-
-      <div className="xx-title-ai-toggle">
-        <span className="xx-toggle-label">AI 自动选择标题</span>
-        <div
-          className={`xx-switch ${t.titleSettings.aiAutoSelect ? "active" : ""}`}
-          onClick={t.toggleAiAutoSelect}
-        >
-          <div className="xx-switch-knob" />
-        </div>
-      </div>
+          {/* 显示当前 AI 选中的标题（只读）+ 换一个按钮 */}
+          <div className="xx-form-field">
+            <label>当前 AI 选定标题</label>
+            <div
+              style={{
+                display: "flex",
+                alignItems: "center",
+                gap: 10,
+                padding: "8px 12px",
+                background: "var(--bg-secondary, rgba(0,0,0,0.04))",
+                borderRadius: 8,
+                fontSize: 14,
+                color: "var(--text-primary, #333)",
+              }}
+            >
+              <span style={{ flex: 1 }}>{t.titleSettings.title || "AI 将自动为你选择标题"}</span>
+              <button
+                type="button"
+                className="xx-btn xx-btn-primary"
+                style={{ flexShrink: 0, fontSize: 13, padding: "4px 12px" }}
+                onClick={t.autoGenerateTitle}
+              >
+                🔄 换一个
+              </button>
+            </div>
+          </div>
+        </>
+      )}
 
+      {/* 手动选择模式 */}
       {!t.titleSettings.aiAutoSelect && (
         <>
+          <AiTitleGenerator
+            inputValue={t.aiTitleInput}
+            onInputChange={t.setAiTitleInput}
+            generating={t.aiTitleGenerating}
+            onGenerate={t.handleGenerateAiTitles}
+            results={t.aiTitleResults}
+            hasGenerated={t.hasGeneratedTitles}
+            onSelect={t.handleSelectAiTitle}
+            selectedTitle={t.titleSettings.title}
+            onRefresh={t.handleRefreshAiTitles}
+          />
+
+          <div className="xx-title-ai-toggle">
+            <span className="xx-toggle-label">AI 自动选择标题</span>
+            <div className="xx-switch" onClick={t.toggleAiAutoSelect}>
+              <div className="xx-switch-knob" />
+            </div>
+          </div>
+
           <div className="xx-form-field">
-            <label>从标题库选择</label>
-            <Select
-              placeholder="请选择标题…"
+            <label>标题</label>
+            <AutoComplete
+              placeholder="输入或从标题库选择…"
               allowClear
-              showSearch
+              maxLength={50}
               style={{ width: "100%" }}
               value={t.titleSettings.title || undefined}
               onChange={(val) => t.updateTitle(val || "")}
@@ -62,9 +95,10 @@ const Step4TitleSettings: React.FC<Step4TitleSettingsProps> = (props) => {
                 label: ut.content,
                 value: ut.content,
               }))}
-              filterOption={(input, option) =>
-                ((option?.label as string) || "").toLowerCase().includes(input.toLowerCase())
-              }
+              filterOption={(inputValue, option) => {
+                const title = (option?.label || option?.value || "") as string
+                return title.toLowerCase().includes((inputValue || "").toLowerCase())
+              }}
               notFoundContent={
                 t.userTitles.length === 0 ? (
                   <span style={{ color: "var(--text-tertiary)", fontSize: 13 }}>
@@ -74,33 +108,25 @@ const Step4TitleSettings: React.FC<Step4TitleSettingsProps> = (props) => {
               }
             />
           </div>
-          <div className="xx-form-field" style={{ marginTop: 14 }}>
-            <label>或手动输入</label>
-            <input
-              placeholder="输入自定义标题…"
-              value={t.titleSettings.title}
-              onChange={(e) => t.updateTitle(e.target.value)}
-              maxLength={50}
-            />
-          </div>
-
-          <TitleStylePanel
-            settings={t.titleSettings}
-            onUpdatePosition={t.updatePosition}
-            onUpdateFont={t.updateFont}
-            onUpdateSize={t.updateSize}
-            onToggleBold={t.toggleBold}
-            onToggleItalic={t.toggleItalic}
-            onToggleStroke={t.toggleStroke}
-            onToggleShadow={t.toggleShadow}
-            onApplyPreset={t.applyPreset}
-            activePreset={t.activePreset}
-            titlePresets={t.titlePresets}
-            POSITION_OPTIONS={POSITION_OPTIONS}
-            FONT_OPTIONS={FONT_OPTIONS}
-          />
         </>
       )}
+
+      {/* 样式面板始终可见，两种模式下都可调整标题展示样式 */}
+      <TitleStylePanel
+        settings={t.titleSettings}
+        onUpdatePosition={t.updatePosition}
+        onUpdateFont={t.updateFont}
+        onUpdateSize={t.updateSize}
+        onToggleBold={t.toggleBold}
+        onToggleItalic={t.toggleItalic}
+        onToggleStroke={t.toggleStroke}
+        onToggleShadow={t.toggleShadow}
+        onApplyPreset={t.applyPreset}
+        activePreset={t.activePreset}
+        titlePresets={t.titlePresets}
+        POSITION_OPTIONS={POSITION_OPTIONS}
+        FONT_OPTIONS={FONT_OPTIONS}
+      />
     </div>
   )
 }

apps/web/src/pages/generate/components/Step5VoiceSelect.tsx

@@ -1,137 +1,252 @@
 /**
  * Step 5 配音选择组件
+ * 展示用户已上传的配音素材，支持选中、预览播放
  */
-import React from "react"
-import type { VoiceClone } from "@/api/voice-clone"
-import { useStep5Voice } from "../hooks/useStep5Voice"
-import VoiceRecommendSection from "./voice/VoiceRecommendSection"
-import VoiceChoiceCard from "./voice/VoiceChoiceCard"
-import PresetVoiceDetail from "./voice/PresetVoiceDetail"
-import CustomVoicePanel from "./voice/CustomVoicePanel"
-import SaveVoiceModal from "./voice/SaveVoiceModal"
-import CloneVoiceSection from "./voice/CloneVoiceSection"
+import React, { useState, useRef, useCallback } from "react"
+import { useNavigate } from "react-router-dom"
+import { useQuery } from "@tanstack/react-query"
+import { AudioOutlined, SoundOutlined } from "@ant-design/icons"
+import { getAssetsByKind } from "@/api/assets"
+import type { AssetItem } from "@/api/assets"
 
 interface Step5VoiceSelectProps {
   selectedVoice: string
-  onSelectedVoiceChange: (voiceId: string) => void
-  voiceMode: "preset" | "custom" | "clone"
-  onVoiceModeChange: (mode: "preset" | "custom" | "clone") => void
-  selectedClonedVoice: string
-  onSelectedClonedVoiceChange: (voiceId: string) => void
-  clonedVoices: VoiceClone[]
-  addClone: (voice: VoiceClone) => void
-  hasProcessing: boolean
-  cloneModalOpen: boolean
-  onCloneModalOpenChange: (open: boolean) => void
-  titleText: string
+  onSelectedVoiceChange: (id: string) => void
 }
 
-const Step5VoiceSelect: React.FC<Step5VoiceSelectProps> = (props) => {
-  const v = useStep5Voice(props)
+/** 格式化时长 mm:ss */
+const formatDuration = (seconds?: number): string => {
+  if (!seconds || seconds <= 0) return "00:00"
+  const m = Math.floor(seconds / 60)
+  const s = Math.floor(seconds % 60)
+  return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`
+}
+
+/** 格式化文件大小 */
+const formatFileSize = (bytes?: number): string => {
+  if (!bytes || bytes <= 0) return "未知"
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`
+}
+
+const Step5VoiceSelect: React.FC<Step5VoiceSelectProps> = ({
+  selectedVoice,
+  onSelectedVoiceChange,
+}) => {
+  const navigate = useNavigate()
+  const [playingId, setPlayingId] = useState<string | null>(null)
+  const audioRef = useRef<HTMLAudioElement | null>(null)
+
+  // 获取用户上传的配音素材
+  const { data: materials = [], isLoading } = useQuery({
+    queryKey: ["assets", "voice"],
+    queryFn: () => getAssetsByKind("voice", { limit: 50 }),
+  })
+
+  /** 切换播放/暂停 */
+  const togglePlay = useCallback(
+    (material: AssetItem) => {
+      // 如果当前正在播放同一个素材，则暂停
+      if (playingId === material.id && audioRef.current) {
+        audioRef.current.pause()
+        setPlayingId(null)
+        return
+      }
+
+      // 停止之前的播放
+      if (audioRef.current) {
+        audioRef.current.pause()
+      }
+
+      // 创建新的 audio 元素播放
+      const audio = new Audio(material.file_url)
+      audioRef.current = audio
+      setPlayingId(material.id)
+
+      audio.onended = () => {
+        setPlayingId(null)
+        audioRef.current = null
+      }
+
+      audio.play().catch(() => {
+        setPlayingId(null)
+        audioRef.current = null
+      })
+    },
+    [playingId],
+  )
+
+  /** 选中素材 */
+  const handleSelect = useCallback(
+    (id: string) => {
+      onSelectedVoiceChange(id)
+    },
+    [onSelectedVoiceChange],
+  )
+
+  /** 跳转到配音库上传 */
+  const handleGoToUpload = useCallback(() => {
+    navigate("/app/voices")
+  }, [navigate])
+
+  // 加载中状态
+  if (isLoading) {
+    return (
+      <div className="xx-form-section">
+        <h3>🎙️ 选择配音</h3>
+        <div style={{ textAlign: "center", padding: "40px 0", color: "#999" }}>
+          加载配音素材中...
+        </div>
+      </div>
+    )
+  }
+
+  // 空状态
+  if (materials.length === 0) {
+    return (
+      <div className="xx-form-section">
+        <h3>🎙️ 选择配音</h3>
+        <div
+          style={{
+            textAlign: "center",
+            padding: "60px 0",
+            color: "#999",
+          }}
+        >
+          <AudioOutlined style={{ fontSize: 48, color: "#d9d9d9", marginBottom: 16 }} />
+          <p style={{ fontSize: 16, marginBottom: 16 }}>暂无配音素材</p>
+          <button
+            type="button"
+            onClick={handleGoToUpload}
+            style={{
+              padding: "8px 24px",
+              background: "#1677ff",
+              color: "#fff",
+              border: "none",
+              borderRadius: 6,
+              cursor: "pointer",
+              fontSize: 14,
+            }}
+          >
+            去配音库上传
+          </button>
+        </div>
+      </div>
+    )
+  }
 
   return (
     <div className="xx-form-section">
       <h3>🎙️ 选择配音</h3>
+      <p style={{ color: "#666", marginBottom: 16, fontSize: 14 }}>
+        从配音库中选择已上传的素材，点击卡片可预览播放
+      </p>
+      <div
+        style={{
+          display: "grid",
+          gridTemplateColumns: "repeat(auto-fill, minmax(220px, 1fr))",
+          gap: 12,
+        }}
+      >
+        {materials.map((item) => {
+          const isSelected = selectedVoice === item.id
+          const isPlaying = playingId === item.id
 
-      <VoiceRecommendSection
-        presetVoices={v.presetVoices}
-        voiceRecommendLoading={v.voiceRecommendLoading}
-        voiceRecommendations={v.voiceRecommendations}
-        hasVoiceRecommend={v.hasVoiceRecommend}
-        onRecommend={v.handleVoiceRecommend}
-        onSelectVoice={v.handleSelectRecommendedVoice}
-        selectedVoiceId={v.selectedVoice}
-        voiceMode={v.voiceMode}
-        VOICE_GENDER_ICON={v.VOICE_GENDER_ICON}
-      />
+          return (
+            <div
+              key={item.id}
+              onClick={() => handleSelect(item.id)}
+              style={{
+                padding: 16,
+                borderRadius: 8,
+                border: isSelected ? "2px solid #1677ff" : "1px solid #e8e8e8",
+                background: isSelected ? "#e6f4ff" : "#fff",
+                cursor: "pointer",
+                transition: "all 0.2s",
+                display: "flex",
+                flexDirection: "column",
+                gap: 8,
+              }}
+            >
+              {/* 顶部：图标 + 播放按钮 */}
+              <div
+                style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}
+              >
+                <div
+                  style={{
+                    width: 40,
+                    height: 40,
+                    borderRadius: 8,
+                    background: isSelected
+                      ? "linear-gradient(135deg, #1677ff, #4096ff)"
+                      : "linear-gradient(135deg, #f0f0f0, #e8e8e8)",
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                  }}
+                >
+                  <AudioOutlined style={{ fontSize: 20, color: isSelected ? "#fff" : "#666" }} />
+                </div>
+                {item.file_url && (
+                  <button
+                    type="button"
+                    onClick={(e) => {
+                      e.stopPropagation()
+                      togglePlay(item)
+                    }}
+                    style={{
+                      width: 32,
+                      height: 32,
+                      borderRadius: "50%",
+                      border: "none",
+                      background: isPlaying ? "#ff4d4f" : "#1677ff",
+                      color: "#fff",
+                      cursor: "pointer",
+                      display: "flex",
+                      alignItems: "center",
+                      justifyContent: "center",
+                      fontSize: 14,
+                    }}
+                    title={isPlaying ? "暂停" : "播放"}
+                  >
+                    <SoundOutlined />
+                  </button>
+                )}
+              </div>
 
-      <div className="xx-divider">
-        <span>全部音色</span>
+              {/* 名称 */}
+              <div
+                style={{
+                  fontSize: 14,
+                  fontWeight: 500,
+                  color: "#333",
+                  overflow: "hidden",
+                  textOverflow: "ellipsis",
+                  whiteSpace: "nowrap",
+                }}
+                title={item.name}
+              >
+                {item.name}
+              </div>
+
+              {/* 时长 + 大小 */}
+              <div
+                style={{
+                  display: "flex",
+                  justifyContent: "space-between",
+                  fontSize: 12,
+                  color: "#999",
+                }}
+              >
+                <span>{formatDuration(item.duration)}</span>
+                <span>{formatFileSize(item.file_size)}</span>
+              </div>
+            </div>
+          )
+        })}
       </div>
-
-      <div className="xx-voice-choice-list" style={{ marginBottom: 16 }}>
-        {v.presetVoices.slice(0, 3).map((pv) => (
-          <VoiceChoiceCard
-            key={pv.voice_id}
-            selected={v.voiceMode === "preset" && v.selectedVoice === pv.voice_id}
-            onClick={() => v.handleSelectPresetVoice(pv.voice_id)}
-            avatar={v.VOICE_GENDER_ICON[pv.gender] ?? "✨"}
-            title={pv.name}
-            description={pv.description}
-          />
-        ))}
-        {v.presetVoicesLoading && (
-          <VoiceChoiceCard
-            selected={false}
-            onClick={() => {}}
-            avatar="⏳"
-            title="加载中…"
-            loading
-          />
-        )}
-        <VoiceChoiceCard
-          selected={v.voiceMode === "clone"}
-          onClick={v.handleSelectCloneVoice}
-          avatar="🎤"
-          title="克隆我的声音"
-          description="上传语音样本克隆"
-          avatarStyle={{ background: "linear-gradient(135deg, #10b981, #059669)" }}
-        />
-      </div>
-
-      {v.voiceMode === "preset" && (
-        <PresetVoiceDetail
-          presetVoices={v.presetVoices}
-          selectedVoice={v.selectedVoice}
-          onSelect={v.handleSelectPresetVoice}
-          playingVoice={v.playingVoice}
-          onTogglePlay={v.toggleVoicePlay}
-          presetVoicesLoading={v.presetVoicesLoading}
-        />
-      )}
-
-      {v.voiceMode === "custom" && (
-        <>
-          <CustomVoicePanel
-            customVoiceText={v.customVoiceText}
-            onTextChange={v.setCustomVoiceText}
-            synthesizePending={v.synthesizeMutation.isPending}
-            onSynthesize={v.handleSynthesizeVoice}
-            ttsError={v.ttsError}
-            customAudioUrl={v.customAudioUrl}
-            completedTtsJobId={v.completedTtsJobId}
-            onOpenSaveModal={v.handleOpenSaveModal}
-          />
-          <SaveVoiceModal
-            open={v.saveModalOpen}
-            onClose={() => v.setSaveModalOpen(false)}
-            saveName={v.saveName}
-            onNameChange={v.setSaveName}
-            saveTagIds={v.saveTagIds}
-            onTagIdsChange={v.setSaveTagIds}
-            saveNewTag={v.saveNewTag}
-            onNewTagChange={v.setSaveNewTag}
-            onAddTag={v.handleAddTagInModal}
-            allTags={v.allTags}
-            savePending={v.saveToLibraryMutation.isPending}
-            onConfirm={v.handleConfirmSave}
-          />
-        </>
-      )}
-
-      {v.voiceMode === "clone" && (
-        <CloneVoiceSection
-          clonedVoices={v.clonedVoices}
-          hasProcessing={v.hasProcessing}
-          selectedClonedVoice={v.selectedClonedVoice}
-          onSelect={v.handleSelectClonedVoice}
-          onOpenCloneModal={v.handleOpenCloneModal}
-          playingVoiceId={v.playingCloneVoice}
-          onPlaySample={v.handlePlayCloneSample}
-          CLONE_STATUS_CONFIG={v.CLONE_STATUS_CONFIG}
-          formatDuration={v.formatDuration}
-        />
-      )}
     </div>
   )
 }

apps/web/src/pages/generate/components/Step6CoverSettings.tsx

@@ -1,4 +1,4 @@
-import React from "react"
+import React, { useEffect, useRef } from "react"
 import type { CoverConfig } from "../../editing-planner/types"
 import { useStep6Cover } from "../hooks/useStep6Cover"
 import { CoverModeSelector } from "./cover-settings/CoverModeSelector"
@@ -9,6 +9,10 @@ interface Step6CoverSettingsProps {
   coverSettings: CoverConfig
   onCoverSettingsChange: (settings: CoverConfig) => void
   duration: number
+  /** 当前素材 ID 列表，用于智能封面生成 */
+  assetIds?: string[]
+  /** 当前选中的模板 ID */
+  selectedTemplate?: string
 }
 
 const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
@@ -19,10 +23,47 @@ const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
     setMode,
     setFrameTime,
     handleUpload,
+    generateAutoCover,
     totalDuration,
     COVER_MODE_LABELS,
     COVER_MODE_ICONS,
-  } = useStep6Cover(props)
+  } = useStep6Cover({
+    coverSettings: props.coverSettings,
+    onCoverSettingsChange: props.onCoverSettingsChange,
+    duration: props.duration,
+    assetIds: props.assetIds,
+    selectedTemplate: props.selectedTemplate,
+  })
+
+  // 进入 auto 模式时自动触发智能封面生成
+  const autoTriggeredRef = useRef(false)
+  useEffect(() => {
+    // 切换模式、禁用封面或素材变更时重置触发标记
+    if (coverSettings.mode !== "auto" || !coverSettings.enabled) {
+      autoTriggeredRef.current = false
+      return
+    }
+    // 有素材且未生成过封面时自动触发
+    if (
+      coverSettings.mode === "auto" &&
+      !coverSettings.thumbnail_url &&
+      !autoTriggeredRef.current &&
+      props.assetIds &&
+      props.assetIds.length > 0
+    ) {
+      autoTriggeredRef.current = true
+      generateAutoCover()
+    }
+  }, [
+    coverSettings.enabled,
+    coverSettings.mode,
+    coverSettings.thumbnail_url,
+    generateAutoCover,
+    props.assetIds,
+  ])
+
+  // 预览图：优先 thumbnail_url，其次 upload_url
+  const previewUrl = coverSettings.thumbnail_url || coverSettings.upload_url
 
   return (
     <div className="xx-form-section">
@@ -52,9 +93,6 @@ const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
 
           {coverSettings.mode === "auto" && (
             <div className="xx-cover-auto">
-              <div className="xx-cover-auto-desc">
-                AI 将分析视频内容，自动选择最具吸引力的画面作为封面。
-              </div>
               <div className="xx-cover-auto-badge">
                 <span style={{ fontSize: 24 }}>🤖</span>
                 <span>AI 智能选帧</span>
@@ -77,21 +115,21 @@ const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
 
           <div className="xx-section-title">封面预览</div>
           <div className="xx-cover-preview-box">
-            {coverSettings.upload_url ? (
-              <img src={coverSettings.upload_url} alt="封面预览" className="xx-cover-preview-img" />
+            {previewUrl ? (
+              <img src={previewUrl} alt="封面预览" className="xx-cover-preview-img" />
             ) : (
               <div className="xx-cover-preview-placeholder">
                 <span style={{ fontSize: 28 }}>🖼️</span>
                 <span>
                   {coverSettings.mode === "auto"
-                    ? "AI 智能选择"
+                    ? "AI 正在选择..."
                     : coverSettings.mode === "frame"
                       ? `帧 ${formatTime(coverSettings.frame_time)}`
                       : "未上传封面"}
                 </span>
               </div>
             )}
-            <div className="xx-cover-preview-ratio">16:9</div>
+            <div className="xx-cover-preview-ratio">9:16</div>
           </div>
         </>
       )}

apps/web/src/pages/generate/components/material/ManualMaterialList.tsx

@@ -1,7 +1,7 @@
 /**
  * 手动选择素材列表
  */
-import React from "react"
+import React, { useRef, useCallback } from "react"
 import { Typography } from "antd"
 import type { AssetItem } from "@/api/assets"
 
@@ -20,6 +20,33 @@ const ManualMaterialList: React.FC<ManualMaterialListProps> = ({
   selectedMaterials,
   onToggle,
 }) => {
+  // 追踪当前正在播放的视频元素，确保同时只有一个视频播放
+  const activeVideoRef = useRef<HTMLVideoElement | null>(null)
+
+  const handleVideoMouseEnter = useCallback((e: React.MouseEvent<HTMLVideoElement>) => {
+    const video = e.currentTarget
+    // 暂停之前正在播放的视频（检查是否仍在 DOM 中）
+    if (
+      activeVideoRef.current &&
+      activeVideoRef.current !== video &&
+      document.body.contains(activeVideoRef.current)
+    ) {
+      activeVideoRef.current.pause()
+      activeVideoRef.current.currentTime = 0
+    }
+    activeVideoRef.current = video
+    video.play().catch(() => {})
+  }, [])
+
+  const handleVideoMouseLeave = useCallback((e: React.MouseEvent<HTMLVideoElement>) => {
+    const video = e.currentTarget
+    video.pause()
+    video.currentTime = 0
+    if (activeVideoRef.current === video) {
+      activeVideoRef.current = null
+    }
+  }, [])
+
   return (
     <div style={{ marginTop: 14 }}>
       {materialsLoading ? (
@@ -32,6 +59,8 @@ const ManualMaterialList: React.FC<ManualMaterialListProps> = ({
         <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
           {materials.items.map((m) => {
             const checked = selectedMaterials.includes(m.id)
+            const isVideo = m.mime_type?.startsWith("video/") ?? false
+            const thumbSrc = m.thumbnail_url || undefined
             return (
               <label
                 key={m.id}
@@ -53,13 +82,103 @@ const ManualMaterialList: React.FC<ManualMaterialListProps> = ({
                   type="checkbox"
                   checked={checked}
                   onChange={() => onToggle(m.id)}
-                  style={{ accentColor: "var(--primary-color, #4f46e5)" }}
+                  style={{
+                    accentColor: "var(--primary-color, #4f46e5)",
+                    flexShrink: 0,
+                  }}
                 />
+                {/* 缩略图预览 48×48 */}
+                <div
+                  style={{
+                    width: 48,
+                    height: 48,
+                    borderRadius: 6,
+                    overflow: "hidden",
+                    background: "#e2e8f0",
+                    flexShrink: 0,
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                  }}
+                >
+                  {isVideo && m.file_url ? (
+                    <video
+                      src={m.file_url}
+                      poster={m.thumbnail_url || undefined}
+                      muted
+                      loop
+                      playsInline
+                      preload="none"
+                      onMouseEnter={handleVideoMouseEnter}
+                      onMouseLeave={handleVideoMouseLeave}
+                      style={{
+                        width: "100%",
+                        height: "100%",
+                        objectFit: "cover",
+                        cursor: "pointer",
+                      }}
+                    />
+                  ) : thumbSrc ? (
+                    <img
+                      src={thumbSrc}
+                      alt={m.name}
+                      style={{
+                        width: "100%",
+                        height: "100%",
+                        objectFit: "cover",
+                      }}
+                      onError={(e) => {
+                        const target = e.target as HTMLImageElement
+                        target.style.display = "none"
+                        const fallback = target.nextElementSibling as HTMLElement | null
+                        if (fallback) fallback.style.display = "flex"
+                      }}
+                    />
+                  ) : null}
+                  {!thumbSrc && !isVideo && (
+                    <span
+                      style={{
+                        fontSize: 20,
+                        opacity: 0.5,
+                        display: "flex",
+                      }}
+                    >
+                      🎵
+                    </span>
+                  )}
+                  {!thumbSrc && isVideo && !m.file_url && (
+                    <span
+                      style={{
+                        fontSize: 20,
+                        opacity: 0.5,
+                        display: "flex",
+                      }}
+                    >
+                      🎬
+                    </span>
+                  )}
+                  {/* img onError 时显示的 fallback（初始隐藏） */}
+                  {thumbSrc && !(isVideo && m.file_url) && (
+                    <span
+                      style={{
+                        fontSize: 20,
+                        opacity: 0.5,
+                        display: "none",
+                      }}
+                    >
+                      {isVideo ? "🎬" : "🎵"}
+                    </span>
+                  )}
+                </div>
                 <span
                   style={{
                     fontSize: 13,
                     color: "var(--text-primary)",
                     flex: 1,
+                    minWidth: 0,
+                    overflow: "hidden",
+                    textOverflow: "ellipsis",
+                    whiteSpace: "nowrap",
                   }}
                 >
                   {m.name}
@@ -68,9 +187,10 @@ const ManualMaterialList: React.FC<ManualMaterialListProps> = ({
                   style={{
                     fontSize: 11,
                     color: "var(--text-tertiary, #94a3b8)",
+                    flexShrink: 0,
                   }}
                 >
-                  {m.mime_type.split("/")[1].toUpperCase()}
+                  {m.mime_type?.split("/")?.[1]?.toUpperCase() ?? "FILE"}
                 </span>
               </label>
             )

apps/web/src/pages/generate/components/material/SmartMatchCard.tsx

@@ -1,30 +1,24 @@
 /**
- * 单个智能匹配卡片
+ * 智能匹配卡片（Q5 简化版）
+ * 只展示素材缩略图、名称、时长，无匹配分数
  */
 import React from "react"
 import { PlayCircleOutlined, CheckCircleFilled } from "@ant-design/icons"
 import type { AssetItem } from "@/api/assets"
 
-interface SmartMatchResultItem {
-  asset: AssetItem
-  matchScore: number
-  matchReason: string
-}
-
 interface SmartMatchCardProps {
-  result: SmartMatchResultItem
+  asset: AssetItem
   selected: boolean
   onClick: () => void
   formatDuration: (seconds: number) => string
 }
 
 const SmartMatchCard: React.FC<SmartMatchCardProps> = ({
-  result,
+  asset,
   selected,
   onClick,
   formatDuration,
 }) => {
-  const { asset, matchScore, matchReason } = result
   return (
     <div className={`xx-smart-match-card ${selected ? "selected" : ""}`} onClick={onClick}>
       {/* 缩略图 */}
@@ -36,7 +30,6 @@ const SmartMatchCard: React.FC<SmartMatchCardProps> = ({
             <PlayCircleOutlined style={{ fontSize: 32, opacity: 0.5 }} />
           </div>
         )}
-        <div className="xx-smart-match-score">{matchScore}%</div>
         {selected && (
           <div className="xx-smart-match-check">
             <CheckCircleFilled style={{ fontSize: 20, color: "#fff" }} />
@@ -46,12 +39,11 @@ const SmartMatchCard: React.FC<SmartMatchCardProps> = ({
           <div className="xx-smart-match-duration">{formatDuration(asset.duration)}</div>
         )}
       </div>
-      {/* 信息区 */}
+      {/* 名称 */}
       <div className="xx-smart-match-info">
         <div className="xx-smart-match-name" title={asset.name}>
           {asset.name}
         </div>
-        <div className="xx-smart-match-reason">🎯 {matchReason}</div>
       </div>
     </div>
   )

apps/web/src/pages/generate/components/material/SmartMatchInput.tsx

@@ -1,13 +1,11 @@
 /**
- * 智能匹配输入区
- * textarea + 提示 + 按钮组
+ * 智能匹配操作区（Q5 简化版）
+ * 一键触发 AI 选素材，无需输入描述
  */
 import React from "react"
-import { LoadingOutlined } from "@ant-design/icons"
+import { LoadingOutlined, ThunderboltOutlined } from "@ant-design/icons"
 
 interface SmartMatchInputProps {
-  inputValue: string
-  onInputChange: (value: string) => void
   matching: boolean
   onMatch: () => void
   hasMatched: boolean
@@ -17,8 +15,6 @@ interface SmartMatchInputProps {
 }
 
 const SmartMatchInput: React.FC<SmartMatchInputProps> = ({
-  inputValue,
-  onInputChange,
   matching,
   onMatch,
   hasMatched,
@@ -28,22 +24,9 @@ const SmartMatchInput: React.FC<SmartMatchInputProps> = ({
 }) => {
   return (
     <div className="xx-smart-match-input-area">
-      <label className="xx-smart-match-label">🤖 描述你想要的视频内容</label>
-      <textarea
-        className="xx-smart-match-input"
-        placeholder="例如：一个科技感十足的产品宣传视频，画面要有现代办公场景、团队协作、数据分析图表…"
-        value={inputValue}
-        onChange={(e) => onInputChange(e.target.value)}
-        rows={3}
-        onKeyDown={(e) => {
-          if (e.key === "Enter" && (e.ctrlKey || e.metaKey)) {
-            onMatch()
-          }
-        }}
-      />
-      <div className="xx-smart-match-input-footer">
+      <div className="xx-smart-match-action-row">
         <span className="xx-smart-match-tip">
-          {loading ? "扫描视频库中…" : `当前视频库共 ${materialsCount} 个素材可供匹配`}
+          {loading ? "扫描视频库中…" : `当前视频库共 ${materialsCount} 个素材`}
         </span>
         <div style={{ display: "flex", gap: 8 }}>
           {hasMatched && (
@@ -60,15 +43,18 @@ const SmartMatchInput: React.FC<SmartMatchInputProps> = ({
             type="button"
             className="xx-btn xx-btn-primary xx-btn-sm"
             onClick={onMatch}
-            disabled={matching || loading || !inputValue.trim()}
+            disabled={matching || loading}
           >
             {matching ? (
               <>
                 <LoadingOutlined style={{ marginRight: 6 }} />
-                匹配中…
+                AI 选择中…
               </>
             ) : (
-              "✨ 智能匹配"
+              <>
+                <ThunderboltOutlined style={{ marginRight: 6 }} />
+                {hasMatched ? "重新选择" : "让 AI 帮你选"}
+              </>
             )}
           </button>
         </div>

apps/web/src/pages/generate/components/material/SmartMatchResults.tsx

@@ -1,19 +1,14 @@
 /**
- * 智能匹配结果区（含加载/空状态/已选汇总）
+ * 智能匹配结果区（Q5 简化版）
+ * 直接展示 AI 选中的素材，无匹配分数和理由
  */
 import React from "react"
 import { LoadingOutlined } from "@ant-design/icons"
 import type { AssetItem } from "@/api/assets"
 import SmartMatchCard from "./SmartMatchCard"
 
-interface SmartMatchResultItem {
-  asset: AssetItem
-  matchScore: number
-  matchReason: string
-}
-
 interface SmartMatchResultsProps {
-  results: SmartMatchResultItem[]
+  matchedAssets: AssetItem[]
   selectedIds: string[]
   matching: boolean
   hasMatched: boolean
@@ -25,7 +20,7 @@ interface SmartMatchResultsProps {
 }
 
 const SmartMatchResults: React.FC<SmartMatchResultsProps> = ({
-  results,
+  matchedAssets,
   selectedIds,
   matching,
   hasMatched,
@@ -42,9 +37,9 @@ const SmartMatchResults: React.FC<SmartMatchResultsProps> = ({
         <LoadingOutlined
           style={{ fontSize: 32, color: "var(--primary-color)", marginBottom: 12 }}
         />
-        <div style={{ color: "var(--text-primary)", fontSize: 14 }}>AI 正在分析素材…</div>
+        <div style={{ color: "var(--text-primary)", fontSize: 14 }}>AI 正在为你选择素材…</div>
         <div style={{ color: "var(--text-tertiary)", fontSize: 12, marginTop: 4 }}>
-          正在根据描述从视频库中匹配最合适的素材
+          正在分析视频库，匹配最合适的素材
         </div>
       </div>
     )
@@ -56,20 +51,22 @@ const SmartMatchResults: React.FC<SmartMatchResultsProps> = ({
       <div className="xx-smart-match-empty">
         <div style={{ fontSize: 36, marginBottom: 8 }}>💡</div>
         <div style={{ color: "var(--text-secondary)", fontSize: 13 }}>
-          输入视频内容描述，点击「智能匹配」让 AI 帮你选素材
+          点击「让 AI 帮你选」，自动从视频库中选择最合适的素材
         </div>
       </div>
     )
   }
 
   // 无结果
-  if (results.length === 0) return null
+  if (matchedAssets.length === 0) return null
 
   return (
     <>
       <div className="xx-smart-match-results">
         <div className="xx-smart-match-results-header">
-          <span className="xx-smart-match-results-title">推荐素材 ({results.length}个)</span>
+          <span className="xx-smart-match-results-title">
+            AI 已选素材 ({matchedAssets.length}个)
+          </span>
           <div className="xx-smart-match-results-actions">
             <button type="button" className="xx-link-btn" onClick={onSelectAll}>
               全选
@@ -81,14 +78,14 @@ const SmartMatchResults: React.FC<SmartMatchResultsProps> = ({
           </div>
         </div>
         <div className="xx-smart-match-grid">
-          {results.map((result) => {
-            const isSelected = selectedIds.includes(result.asset.id)
+          {matchedAssets.map((asset) => {
+            const isSelected = selectedIds.includes(asset.id)
             return (
               <SmartMatchCard
-                key={result.asset.id}
-                result={result}
+                key={asset.id}
+                asset={asset}
                 selected={isSelected}
-                onClick={() => onToggle(result.asset.id)}
+                onClick={() => onToggle(asset.id)}
                 formatDuration={formatDuration}
               />
             )

apps/web/src/pages/generate/components/title/TitlePresetsGrid.tsx

@@ -13,9 +13,15 @@ interface TitlePresetsGridProps {
   presets: TitlePresetItem[]
   activePreset: string | null
   onApply: (presetKey: string) => void
+  fontFamily?: string
 }
 
-const TitlePresetsGrid: React.FC<TitlePresetsGridProps> = ({ presets, activePreset, onApply }) => {
+const TitlePresetsGrid: React.FC<TitlePresetsGridProps> = ({
+  presets,
+  activePreset,
+  onApply,
+  fontFamily,
+}) => {
   return (
     <div className="xx-title-presets-grid">
       {presets.map((p) => {
@@ -27,7 +33,10 @@ const TitlePresetsGrid: React.FC<TitlePresetsGridProps> = ({ presets, activePres
             onClick={() => onApply(p.key)}
             title={p.label}
           >
-            <span className="xx-title-preset-preview-text" style={p.previewStyle}>
+            <span
+              className="xx-title-preset-preview-text"
+              style={{ ...p.previewStyle, ...(fontFamily ? { fontFamily } : {}) }}
+            >
               标题
             </span>
             <span className="xx-title-preset-card-label">{p.label}</span>

apps/web/src/pages/generate/components/title/TitleStylePanel.tsx

@@ -107,6 +107,7 @@ const TitleStylePanel: React.FC<TitleStylePanelProps> = ({
           presets={titlePresets}
           activePreset={activePreset}
           onApply={onApplyPreset}
+          fontFamily={settings.font}
         />
       </div>
 

apps/web/src/pages/generate/constants.ts

@@ -31,9 +31,9 @@ export const VOICE_GENDER_ICON: Record<string, string> = {
 export const STEPS = [
   { key: 1, label: "选择模板" },
   { key: 2, label: "选择素材" },
-  { key: 3, label: "生成预览" },
-  { key: 4, label: "选择标题" },
-  { key: 5, label: "选择配音" },
+  { key: 3, label: "选择配音" },
+  { key: 4, label: "生成预览" },
+  { key: 5, label: "选择标题" },
   { key: 6, label: "选择封面" },
   { key: 7, label: "确认生成" },
 ]

apps/web/src/pages/generate/generate.css

@@ -891,7 +891,7 @@
 
 /* ── 视频预览 ── */
 .xx-preview-video {
-  aspect-ratio: 9 / 16;
+  aspect-ratio: 16 / 9;
   max-height: 400px;
   border-radius: var(--radius-md);
   background: linear-gradient(135deg, var(--color-gray-900), var(--color-primary-900));
@@ -1433,47 +1433,14 @@
   border-radius: 14px;
 }
 
-.xx-smart-match-label {
-  display: block;
-  font-size: 14px;
-  font-weight: 600;
-  color: var(--text-primary, #1e293b);
-  margin-bottom: 10px;
-}
-
-.xx-smart-match-input {
-  width: 100%;
-  min-height: 80px;
-  padding: 12px;
-  font-size: 13px;
-  line-height: 1.6;
-  color: var(--text-primary, #1e293b);
-  background: #fff;
-  border: 1px solid var(--border-primary, #e2e8f0);
-  border-radius: 10px;
-  resize: vertical;
-  box-sizing: border-box;
-  transition: border-color 0.2s;
-  font-family: inherit;
-}
-
-.xx-smart-match-input:focus {
-  outline: none;
-  border-color: var(--primary-color, #4f46e5);
-  box-shadow: 0 0 0 3px rgba(79, 70, 229, 0.1);
-}
-
-.xx-smart-match-input::placeholder {
-  color: var(--text-tertiary, #94a3b8);
-}
-
-.xx-smart-match-input-footer {
+.xx-smart-match-action-row {
   display: flex;
   justify-content: space-between;
   align-items: center;
-  margin-top: 10px;
 }
 
+/* textarea removed in Q5 */
+
 .xx-smart-match-tip {
   font-size: 12px;
   color: var(--text-tertiary, #94a3b8);
@@ -2389,6 +2356,8 @@
   background: var(--bg-tertiary);
   border-radius: var(--radius-lg);
   border: 2px dashed var(--border-color);
+  max-width: 320px;
+  margin: 0 auto;
 }
 
 .xx-preview-generate-hint {
@@ -2414,6 +2383,7 @@
   font-size: 14px;
 }
 
+
 /* ── 加载中状态 ── */
 .xx-preview-loading {
   text-align: center;
@@ -2421,6 +2391,8 @@
   background: var(--bg-tertiary);
   border-radius: var(--radius-lg);
   border: 1px solid var(--border-color);
+  max-width: 320px;
+  margin: 0 auto;
 }
 
 .xx-preview-loading-text {
@@ -2436,13 +2408,15 @@
   margin: 0;
 }
 
-/* ── 错误状态 ── */
+/* ── 错误状态（手机屏尺寸）── */
 .xx-preview-error {
   text-align: center;
   padding: 32px 20px;
   background: rgba(239, 68, 68, 0.06);
   border-radius: var(--radius-lg);
   border: 1px solid rgba(239, 68, 68, 0.2);
+  max-width: 320px;
+  margin: 0 auto;
 }
 
 .xx-preview-error-text {
@@ -2489,6 +2463,9 @@
   margin-bottom: 20px;
   font-size: 13px;
   color: var(--text-primary);
+  max-width: 320px;
+  margin-left: auto;
+  margin-right: auto;
 }
 
 .xx-preview-plan-card {
@@ -2603,6 +2580,16 @@
   z-index: 2;
 }
 
+/* ── 整体进度条（手机屏尺寸）── */
+.xx-preview-progress-bar {
+  max-width: 320px;
+  margin: 12px auto;
+  height: 6px;
+  background: var(--bg-tertiary);
+  border-radius: 3px;
+  overflow: hidden;
+}
+
 .xx-preview-progress-bar-wrap {
   width: 100%;
   height: 4px;
@@ -2680,7 +2667,7 @@
 .xx-preview-video-wrapper .xx-preview-video {
   max-width: 300px;
   width: 100%;
-  aspect-ratio: 9 / 16;
+  aspect-ratio: 16 / 9;
   margin-bottom: 0;
 }
 

apps/web/src/pages/generate/hooks/generate-video/buildPayload.ts

@@ -61,13 +61,23 @@ export const buildEditPlanPayload = (props: UseGenerateVideoProps) => {
  * 返回错误信息，通过则返回 null
  */
 export const validateGenerateInputs = (props: UseGenerateVideoProps): string | null => {
-  const { titleSettings, materialMode, selectedMaterials, voiceMode, selectedClonedVoice } = props
+  const {
+    titleSettings,
+    materialMode,
+    selectedMaterials,
+    smartSelectedIds,
+    voiceMode,
+    selectedClonedVoice,
+  } = props
 
-  if (!titleSettings.title.trim()) {
+  // AI 自动选择模式下，标题可以为空（后端会自行生成）
+  if (!titleSettings.aiAutoSelect && !titleSettings.title?.trim()) {
     return "请先选择或输入标题"
   }
-  if (materialMode === "manual" && selectedMaterials.length === 0) {
-    return "请至少选择一个素材"
+  // 无论手动还是自动模式，都必须有素材
+  const materialIds = materialMode === "auto" ? smartSelectedIds || [] : selectedMaterials || []
+  if (materialIds.length === 0) {
+    return materialMode === "auto" ? "AI 未匹配到素材，请手动选择素材后重试" : "请至少选择一个素材"
   }
   if (voiceMode === "clone" && !selectedClonedVoice) {
     return "请先选择一个克隆音色"

apps/web/src/pages/generate/hooks/step2-materials/useSmartMatch.ts

@@ -1,75 +1,88 @@
 import { useState, useCallback, useMemo } from "react"
 import { message } from "antd"
 import type { AssetItem } from "@/api/assets"
-import { SMART_MATCH_REASONS } from "../../constants"
-
-interface SmartMatchedResult {
-  asset: AssetItem
-  matchScore: number
-  matchReason: string
-}
+import { smartMatchAssets } from "@/api/assets"
 
 interface UseSmartMatchOptions {
+  libraryId: string
   materials: { items: AssetItem[]; total: number }
   smartSelectedIds: string[]
   onSmartSelectedIdsChange: (ids: string[]) => void
 }
 
 /**
- * 智能素材匹配 Hook
- * 封装 AI 匹配、换一批、全选/清空等逻辑
+ * 智能素材匹配 Hook（Q5 简化版）
+ * 用户不手动选素材时，一键调用后端 AI 选素材
+ * 后端统一选素材逻辑后续完善，当前先走前端流程简化
  */
 export function useSmartMatch({
+  libraryId,
   materials,
   smartSelectedIds,
   onSmartSelectedIdsChange,
 }: UseSmartMatchOptions) {
-  const [smartMatchInput, setSmartMatchInput] = useState("")
   const [smartMatching, setSmartMatching] = useState(false)
-  const [smartMatchedResults, setSmartMatchedResults] = useState<SmartMatchedResult[]>([])
   const [hasMatched, setHasMatched] = useState(false)
+  const [smartMatchedResults, setSmartMatchedResults] = useState<AssetItem[]>([])
 
-  /* ── 智能素材匹配 ── */
+  /* ── 一键智能匹配 ── */
   const handleSmartMatch = useCallback(async () => {
-    if (!smartMatchInput.trim()) {
-      message.warning("请先输入视频内容描述")
+    if (!libraryId) {
+      message.warning("请先选择视频库")
       return
     }
+
     if (materials.items.length === 0) {
       message.warning("当前视频库暂无素材")
       return
     }
 
     setSmartMatching(true)
-    setHasMatched(true)
 
-    // 模拟 AI 匹配延迟
-    await new Promise((resolve) => setTimeout(resolve, 1500))
+    try {
+      // 调用后端智能匹配 API
+      const result = await smartMatchAssets(libraryId)
+      const matchedIds = result.items?.map((a: AssetItem) => a.id) ?? []
 
-    // 从素材库中随机选取 5-8 个作为推荐结果
-    const shuffled = [...materials.items].sort(() => Math.random() - 0.5)
-    const count = Math.min(shuffled.length, 5 + Math.floor(Math.random() * 4))
-    const picked = shuffled.slice(0, count)
+      if (matchedIds.length > 0) {
+        onSmartSelectedIdsChange(matchedIds)
+        // 保存 API 返回的完整素材列表
+        const resolved = result.items?.length
+          ? result.items
+          : materials.items.filter((a) => matchedIds.includes(a.id))
+        setSmartMatchedResults(resolved)
+        setHasMatched(true)
+        message.success(`AI 已为你选择 ${matchedIds.length} 个素材`)
+      } else {
+        // 后端返回空结果，回退到全选
+        onSmartSelectedIdsChange(materials.items.map((a) => a.id))
+        setSmartMatchedResults(materials.items)
+        setHasMatched(true)
+        message.info("AI 暂未找到匹配素材，已全选当前库素材")
+      }
+    } catch {
+      // 后端 API 尚未就绪时，回退到全选当前库素材
+      onSmartSelectedIdsChange(materials.items.map((a) => a.id))
+      setSmartMatchedResults(materials.items)
+      setHasMatched(true)
+      message.info("已为你全选当前库素材（智能匹配功能即将上线）")
+    } finally {
+      setSmartMatching(false)
+    }
+  }, [libraryId, materials.items, onSmartSelectedIdsChange])
 
-    const results = picked.map((asset, idx) => ({
-      asset,
-      matchScore: Math.round(85 + Math.random() * 14), // 85-99 分
-      matchReason:
-        SMART_MATCH_REASONS[idx % SMART_MATCH_REASONS.length] +
-        (Math.random() > 0.5 ? "，画面质感优秀" : ""),
-    }))
+  const handleRefreshMatch = useCallback(async () => {
+    // 换一批 = 重新触发智能匹配
+    await handleSmartMatch()
+  }, [handleSmartMatch])
 
-    // 按匹配度从高到低排序
-    results.sort((a, b) => b.matchScore - a.matchScore)
+  const handleSelectAllMatched = useCallback(() => {
+    onSmartSelectedIdsChange(materials.items.map((a) => a.id))
+  }, [materials.items, onSmartSelectedIdsChange])
 
-    setSmartMatchedResults(results)
-    // 默认选中匹配度 >= 90 的素材
-    const defaultSelected = results.filter((r) => r.matchScore >= 90).map((r) => r.asset.id)
-    onSmartSelectedIdsChange(
-      defaultSelected.length > 0 ? defaultSelected : results.slice(0, 3).map((r) => r.asset.id),
-    )
-    setSmartMatching(false)
-  }, [smartMatchInput, materials.items, onSmartSelectedIdsChange])
+  const handleClearSmartSelect = useCallback(() => {
+    onSmartSelectedIdsChange([])
+  }, [onSmartSelectedIdsChange])
 
   const handleToggleSmartSelect = useCallback(
     (assetId: string) => {
@@ -82,57 +95,20 @@ export function useSmartMatch({
     [smartSelectedIds, onSmartSelectedIdsChange],
   )
 
-  const handleRefreshMatch = useCallback(async () => {
-    if (materials.items.length <= 5) {
-      message.info("视频库素材较少，无法换一批")
-      return
-    }
-    setSmartMatching(true)
-    await new Promise((resolve) => setTimeout(resolve, 800))
-
-    const remaining = materials.items.filter(
-      (m) => !smartMatchedResults.some((r) => r.asset.id === m.id),
-    )
-    const shuffled = [...remaining].sort(() => Math.random() - 0.5)
-    const count = Math.min(shuffled.length, 5 + Math.floor(Math.random() * 3))
-    const picked = shuffled.slice(0, count)
-
-    const results = picked.map((asset, idx) => ({
-      asset,
-      matchScore: Math.round(80 + Math.random() * 19),
-      matchReason:
-        SMART_MATCH_REASONS[(idx + 2) % SMART_MATCH_REASONS.length] +
-        (Math.random() > 0.5 ? "，节奏明快" : ""),
-    }))
-    results.sort((a, b) => b.matchScore - a.matchScore)
-
-    setSmartMatchedResults(results)
-    onSmartSelectedIdsChange([])
-    setSmartMatching(false)
-  }, [materials.items, smartMatchedResults, onSmartSelectedIdsChange])
-
-  const handleSelectAllMatched = useCallback(() => {
-    onSmartSelectedIdsChange(smartMatchedResults.map((r) => r.asset.id))
-  }, [smartMatchedResults, onSmartSelectedIdsChange])
-
-  const handleClearSmartSelect = useCallback(() => {
-    onSmartSelectedIdsChange([])
-  }, [onSmartSelectedIdsChange])
-
-  /* ── 计算已选智能匹配素材的总时长 ── */
-  const smartSelectedTotalDuration = useMemo(() => {
-    return smartMatchedResults
-      .filter((r) => smartSelectedIds.includes(r.asset.id))
-      .reduce((sum, r) => sum + (r.asset.duration || 0), 0)
-  }, [smartMatchedResults, smartSelectedIds])
+  /* ── 计算已选素材总时长 ── */
+  const smartSelectedTotalDuration = useMemo(
+    () =>
+      materials.items
+        .filter((a) => smartSelectedIds.includes(a.id))
+        .reduce((sum, a) => sum + (a.duration || 0), 0),
+    [materials.items, smartSelectedIds],
+  )
 
   return {
-    smartMatchInput,
-    setSmartMatchInput,
     smartMatching,
-    smartMatchedResults,
     hasMatched,
     smartSelectedIds,
+    smartMatchedResults,
     handleSmartMatch,
     handleToggleSmartSelect,
     handleRefreshMatch,

apps/web/src/pages/generate/hooks/useStep2Materials.ts

@@ -2,7 +2,7 @@
  * Step 2 素材选择 Hook
  * 组合素材库加载 + 智能匹配两个子 Hook
  */
-import { useCallback } from "react"
+import { useCallback, useEffect, useRef } from "react"
 import { formatDuration } from "../utils/formatDuration"
 import { useMaterialLibrary } from "./step2-materials/useMaterialLibrary"
 import { useSmartMatch } from "./step2-materials/useSmartMatch"
@@ -28,11 +28,31 @@ export function useStep2Materials({
     useMaterialLibrary()
 
   const smartMatch = useSmartMatch({
+    libraryId: selectedLibraryId,
     materials,
     smartSelectedIds,
     onSmartSelectedIdsChange,
   })
 
+  /* ── 自动触发智能匹配：选择视频库后自动调用 ── */
+  const autoTriggeredRef = useRef<string>("")
+  const { handleSmartMatch } = smartMatch
+  useEffect(() => {
+    // 离开 auto 模式时重置，确保下次进入 auto 模式能重新触发
+    if (materialMode !== "auto") {
+      autoTriggeredRef.current = ""
+      return
+    }
+    if (!selectedLibraryId) return
+    if (materialsLoading) return
+    if (materials.items.length === 0) return
+    // 防止同一视频库重复触发
+    if (autoTriggeredRef.current === selectedLibraryId) return
+
+    autoTriggeredRef.current = selectedLibraryId
+    handleSmartMatch()
+  }, [selectedLibraryId, materialMode, materialsLoading, materials.items, handleSmartMatch])
+
   /* ── 手动选择素材 ── */
   const handleToggleMaterial = useCallback(
     (materialId: string) => {
@@ -58,13 +78,11 @@ export function useStep2Materials({
     // 手动选择
     selectedMaterials,
     handleToggleMaterial,
-    // 智能匹配
-    smartMatchInput: smartMatch.smartMatchInput,
-    setSmartMatchInput: smartMatch.setSmartMatchInput,
+    // 智能匹配（简化版）
     smartMatching: smartMatch.smartMatching,
-    smartMatchedResults: smartMatch.smartMatchedResults,
     hasMatched: smartMatch.hasMatched,
     smartSelectedIds: smartMatch.smartSelectedIds,
+    smartMatchedResults: smartMatch.smartMatchedResults,
     handleSmartMatch: smartMatch.handleSmartMatch,
     handleToggleSmartSelect: smartMatch.handleToggleSmartSelect,
     handleRefreshMatch: smartMatch.handleRefreshMatch,

apps/web/src/pages/generate/hooks/useStep3Preview.ts

@@ -1,290 +0,0 @@
-/**
- * Step 3 生成预览 Hook
- * 调用 /generation/preview 接口创建预览任务，轮询状态直到完成
- */
-import { useState, useCallback, useMemo, useEffect, useRef } from "react"
-import { createPreview, getPreviewStatus } from "@/api/generation"
-import type { PreviewTaskResponse, PreviewStatus as ApiPreviewStatus } from "@/api/generation"
-import type { EditingTemplate } from "@/api/editing-planner"
-
-interface UseStep3PreviewProps {
-  templates: EditingTemplate[]
-  selectedTemplate: string
-  materialMode: "manual" | "auto"
-  selectedMaterials: string[]
-  smartSelectedIds: string[]
-  duration: number
-  videoRatio: string
-  titleText?: string
-  voiceId?: string
-}
-
-export type PreviewStatus = "idle" | "pending" | "generating" | "ready" | "error"
-
-/** 预览生成结果 */
-export interface PreviewResult {
-  taskId: string
-  videoUrl: string
-  clipCount: number
-  transitionCount: number
-  materialUsage: number
-  duration: number
-  fileSize: number
-  generateDuration: number
-  progress: number
-}
-
-// 轮询超时时间（10 分钟）
-const POLL_TIMEOUT_MS = 10 * 60 * 1000
-export function useStep3Preview({
-  templates,
-  selectedTemplate,
-  materialMode,
-  selectedMaterials,
-  smartSelectedIds,
-  duration,
-  videoRatio,
-}: UseStep3PreviewProps) {
-  const templateName = useMemo(
-    () => templates.find((t) => t.id === selectedTemplate)?.name ?? "未选择",
-    [templates, selectedTemplate],
-  )
-
-  const materialCount = useMemo(() => {
-    if (materialMode === "auto") {
-      return `${smartSelectedIds.length} 个素材（智能匹配）`
-    }
-    return `${selectedMaterials.length} 个素材`
-  }, [materialMode, selectedMaterials.length, smartSelectedIds.length])
-
-  const materialTotal = materialMode === "auto" ? smartSelectedIds.length : selectedMaterials.length
-
-  /* ── 预览生成状态 ── */
-  const [previewStatus, setPreviewStatus] = useState<PreviewStatus>("idle")
-  const [previewResult, setPreviewResult] = useState<PreviewResult | null>(null)
-  const [previewError, setPreviewError] = useState<string>("")
-  const [progress, setProgress] = useState(0)
-
-  // 任务 ID + 轮询定时器，用于防止竞态条件
-  const currentTaskIdRef = useRef<string | null>(null)
-  const pollTimerRef = useRef<ReturnType<typeof setTimeout>>()
-  const startTimeRef = useRef<number>(0)
-
-  const clearPollTimer = useCallback(() => {
-    if (pollTimerRef.current) {
-      clearTimeout(pollTimerRef.current)
-      pollTimerRef.current = undefined
-    }
-  }, [])
-
-  /* ── 参数变化时重置预览状态 ── */
-  const prevDepsRef = useRef({
-    selectedTemplate,
-    materialMode,
-    selectedMaterials: [...selectedMaterials].sort().join(","),
-    smartSelectedIds: [...smartSelectedIds].sort().join(","),
-    duration,
-    videoRatio,
-  })
-
-  useEffect(() => {
-    const currentKey = [
-      selectedTemplate,
-      materialMode,
-      [...selectedMaterials].sort().join(","),
-      [...smartSelectedIds].sort().join(","),
-      duration,
-      videoRatio,
-    ].join("|")
-
-    const prevKey = [
-      prevDepsRef.current.selectedTemplate,
-      prevDepsRef.current.materialMode,
-      prevDepsRef.current.selectedMaterials,
-      prevDepsRef.current.smartSelectedIds,
-      prevDepsRef.current.duration,
-      prevDepsRef.current.videoRatio,
-    ].join("|")
-
-    if (prevKey !== currentKey && previewStatus !== "idle") {
-      // 参数变化，作废当前任务
-      currentTaskIdRef.current = null
-      clearPollTimer()
-      setPreviewStatus("idle")
-      setPreviewResult(null)
-      setPreviewError("")
-      setProgress(0)
-    }
-
-    prevDepsRef.current = {
-      selectedTemplate,
-      materialMode,
-      selectedMaterials: [...selectedMaterials].sort().join(","),
-      smartSelectedIds: [...smartSelectedIds].sort().join(","),
-      duration,
-      videoRatio,
-    }
-  }, [
-    selectedTemplate,
-    materialMode,
-    selectedMaterials,
-    smartSelectedIds,
-    duration,
-    videoRatio,
-    previewStatus,
-    clearPollTimer,
-  ])
-
-  // 组件卸载时清理轮询
-  useEffect(() => {
-    return () => {
-      clearPollTimer()
-    }
-  }, [clearPollTimer])
-
-  /** 轮询预览任务状态 */
-  const pollPreviewStatus = useCallback((taskId: string) => {
-    const poll = async () => {
-      // 检查是否已被取消（参数变化或重新生成）
-      if (currentTaskIdRef.current !== taskId) return
-
-      // 超时检查
-      if (Date.now() - startTimeRef.current > POLL_TIMEOUT_MS) {
-        setPreviewError("预览生成超时，请重试")
-        setPreviewStatus("error")
-        return
-      }
-
-      try {
-        const data: PreviewTaskResponse = await getPreviewStatus(taskId)
-
-        if (currentTaskIdRef.current !== taskId) return
-
-        const status = data.status as ApiPreviewStatus
-
-        if (status === "completed") {
-          setProgress(100)
-          setPreviewResult({
-            taskId: data.task_id,
-            videoUrl: data.video_url ?? "",
-            clipCount: data.clip_count ?? 0,
-            transitionCount: data.transition_count ?? 0,
-            materialUsage: data.material_usage ?? 0,
-            duration: data.duration ?? 0,
-            fileSize: data.file_size ?? 0,
-            generateDuration: data.generate_duration ?? 0,
-            progress: 100,
-          })
-          setPreviewStatus("ready")
-          return
-        }
-
-        if (status === "failed") {
-          setPreviewError(data.error_message || "预览生成失败，请重试")
-          setPreviewStatus("error")
-          return
-        }
-
-        if (status === "cancelled") {
-          setPreviewError("预览任务已取消")
-          setPreviewStatus("error")
-          return
-        }
-
-        // pending / generating 状态继续轮询
-        setProgress(data.progress || 0)
-        if (status === "pending") {
-          setPreviewStatus("pending")
-          pollTimerRef.current = setTimeout(poll, 5000)
-        } else {
-          setPreviewStatus("generating")
-          pollTimerRef.current = setTimeout(poll, 2000)
-        }
-      } catch (pollErr) {
-        if (currentTaskIdRef.current !== taskId) return
-        // 轮询出错，延迟后重试
-        pollTimerRef.current = setTimeout(poll, 3000)
-      }
-    }
-
-    // 首次延迟 1 秒开始轮询
-    pollTimerRef.current = setTimeout(poll, 1000)
-  }, [])
-
-  /** 生成预览 */
-  const generatePreview = useCallback(async () => {
-    if (!selectedTemplate) {
-      setPreviewError("请先选择模板")
-      setPreviewStatus("error")
-      return
-    }
-    if (materialTotal === 0) {
-      setPreviewError("请先选择素材")
-      setPreviewStatus("error")
-      return
-    }
-
-    // 取消之前的轮询
-    clearPollTimer()
-
-    setPreviewStatus("pending")
-    setPreviewError("")
-    setProgress(0)
-    setPreviewResult(null)
-    startTimeRef.current = Date.now()
-
-    try {
-      const assetIds = materialMode === "auto" ? smartSelectedIds : selectedMaterials
-      const response = await createPreview({
-        template_id: selectedTemplate,
-        asset_ids: assetIds,
-        duration: duration || undefined,
-        video_ratio: videoRatio,
-      })
-
-      // 竞态检查
-      if (startTimeRef.current === 0) return // 已被重置
-
-      currentTaskIdRef.current = response.task_id
-      pollPreviewStatus(response.task_id)
-    } catch (e) {
-      setPreviewError(e instanceof Error ? e.message : "预览生成失败")
-      setPreviewStatus("error")
-    }
-  }, [
-    selectedTemplate,
-    materialTotal,
-    materialMode,
-    smartSelectedIds,
-    selectedMaterials,
-    duration,
-    videoRatio,
-    clearPollTimer,
-    pollPreviewStatus,
-  ])
-
-  /** 重新生成预览 */
-  const regeneratePreview = useCallback(() => {
-    generatePreview()
-  }, [generatePreview])
-
-  /** 是否可以下一步（预览已生成） */
-  const canProceed = previewStatus === "ready"
-
-  return {
-    templateName,
-    materialCount,
-    duration,
-    videoRatio,
-    // 预览生成状态
-    previewStatus,
-    previewResult,
-    previewError,
-    progress,
-    canProceed,
-    generatePreview,
-    regeneratePreview,
-  }
-}
-
-export default useStep3Preview

apps/web/src/pages/generate/hooks/useStep4Preview.ts

@@ -0,0 +1,430 @@
+/**
+ * Step 4 生成预览 Hook（支持多预览 + voice_ids）
+ * 调用 /generation/preview 接口创建多个预览任务，轮询状态直到全部完成
+ */
+import { useState, useCallback, useMemo, useEffect, useRef } from "react"
+import { createPreview, getPreviewStatus } from "@/api/generation"
+import type { PreviewTaskResponse, PreviewStatus as ApiPreviewStatus } from "@/api/generation"
+import type { EditingTemplate } from "@/api/editing-planner"
+import { safeExtractError } from "./generate-video/errorUtils"
+
+/** 安全地将值转为字符串，防止对象被直接渲染导致 React Error #31 */
+const safeString = (val: unknown, fallback: string): string => {
+  if (val == null) return fallback
+  const s = safeExtractError(val)
+  return s || fallback
+}
+
+/** 安全地将值转为数字，防止非数字值进入渲染 */
+const safeNumber = (val: unknown, fallback = 0): number => {
+  if (typeof val === "number" && !Number.isNaN(val)) return val
+  if (typeof val === "string") {
+    const n = Number(val)
+    return Number.isNaN(n) ? fallback : n
+  }
+  return fallback
+}
+
+interface UseStep4PreviewProps {
+  templates: EditingTemplate[]
+  selectedTemplate: string
+  materialMode: "manual" | "auto"
+  selectedMaterials: string[]
+  smartSelectedIds: string[]
+  duration: number
+  videoRatio: string
+  /** 配音 voice_ids（传给后端，让预览包含配音音频） */
+  voiceIds?: string[]
+  /** 要生成的预览数量 */
+  previewCount?: number
+}
+
+export type PreviewStatus = "idle" | "pending" | "generating" | "ready" | "error"
+
+/** 单个预览生成结果 */
+export interface PreviewResult {
+  taskId: string
+  videoUrl: string
+  clipCount: number
+  transitionCount: number
+  materialUsage: number
+  duration: number
+  fileSize: number
+  generateDuration: number
+  progress: number
+}
+
+/** 单个预览项的完整状态（用于多预览） */
+export interface PreviewItem {
+  index: number
+  status: PreviewStatus
+  result: PreviewResult | null
+  error: string
+  progress: number
+}
+
+// 轮询超时时间（10 分钟）
+const POLL_TIMEOUT_MS = 10 * 60 * 1000
+
+/** 初始单项状态 */
+const createInitialItem = (index: number): PreviewItem => ({
+  index,
+  status: "idle",
+  result: null,
+  error: "",
+  progress: 0,
+})
+
+export function useStep4Preview({
+  templates,
+  selectedTemplate,
+  materialMode,
+  selectedMaterials,
+  smartSelectedIds,
+  duration,
+  videoRatio,
+  voiceIds,
+  previewCount = 1,
+}: UseStep4PreviewProps) {
+  const templateName = useMemo(
+    () => templates.find((t) => t.id === selectedTemplate)?.name ?? "未选择",
+    [templates, selectedTemplate],
+  )
+
+  const materialCount = useMemo(() => {
+    if (materialMode === "auto") {
+      return `${smartSelectedIds.length} 个素材（智能匹配）`
+    }
+    return `${selectedMaterials.length} 个素材`
+  }, [materialMode, selectedMaterials.length, smartSelectedIds.length])
+
+  const materialTotal = materialMode === "auto" ? smartSelectedIds.length : selectedMaterials.length
+
+  /* ── 多预览状态 ── */
+  const [items, setItems] = useState<PreviewItem[]>(() =>
+    Array.from({ length: previewCount }, (_, i) => createInitialItem(i)),
+  )
+  const [selectedIndex, setSelectedIndex] = useState(0)
+
+  // 每个任务 ID + 轮询定时器，用于防止竞态条件（按 index 存储）
+  const taskIdsRef = useRef<Map<number, string>>(new Map())
+  const pollTimersRef = useRef<Map<number, ReturnType<typeof setTimeout>>>(new Map())
+  const startTimeRef = useRef<number>(0)
+
+  const clearPollTimer = useCallback((index?: number) => {
+    if (index !== undefined) {
+      const timer = pollTimersRef.current.get(index)
+      if (timer) {
+        clearTimeout(timer)
+        pollTimersRef.current.delete(index)
+      }
+    } else {
+      pollTimersRef.current.forEach((timer) => clearTimeout(timer))
+      pollTimersRef.current.clear()
+    }
+  }, [])
+
+  // 同步 previewCount 变化（增减项）
+  useEffect(() => {
+    setItems((prev) => {
+      if (prev.length === previewCount) return prev
+      if (prev.length > previewCount) return prev.slice(0, previewCount)
+      return [
+        ...prev,
+        ...Array.from({ length: previewCount - prev.length }, (_, i) =>
+          createInitialItem(prev.length + i),
+        ),
+      ]
+    })
+    // 如果 selectedIndex 超出范围，重置
+    setSelectedIndex((prev) => Math.min(prev, previewCount - 1))
+  }, [previewCount])
+
+  /* ── 参数变化时重置所有预览状态 ── */
+  const prevDepsRef = useRef({
+    selectedTemplate,
+    materialMode,
+    selectedMaterials: [...selectedMaterials].sort().join(","),
+    smartSelectedIds: [...smartSelectedIds].sort().join(","),
+    duration,
+    videoRatio,
+    voiceIds: [...(voiceIds || [])].sort().join(","),
+  })
+
+  useEffect(() => {
+    const currentKey = [
+      selectedTemplate,
+      materialMode,
+      [...selectedMaterials].sort().join(","),
+      [...smartSelectedIds].sort().join(","),
+      duration,
+      videoRatio,
+      [...(voiceIds || [])].sort().join(","),
+    ].join("|")
+
+    const prevKey = [
+      prevDepsRef.current.selectedTemplate,
+      prevDepsRef.current.materialMode,
+      prevDepsRef.current.selectedMaterials,
+      prevDepsRef.current.smartSelectedIds,
+      prevDepsRef.current.duration,
+      prevDepsRef.current.videoRatio,
+      prevDepsRef.current.voiceIds,
+    ].join("|")
+
+    if (prevKey !== currentKey && items.some((it) => it.status !== "idle")) {
+      taskIdsRef.current.clear()
+      clearPollTimer()
+      setItems(Array.from({ length: previewCount }, (_, i) => createInitialItem(i)))
+      setSelectedIndex(0)
+    }
+
+    prevDepsRef.current = {
+      selectedTemplate,
+      materialMode,
+      selectedMaterials: [...selectedMaterials].sort().join(","),
+      smartSelectedIds: [...smartSelectedIds].sort().join(","),
+      duration,
+      videoRatio,
+      voiceIds: [...(voiceIds || [])].sort().join(","),
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    selectedTemplate,
+    materialMode,
+    selectedMaterials,
+    smartSelectedIds,
+    duration,
+    videoRatio,
+    voiceIds,
+    previewCount,
+  ])
+
+  // 组件卸载时清理所有轮询
+  useEffect(() => {
+    return () => {
+      clearPollTimer()
+    }
+  }, [clearPollTimer])
+
+  /** 轮询单个预览任务状态 */
+  const pollPreviewStatus = useCallback((index: number, taskId: string) => {
+    const poll = async () => {
+      // 竞态检查
+      if (taskIdsRef.current.get(index) !== taskId) return
+
+      // 超时检查
+      if (Date.now() - startTimeRef.current > POLL_TIMEOUT_MS) {
+        setItems((prev) =>
+          prev.map((it) =>
+            it.index === index ? { ...it, status: "error", error: "预览生成超时，请重试" } : it,
+          ),
+        )
+        return
+      }
+
+      try {
+        const data: PreviewTaskResponse = await getPreviewStatus(taskId)
+
+        if (taskIdsRef.current.get(index) !== taskId) return
+
+        const status = data.status as ApiPreviewStatus
+
+        if (status === "completed") {
+          const result: PreviewResult = {
+            taskId: safeString(data.task_id, ""),
+            videoUrl: safeString(data.video_url, ""),
+            clipCount: safeNumber(data.clip_count),
+            transitionCount: safeNumber(data.transition_count),
+            materialUsage: safeNumber(data.material_usage),
+            duration: safeNumber(data.duration),
+            fileSize: safeNumber(data.file_size),
+            generateDuration: safeNumber(data.generate_duration),
+            progress: 100,
+          }
+          setItems((prev) =>
+            prev.map((it) =>
+              it.index === index ? { ...it, status: "ready", result, progress: 100 } : it,
+            ),
+          )
+          return
+        }
+
+        if (status === "failed") {
+          setItems((prev) =>
+            prev.map((it) =>
+              it.index === index
+                ? {
+                    ...it,
+                    status: "error",
+                    error: safeString(data.error_message, "预览生成失败，请重试"),
+                  }
+                : it,
+            ),
+          )
+          return
+        }
+
+        if (status === "cancelled") {
+          setItems((prev) =>
+            prev.map((it) =>
+              it.index === index ? { ...it, status: "error", error: "预览任务已取消" } : it,
+            ),
+          )
+          return
+        }
+
+        // pending / generating 状态继续轮询
+        const prog = safeNumber(data.progress)
+        const nextStatus: PreviewStatus = status === "pending" ? "pending" : "generating"
+        setItems((prev) =>
+          prev.map((it) =>
+            it.index === index ? { ...it, status: nextStatus, progress: prog } : it,
+          ),
+        )
+        const delay = status === "pending" ? 5000 : 2000
+        pollTimersRef.current.set(index, setTimeout(poll, delay))
+      } catch {
+        if (taskIdsRef.current.get(index) !== taskId) return
+        pollTimersRef.current.set(index, setTimeout(poll, 3000))
+      }
+    }
+
+    pollTimersRef.current.set(index, setTimeout(poll, 1000))
+  }, [])
+
+  /** 生成所有预览 */
+  const generatePreview = useCallback(async () => {
+    if (!selectedTemplate) {
+      setItems((prev) => prev.map((it) => ({ ...it, status: "error", error: "请先选择模板" })))
+      return
+    }
+    if (materialTotal === 0) {
+      setItems((prev) => prev.map((it) => ({ ...it, status: "error", error: "请先选择素材" })))
+      return
+    }
+
+    // 取消之前的所有轮询
+    clearPollTimer()
+    taskIdsRef.current.clear()
+
+    // 初始化所有项为 pending
+    setItems(
+      Array.from({ length: previewCount }, (_, i) => ({
+        index: i,
+        status: "pending" as PreviewStatus,
+        result: null,
+        error: "",
+        progress: 0,
+      })),
+    )
+    setSelectedIndex(0)
+    startTimeRef.current = Date.now()
+
+    const assetIds = materialMode === "auto" ? smartSelectedIds : selectedMaterials
+
+    // 并发创建所有预览任务（Promise.all 并行请求，减少串行等待）
+    const createTasks = Array.from({ length: previewCount }, async (_, i) => {
+      try {
+        const response = await createPreview({
+          template_id: selectedTemplate,
+          asset_ids: assetIds,
+          duration: duration || undefined,
+          video_ratio: videoRatio,
+          voice_ids: voiceIds && voiceIds.length > 0 ? voiceIds : undefined,
+        })
+
+        if (startTimeRef.current === 0) return
+
+        taskIdsRef.current.set(i, response.task_id)
+        pollPreviewStatus(i, response.task_id)
+      } catch (e) {
+        const errMsg = safeString(e instanceof Error ? e.message : e, "预览生成失败")
+        setItems((prev) =>
+          prev.map((it) => (it.index === i ? { ...it, status: "error", error: errMsg } : it)),
+        )
+      }
+    })
+    await Promise.all(createTasks)
+  }, [
+    selectedTemplate,
+    materialTotal,
+    materialMode,
+    smartSelectedIds,
+    selectedMaterials,
+    duration,
+    videoRatio,
+    voiceIds,
+    previewCount,
+    clearPollTimer,
+    pollPreviewStatus,
+  ])
+
+  /** 重新生成所有预览 */
+  const regeneratePreview = useCallback(() => {
+    generatePreview()
+  }, [generatePreview])
+
+  /** 是否所有预览都已完成 */
+  const allReady = items.length > 0 && items.every((it) => it.status === "ready")
+  /** 是否至少有一个预览已完成 */
+  const anyReady = items.some((it) => it.status === "ready")
+  /** 是否有任一正在生成中 */
+  const anyGenerating = items.some((it) => it.status === "pending" || it.status === "generating")
+
+  /** 当前选中的预览结果 */
+  const selectedResult = items[selectedIndex]?.result ?? null
+
+  /** 综合状态（兼容旧逻辑） */
+  const previewStatus: PreviewStatus = useMemo(() => {
+    if (items.every((it) => it.status === "idle")) return "idle"
+    if (items.some((it) => it.status === "pending" || it.status === "generating"))
+      return "generating"
+    if (allReady) return "ready"
+    if (items.every((it) => it.status === "error")) return "error"
+    // 部分完成部分出错
+    if (anyReady) return "ready"
+    return "error"
+  }, [items, allReady, anyReady])
+
+  /** 综合进度（取平均） */
+  const progress = useMemo(() => {
+    if (items.length === 0) return 0
+    return Math.round(items.reduce((sum, it) => sum + it.progress, 0) / items.length)
+  }, [items])
+
+  /** 综合错误信息 */
+  const previewError = useMemo(() => {
+    const errorItems = items.filter((it) => it.status === "error" && it.error)
+    if (errorItems.length === 0) return ""
+    if (errorItems.length === 1) return errorItems[0].error
+    return `${errorItems.length} 个预览生成失败`
+  }, [items])
+
+  const canProceed = anyReady
+
+  return {
+    templateName,
+    materialCount,
+    duration,
+    videoRatio,
+    // 多预览状态
+    items,
+    selectedIndex,
+    setSelectedIndex,
+    previewCount,
+    // 综合状态
+    previewStatus,
+    previewResult: selectedResult,
+    previewError,
+    progress,
+    canProceed,
+    allReady,
+    anyReady,
+    anyGenerating,
+    generatePreview,
+    regeneratePreview,
+  }
+}
+
+export default useStep4Preview

apps/web/src/pages/generate/hooks/useStep4Title/index.ts

@@ -1,3 +1,4 @@
+import { useEffect, useRef } from "react"
 import { useQuery } from "@tanstack/react-query"
 import { getTitles } from "@/api/titles"
 import type { TitleSettings } from "../../types"
@@ -22,27 +23,59 @@ export function useStep4Title({ titleSettings, onTitleSettingsChange }: UseStep4
   })
 
   // AI 标题生成
-  const aiGenerator = useAiTitleGenerator({ titleSettings, onTitleSettingsChange })
+  const {
+    aiTitleInput,
+    setAiTitleInput,
+    aiTitleGenerating,
+    aiTitleResults,
+    hasGeneratedTitles,
+    handleGenerateAiTitles,
+    handleSelectAiTitle,
+    handleRefreshAiTitles,
+    autoGenerateTitle,
+  } = useAiTitleGenerator({ titleSettings, onTitleSettingsChange })
 
   // 样式更新
   const styleUpdaters = useTitleStyleUpdaters({ titleSettings, onTitleSettingsChange })
 
+  // 追踪 AI 自动选择开关的上一次值 & 是否首次挂载
+  const prevAiAutoSelect = useRef(titleSettings.aiAutoSelect)
+  const isFirstMount = useRef(true)
+
+  // 当 AI 自动选择开关打开时，自动生成/选择一个标题填入
+  // 首次挂载时如果开关已经是 true 且无标题，也需要触发
+  useEffect(() => {
+    if (isFirstMount.current) {
+      isFirstMount.current = false
+      if (titleSettings.aiAutoSelect && !titleSettings.title) {
+        autoGenerateTitle()
+      }
+      prevAiAutoSelect.current = titleSettings.aiAutoSelect
+      return
+    }
+    if (titleSettings.aiAutoSelect && !prevAiAutoSelect.current && !titleSettings.title) {
+      autoGenerateTitle()
+    }
+    prevAiAutoSelect.current = titleSettings.aiAutoSelect
+  }, [titleSettings.aiAutoSelect, titleSettings.title, autoGenerateTitle])
+
   return {
     // 数据
     userTitles,
     titleSettings,
     // AI 标题状态
-    aiTitleInput: aiGenerator.aiTitleInput,
-    setAiTitleInput: aiGenerator.setAiTitleInput,
-    aiTitleGenerating: aiGenerator.aiTitleGenerating,
-    aiTitleResults: aiGenerator.aiTitleResults,
-    hasGeneratedTitles: aiGenerator.hasGeneratedTitles,
+    aiTitleInput,
+    setAiTitleInput,
+    aiTitleGenerating,
+    aiTitleResults,
+    hasGeneratedTitles,
     activePreset: styleUpdaters.activePreset,
     titlePresets: styleUpdaters.titlePresets,
     // AI 标题操作
-    handleGenerateAiTitles: aiGenerator.handleGenerateAiTitles,
-    handleSelectAiTitle: aiGenerator.handleSelectAiTitle,
-    handleRefreshAiTitles: aiGenerator.handleRefreshAiTitles,
+    handleGenerateAiTitles,
+    handleSelectAiTitle,
+    handleRefreshAiTitles,
+    autoGenerateTitle,
     // 标题设置操作
     updateTitle: styleUpdaters.updateTitle,
     toggleAiAutoSelect: styleUpdaters.toggleAiAutoSelect,

apps/web/src/pages/generate/hooks/useStep4Title/useAiTitleGenerator.ts

@@ -72,9 +72,30 @@ export function useAiTitleGenerator({
     setAiTitleGenerating(false)
   }, [aiTitleInput])
 
+  /**
+   * 自动生成标题（供 AI 自动选择开关使用）
+   * 如果已有生成结果，直接从中选一个；否则用默认关键词生成
+   */
+  const autoGenerateTitle = useCallback((): string => {
+    if (aiTitleResults.length > 0) {
+      const picked = aiTitleResults[Math.floor(Math.random() * aiTitleResults.length)]
+      if (!picked) return ""
+      onTitleSettingsChange({ ...titleSettings, title: picked.title })
+      return picked.title
+    }
+    // 没有已有结果，用默认关键词生成
+    const results = generateTitlesFromTopic("短视频")
+    setAiTitleResults(results)
+    setHasGeneratedTitles(true)
+    const picked = results[Math.floor(Math.random() * results.length)]
+    if (!picked) return ""
+    onTitleSettingsChange({ ...titleSettings, title: picked.title })
+    return picked.title
+  }, [aiTitleResults, titleSettings, onTitleSettingsChange])
+
   const handleSelectAiTitle = useCallback(
     (title: string) => {
-      onTitleSettingsChange({ ...titleSettings, title, aiAutoSelect: false })
+      onTitleSettingsChange({ ...titleSettings, title })
       message.success("已选用此标题")
     },
     [titleSettings, onTitleSettingsChange],
@@ -98,5 +119,6 @@ export function useAiTitleGenerator({
     handleGenerateAiTitles,
     handleSelectAiTitle,
     handleRefreshAiTitles,
+    autoGenerateTitle,
   }
 }

apps/web/src/pages/generate/hooks/useStep4Title/useTitleStyleUpdaters.ts

@@ -15,10 +15,10 @@ export function useTitleStyleUpdaters({
   titleSettings,
   onTitleSettingsChange,
 }: UseTitleStyleUpdatersOptions) {
+  /** 匹配预设：只用 color/bold/italic/stroke/shadow，不再匹配 size */
   const getActivePreset = (settings: TitleSettings): string | null => {
     for (const p of TITLE_PRESETS) {
       if (
-        settings.size === p.style.size &&
         settings.color === p.style.color &&
         settings.bold === p.style.bold &&
         settings.italic === p.style.italic &&
@@ -88,13 +88,13 @@ export function useTitleStyleUpdaters({
     onTitleSettingsChange({ ...titleSettings, shadow: !titleSettings.shadow })
   }, [titleSettings, onTitleSettingsChange])
 
+  /** 应用预设：只覆盖 color/bold/italic/stroke/shadow，不改变字号 */
   const applyPreset = useCallback(
     (presetKey: string) => {
       const preset = TITLE_PRESETS.find((p) => p.key === presetKey)
       if (!preset) return
       onTitleSettingsChange({
         ...titleSettings,
-        size: preset.style.size,
         color: preset.style.color,
         bold: preset.style.bold,
         italic: preset.style.italic,

apps/web/src/pages/generate/hooks/useStep6Cover.ts

@@ -2,21 +2,30 @@
  * Step 6 封面设置 Hook
  * 封装封面设置的交互逻辑
  */
-import { useCallback } from "react"
+import { useCallback, useRef } from "react"
 import type { CoverConfig } from "../../editing-planner/types"
 import { COVER_MODE_LABELS, COVER_MODE_ICONS, DEFAULT_COVER_SETTINGS } from "../constants"
+import { generateCover } from "@/api/template-editor"
 
 interface UseStep6CoverProps {
   coverSettings: CoverConfig
   onCoverSettingsChange: (settings: CoverConfig) => void
   duration: number
+  /** 当前素材 ID 列表，用于智能封面生成 */
+  assetIds?: string[]
+  /** 当前选中的模板 ID */
+  selectedTemplate?: string
 }
 
 export function useStep6Cover({
   coverSettings,
   onCoverSettingsChange,
   duration,
+  assetIds = [],
+  selectedTemplate = "",
 }: UseStep6CoverProps) {
+  const generatingRef = useRef(false)
+
   const formatTime = useCallback((seconds: number) => {
     const m = Math.floor(seconds / 60)
     const s = Math.floor(seconds % 60)
@@ -62,6 +71,30 @@ export function useStep6Cover({
     [coverSettings, onCoverSettingsChange],
   )
 
+  /** 调用后端智能封面 API，生成封面并更新预览 */
+  const generateAutoCover = useCallback(async () => {
+    if (!selectedTemplate || assetIds.length === 0 || generatingRef.current) return
+    generatingRef.current = true
+    try {
+      const response = await generateCover(selectedTemplate, {
+        asset_ids: assetIds,
+        cover_type: "ai_frame",
+      })
+      const thumbnailUrl = response.cover?.thumbnail_url || ""
+      if (thumbnailUrl) {
+        onCoverSettingsChange({
+          ...coverSettings,
+          thumbnail_url: thumbnailUrl,
+          ai_suggested_time: response.cover?.frame_time ?? null,
+        })
+      }
+    } catch (err) {
+      console.warn("[Step6] 智能封面生成失败:", err)
+    } finally {
+      generatingRef.current = false
+    }
+  }, [selectedTemplate, assetIds, coverSettings, onCoverSettingsChange])
+
   const totalDuration = duration || 30
 
   return {
@@ -71,6 +104,7 @@ export function useStep6Cover({
     setMode,
     setFrameTime,
     handleUpload,
+    generateAutoCover,
     totalDuration,
     COVER_MODE_LABELS,
     COVER_MODE_ICONS,

apps/web/src/pages/generate/hooks/useStep7Generate.ts

@@ -3,11 +3,13 @@
  * 封装生成确认页的展示逻辑
  */
 import { useMemo } from "react"
+import { useQuery } from "@tanstack/react-query"
 import type { EditingTemplate } from "@/api/editing-planner"
 import type { GeneratedVideo } from "@/api/template-editor"
 import type { CoverConfig } from "../../editing-planner/types"
 import type { VoiceClone } from "@/api/voice-clone"
 import type { PresetVoiceItem } from "@/api/voices"
+import { getAssetsByKind } from "@/api/assets"
 import { COVER_MODE_LABELS } from "../constants"
 
 interface UseStep7GenerateProps {
@@ -39,11 +41,11 @@ export function useStep7Generate({
   selectedMaterials,
   smartSelectedIds,
   title,
-  voiceMode,
+  voiceMode: _voiceMode,
   selectedVoice,
-  selectedClonedVoice,
-  presetVoices,
-  clonedVoices,
+  selectedClonedVoice: _selectedClonedVoice,
+  presetVoices: _presetVoices,
+  clonedVoices: _clonedVoices,
   coverSettings,
   generateCount,
   onGenerateCountChange,
@@ -65,14 +67,16 @@ export function useStep7Generate({
     return `${selectedMaterials.length} 个素材`
   }, [materialMode, selectedMaterials.length, smartSelectedIds.length])
 
+  // 从配音素材库中查找 voiceName
+  const { data: voiceMaterials = [] } = useQuery({
+    queryKey: ["assets", "voice"],
+    queryFn: () => getAssetsByKind("voice", { limit: 50 }),
+  })
+
   const voiceName = useMemo(() => {
-    if (voiceMode === "clone") {
-      const cv = clonedVoices.find((v) => v.id === selectedClonedVoice)
-      return cv ? cv.name : "未选择"
-    }
-    const pv = presetVoices.find((v) => v.voice_id === selectedVoice)
-    return pv ? pv.name : "未选择"
-  }, [voiceMode, selectedVoice, selectedClonedVoice, presetVoices, clonedVoices])
+    const asset = voiceMaterials.find((v) => v.id === selectedVoice)
+    return asset ? asset.name : "未选择"
+  }, [voiceMaterials, selectedVoice])
 
   const coverSummary = useMemo(() => {
     if (!coverSettings.enabled) return "不使用"

apps/web/src/pages/generate/hooks/useStepNavigation.ts

@@ -1,6 +1,7 @@
 /**
  * GeneratePage 步骤导航
  * 管理步骤切换与各步骤的前置校验
+ * 步骤顺序：模板(1) → 素材(2) → 配音(3) → 预览(4) → 标题(5) → 封面(6) → 确认(7)
  */
 import { message } from "antd"
 import type { TitleSettings } from "../types"
@@ -13,7 +14,7 @@ export interface UseStepNavigationOptions {
   selectedMaterials: string[]
   smartSelectedIds: string[]
   titleSettings: TitleSettings
-  /** Step3 是否已生成预览（Step3校验用） */
+  /** Step4 是否已生成预览 */
   previewReady: boolean
 }
 
@@ -47,11 +48,12 @@ export const useStepNavigation = (options: UseStepNavigationOptions): UseStepNav
       message.warning("请先进行智能匹配并选择素材")
       return
     }
-    if (currentStep === 3 && !previewReady) {
+    // Step3 配音：配音为可选项，不强制校验，用户可跳过
+    if (currentStep === 4 && !previewReady) {
       message.warning("请先生成剪辑预览")
       return
     }
-    if (currentStep === 4 && !titleSettings.title.trim()) {
+    if (currentStep === 5 && !titleSettings.title.trim()) {
       message.warning("请选择或输入标题")
       return
     }

apps/web/src/pages/my-voices/MyVoices.tsx

@@ -26,6 +26,7 @@ const MyVoices: React.FC = () => {
     loading,
     hasProcessing,
     playingId,
+    loadingPreviewId,
     toasts,
     editModalOpen,
     editName,
@@ -75,6 +76,7 @@ const MyVoices: React.FC = () => {
               key={voice.id}
               voice={voice}
               isPlaying={playingId === voice.id}
+              isLoading={loadingPreviewId === voice.id}
               onTogglePlay={handleTogglePlay}
               onEdit={handleEdit}
               onDelete={handleDelete}

apps/web/src/pages/my-voices/components/VoiceCard.tsx

@@ -6,6 +6,7 @@ import {
   EditOutlined,
   SoundOutlined,
   ClockCircleOutlined,
+  LoadingOutlined,
 } from "@ant-design/icons"
 import { Button, Tooltip } from "@/components/ui"
 import { formatDuration, type VoiceClone } from "@/api/voice-clone"
@@ -15,6 +16,7 @@ import { formatDate } from "../utils"
 interface VoiceCardProps {
   voice: VoiceClone
   isPlaying: boolean
+  isLoading?: boolean
   onTogglePlay: (voice: VoiceClone) => void
   onEdit: (voice: VoiceClone) => void
   onDelete: (voice: VoiceClone) => void
@@ -26,6 +28,7 @@ interface VoiceCardProps {
 export const VoiceCard: React.FC<VoiceCardProps> = ({
   voice,
   isPlaying,
+  isLoading = false,
   onTogglePlay,
   onEdit,
   onDelete,
@@ -74,8 +77,13 @@ export const VoiceCard: React.FC<VoiceCardProps> = ({
             buttonType={isPlaying ? "secondary" : "ghost"}
             buttonSize="sm"
             onClick={() => onTogglePlay(voice)}
+            disabled={isLoading}
           >
-            {isPlaying ? (
+            {isLoading ? (
+              <>
+                <LoadingOutlined /> 合成中…
+              </>
+            ) : isPlaying ? (
               <>
                 <PauseCircleOutlined /> 暂停
               </>

apps/web/src/pages/my-voices/hooks/useMyVoices.ts

@@ -1,7 +1,7 @@
 import { useState, useCallback, useRef } from "react"
 import { useNavigate } from "react-router-dom"
 import { useCloneProgress } from "@/hooks/useCloneProgress"
-import { deleteVoiceClone, updateVoiceClone } from "@/api/voice-clone"
+import { deleteVoiceClone, updateVoiceClone, getVoiceClonePreview } from "@/api/voice-clone"
 import type { VoiceClone } from "@/api/voice-clone"
 import type { ToastItem } from "../types"
 
@@ -15,6 +15,7 @@ export const useMyVoices = () => {
   const navigate = useNavigate()
   const { clones, loading, removeClone, updateClone, hasProcessing } = useCloneProgress()
   const [playingId, setPlayingId] = useState<string | null>(null)
+  const [loadingPreviewId, setLoadingPreviewId] = useState<string | null>(null)
   const [toasts, setToasts] = useState<ToastItem[]>([])
   const [editModalOpen, setEditModalOpen] = useState(false)
   const [editingVoice, setEditingVoice] = useState<VoiceClone | null>(null)
@@ -31,26 +32,44 @@ export const useMyVoices = () => {
 
   // 试听播放
   const handleTogglePlay = useCallback(
-    (voice: VoiceClone) => {
+    async (voice: VoiceClone) => {
+      // 正在播放同一个 → 暂停
       if (playingId === voice.id) {
         audioRef.current?.pause()
         setPlayingId(null)
         return
       }
+
+      // 先停掉当前播放
       if (audioRef.current) {
         audioRef.current.pause()
+        audioRef.current = null
       }
-      if (!voice.sample_url) {
-        showToast("暂无试听音频", "error")
+
+      // 如果正在加载其他试听，不重复触发
+      if (loadingPreviewId && loadingPreviewId !== voice.id) {
         return
       }
-      const audio = new Audio(voice.sample_url)
-      audioRef.current = audio
-      audio.play().catch(() => showToast("播放失败，请检查音频文件", "error"))
-      audio.onended = () => setPlayingId(null)
-      setPlayingId(voice.id)
+
+      // 调用试听接口获取音频 URL
+      setLoadingPreviewId(voice.id)
+      try {
+        const preview = await getVoiceClonePreview(voice.id)
+        const audio = new Audio(preview.audio_url)
+        audioRef.current = audio
+        audio.play().catch(() => {
+          showToast("播放失败，请检查音频文件", "error")
+          setPlayingId(null)
+        })
+        audio.onended = () => setPlayingId(null)
+        setPlayingId(voice.id)
+      } catch {
+        showToast("试听音频生成失败，请重试", "error")
+      } finally {
+        setLoadingPreviewId(null)
+      }
     },
-    [playingId, showToast],
+    [playingId, loadingPreviewId, showToast],
   )
 
   // 编辑
@@ -117,6 +136,7 @@ export const useMyVoices = () => {
     hasProcessing,
     // 状态
     playingId,
+    loadingPreviewId,
     toasts,
     editModalOpen,
     editingVoice,

apps/web/src/pages/voices/VoiceLibrary.tsx

@@ -117,11 +117,9 @@ const VoiceLibrary: React.FC = () => {
     uploadOpen,
     uploadFile,
     uploadName,
-    uploadGender,
     uploadDesc,
     uploadProgress,
     setUploadName,
-    setUploadGender,
     setUploadDesc,
     setUploadOpen,
     handleFileSelect,
@@ -252,14 +250,12 @@ const VoiceLibrary: React.FC = () => {
         uploadOpen={uploadOpen}
         uploadFile={uploadFile}
         uploadName={uploadName}
-        uploadGender={uploadGender}
         uploadDesc={uploadDesc}
         uploadProgress={uploadProgress}
         onUploadClose={handleUploadClose}
         onFileSelect={handleFileSelect}
         onFileRemove={handleFileRemove}
         onNameChange={setUploadName}
-        onGenderChange={setUploadGender}
         onDescChange={setUploadDesc}
         onUpload={handleUpload}
         ttsOpen={ttsOpen}

apps/web/src/pages/voices/components/UploadVoiceModal.tsx

@@ -14,14 +14,12 @@ const UploadVoiceModal: React.FC<UploadVoiceModalProps> = ({
   open,
   uploadFile,
   uploadName,
-  uploadGender,
   uploadDesc,
   uploadProgress,
   onClose,
   onFileSelect,
   onFileRemove,
   onNameChange,
-  onGenderChange,
   onDescChange,
   onUpload,
 }) => {
@@ -30,7 +28,7 @@ const UploadVoiceModal: React.FC<UploadVoiceModalProps> = ({
 
   return (
     <Modal
-      title="上传音频"
+      title={<span style={{ fontSize: 16, fontWeight: 600 }}>上传配音素材</span>}
       open={open}
       onCancel={() => {
         if (uploading) return // 上传中不可关闭
@@ -45,7 +43,7 @@ const UploadVoiceModal: React.FC<UploadVoiceModalProps> = ({
           display: "flex",
           flexDirection: "column",
           gap: 16,
-          padding: "8px 0",
+          padding: "12px 0 4px",
         }}
       >
         {/* 拖拽上传区 */}
@@ -64,11 +62,9 @@ const UploadVoiceModal: React.FC<UploadVoiceModalProps> = ({
         {/* 表单字段 */}
         <FormFields
           name={uploadName}
-          gender={uploadGender}
           desc={uploadDesc}
           disabled={uploading}
           onNameChange={onNameChange}
-          onGenderChange={onGenderChange}
           onDescChange={onDescChange}
         />
 

apps/web/src/pages/voices/components/VoiceModals.tsx

@@ -2,7 +2,7 @@
  * VoiceLibrary 弹窗集合
  */
 import React from "react"
-import type { ClonedVoiceDisplay, PresetVoiceDisplay, VoiceGender } from "../types"
+import type { ClonedVoiceDisplay, PresetVoiceDisplay } from "../types"
 import type { VoiceClone } from "@/api/voice-clone"
 import type { TtsStatus } from "./TtsModal"
 import CloneModal from "@/components/voice/CloneModal"
@@ -27,14 +27,12 @@ export interface VoiceModalsProps {
   uploadOpen: boolean
   uploadFile: File | null
   uploadName: string
-  uploadGender: VoiceGender
   uploadDesc: string
   uploadProgress: number | null
   onUploadClose: () => void
   onFileSelect: (file: File) => void
   onFileRemove: () => void
   onNameChange: (name: string) => void
-  onGenderChange: (gender: VoiceGender) => void
   onDescChange: (desc: string) => void
   onUpload: () => void
 
@@ -67,14 +65,12 @@ export const VoiceModals: React.FC<VoiceModalsProps> = ({
   uploadOpen,
   uploadFile,
   uploadName,
-  uploadGender,
   uploadDesc,
   uploadProgress,
   onUploadClose,
   onFileSelect,
   onFileRemove,
   onNameChange,
-  onGenderChange,
   onDescChange,
   onUpload,
   ttsOpen,
@@ -113,14 +109,12 @@ export const VoiceModals: React.FC<VoiceModalsProps> = ({
         open={uploadOpen}
         uploadFile={uploadFile}
         uploadName={uploadName}
-        uploadGender={uploadGender}
         uploadDesc={uploadDesc}
         uploadProgress={uploadProgress}
         onClose={onUploadClose}
         onFileSelect={onFileSelect}
         onFileRemove={onFileRemove}
         onNameChange={onNameChange}
-        onGenderChange={onGenderChange}
         onDescChange={onDescChange}
         onUpload={onUpload}
       />

apps/web/src/pages/voices/components/upload-voice-modal/ActionButtons.tsx

@@ -1,4 +1,5 @@
 import React from "react"
+import { Button } from "antd"
 
 interface ActionButtonsProps {
   uploading: boolean
@@ -13,12 +14,6 @@ const ActionButtons: React.FC<ActionButtonsProps> = ({
   onCancel,
   onUpload,
 }) => {
-  const disabled = uploading || !canUpload
-
-  const handleUpload = () => {
-    onUpload()
-  }
-
   return (
     <div
       style={{
@@ -28,39 +23,32 @@ const ActionButtons: React.FC<ActionButtonsProps> = ({
         paddingTop: 4,
       }}
     >
-      <button
-        type="button"
+      <Button
         onClick={onCancel}
         disabled={uploading}
         style={{
-          padding: "8px 20px",
+          height: 36,
           borderRadius: 8,
-          border: "1px solid var(--border-color)",
-          background: "transparent",
           fontSize: 13,
-          cursor: uploading ? "not-allowed" : "pointer",
-          color: "var(--text-secondary)",
         }}
       >
         取消
-      </button>
-      <button
-        type="button"
-        onClick={handleUpload}
-        disabled={disabled}
+      </Button>
+      <Button
+        type="primary"
+        onClick={onUpload}
+        disabled={!canUpload}
+        loading={uploading}
         style={{
-          padding: "8px 20px",
+          height: 36,
           borderRadius: 8,
-          border: "none",
-          background: disabled ? "var(--text-tertiary)" : "var(--primary-color)",
-          color: "#fff",
           fontSize: 13,
           fontWeight: 600,
-          cursor: disabled ? "not-allowed" : "pointer",
+          minWidth: 100,
         }}
       >
-        {uploading ? "上传中..." : "开始上传"}
-      </button>
+        {uploading ? "上传中" : "开始上传"}
+      </Button>
     </div>
   )
 }

apps/web/src/pages/voices/components/upload-voice-modal/FileInfoCard.tsx

@@ -10,28 +10,55 @@ const FileInfoCard: React.FC<FileInfoCardProps> = ({ file }) => {
   return (
     <div
       style={{
-        padding: "10px 12px",
+        padding: "10px 14px",
         background: "var(--bg-secondary)",
-        borderRadius: 8,
+        borderRadius: 10,
         display: "flex",
         alignItems: "center",
-        gap: 10,
+        gap: 12,
+        border: "1px solid var(--border-color)",
+        boxShadow: "0 1px 3px rgba(0, 0, 0, 0.04)",
       }}
     >
-      <SoundOutlined style={{ fontSize: 18, color: "var(--primary-color)" }} />
+      {/* 文件图标圆形底托 */}
+      <div
+        style={{
+          width: 36,
+          height: 36,
+          borderRadius: "50%",
+          background: "var(--primary-soft, rgba(22, 119, 255, 0.1))",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          flexShrink: 0,
+        }}
+      >
+        <SoundOutlined style={{ fontSize: 16, color: "var(--primary-color)" }} />
+      </div>
+
+      {/* 文件信息 */}
       <div style={{ flex: 1, minWidth: 0 }}>
         <div
           style={{
             fontSize: 13,
             fontWeight: 500,
+            color: "var(--text-primary)",
             overflow: "hidden",
             textOverflow: "ellipsis",
             whiteSpace: "nowrap",
+            lineHeight: 1.4,
           }}
         >
           {file.name}
         </div>
-        <div style={{ fontSize: 11, color: "var(--text-secondary)" }}>
+        <div
+          style={{
+            fontSize: 12,
+            color: "var(--text-secondary)",
+            marginTop: 2,
+            lineHeight: 1.3,
+          }}
+        >
           {formatFileSize(file.size)}
         </div>
       </div>

apps/web/src/pages/voices/components/upload-voice-modal/FileUploadZone.tsx

@@ -14,6 +14,8 @@ const FileUploadZone: React.FC<FileUploadZoneProps> = ({
   onFileSelect,
   onFileRemove,
 }) => {
+  const [isHovered, setIsHovered] = React.useState(false)
+
   return (
     <Upload.Dragger
       accept={UPLOAD_CONFIG.accept}
@@ -28,25 +30,73 @@ const FileUploadZone: React.FC<FileUploadZoneProps> = ({
       showUploadList={false}
       disabled={disabled}
     >
-      <p
+      <div
         style={{
-          fontSize: 32,
-          color: "var(--primary-color)",
-          marginBottom: 8,
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          justifyContent: "center",
+          padding: "20px 16px",
+          borderRadius: 12,
+          background: isHovered
+            ? "var(--primary-soft, rgba(22, 119, 255, 0.08))"
+            : "var(--primary-soft, rgba(22, 119, 255, 0.03))",
+          border: `2px dashed ${isHovered ? "var(--primary-color)" : "var(--border-color)"}`,
+          transition: "all 0.25s ease",
+          cursor: disabled ? "not-allowed" : "pointer",
+          opacity: disabled ? 0.6 : 1,
         }}
+        onMouseEnter={() => setIsHovered(true)}
+        onMouseLeave={() => setIsHovered(false)}
       >
-        <UploadOutlined />
-      </p>
-      <p style={{ fontSize: 14, fontWeight: 500, margin: "0 0 4px" }}>点击或拖拽音频文件到此处</p>
-      <p
-        style={{
-          fontSize: 12,
-          color: "var(--text-secondary)",
-          margin: 0,
-        }}
-      >
-        支持 MP3、WAV、AAC、FLAC 等格式，最大 {UPLOAD_CONFIG.maxSizeMB}MB
-      </p>
+        {/* 图标圆形底托 */}
+        <div
+          style={{
+            width: 44,
+            height: 44,
+            borderRadius: "50%",
+            background: "var(--primary-soft, rgba(22, 119, 255, 0.1))",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            marginBottom: 10,
+            transition: "transform 0.2s ease",
+            transform: isHovered ? "scale(1.08)" : "scale(1)",
+          }}
+        >
+          <UploadOutlined
+            style={{
+              fontSize: 20,
+              color: "var(--primary-color)",
+            }}
+          />
+        </div>
+
+        {/* 主文案 */}
+        <p
+          style={{
+            fontSize: 14,
+            fontWeight: 500,
+            color: "var(--text-primary)",
+            margin: "0 0 6px",
+            lineHeight: 1.4,
+          }}
+        >
+          点击或拖拽音频文件到此处
+        </p>
+
+        {/* 副文案 */}
+        <p
+          style={{
+            fontSize: 12,
+            color: "var(--text-secondary)",
+            margin: 0,
+            lineHeight: 1.4,
+          }}
+        >
+          支持 MP3、WAV、AAC、FLAC 等格式，最大 {UPLOAD_CONFIG.maxSizeMB}MB
+        </p>
+      </div>
     </Upload.Dragger>
   )
 }

apps/web/src/pages/voices/components/upload-voice-modal/FormFields.tsx

@@ -1,101 +1,91 @@
 import React from "react"
-import type { VoiceGender } from "@/pages/voices/types"
-import { GENDER_OPTIONS, UPLOAD_CONFIG } from "./types"
+import { UPLOAD_CONFIG } from "./types"
 
 interface FormFieldsProps {
   name: string
-  gender: VoiceGender
   desc: string
   disabled: boolean
   onNameChange: (name: string) => void
-  onGenderChange: (gender: VoiceGender) => void
   onDescChange: (desc: string) => void
 }
 
 const labelStyle: React.CSSProperties = {
-  fontSize: 13,
-  color: "var(--text-secondary)",
+  fontSize: 12,
+  fontWeight: 600,
+  color: "var(--text-primary, #333)",
   marginBottom: 6,
+  letterSpacing: "0.02em",
 }
 
-const inputStyle: React.CSSProperties = {
+const baseInputStyle: React.CSSProperties = {
   width: "100%",
-  padding: "8px 12px",
+  padding: "10px 12px",
   border: "1px solid var(--border-color)",
   borderRadius: 8,
   fontSize: 13,
   background: "var(--bg-primary)",
   color: "var(--text-primary)",
   outline: "none",
+  transition: "border-color 0.2s ease, box-shadow 0.2s ease",
+  lineHeight: 1.5,
+}
+
+const focusStyle: React.CSSProperties = {
+  borderColor: "var(--primary-color)",
+  boxShadow: "0 0 0 2px var(--primary-soft, rgba(22, 119, 255, 0.12))",
 }
 
 const FormFields: React.FC<FormFieldsProps> = ({
   name,
-  gender,
   desc,
   disabled,
   onNameChange,
-  onGenderChange,
   onDescChange,
 }) => {
   return (
     <>
       {/* 名称 */}
       <div>
-        <div style={labelStyle}>素材名称</div>
+        <div style={labelStyle}>配音名称</div>
         <input
           value={name}
           onChange={(e) => onNameChange(e.target.value)}
-          placeholder="输入素材名称"
+          placeholder="输入配音名称"
           maxLength={UPLOAD_CONFIG.maxNameLength}
           disabled={disabled}
-          style={inputStyle}
+          style={baseInputStyle}
+          onFocus={(e) => {
+            Object.assign(e.target.style, focusStyle)
+          }}
+          onBlur={(e) => {
+            e.target.style.borderColor = "var(--border-color)"
+            e.target.style.boxShadow = "none"
+          }}
         />
       </div>
 
-      {/* 性别选择 */}
-      <div>
-        <div style={labelStyle}>音色性别</div>
-        <div style={{ display: "flex", gap: 8 }}>
-          {GENDER_OPTIONS.map((opt) => (
-            <button
-              key={opt.value}
-              type="button"
-              onClick={() => onGenderChange(opt.value)}
-              disabled={disabled}
-              style={{
-                flex: 1,
-                padding: "6px 0",
-                borderRadius: 8,
-                border: `1px solid ${gender === opt.value ? "var(--primary-color)" : "var(--border-color)"}`,
-                background: gender === opt.value ? "var(--primary-soft)" : "transparent",
-                color: gender === opt.value ? "var(--primary-color)" : "var(--text-secondary)",
-                fontSize: 13,
-                fontWeight: gender === opt.value ? 600 : 400,
-                cursor: disabled ? "not-allowed" : "pointer",
-                transition: "all 0.2s",
-              }}
-            >
-              {opt.label}
-            </button>
-          ))}
-        </div>
-      </div>
-
       {/* 描述 */}
       <div>
-        <div style={labelStyle}>音色描述（可选）</div>
+        <div style={labelStyle}>配音描述（可选）</div>
         <textarea
           value={desc}
           onChange={(e) => onDescChange(e.target.value)}
-          placeholder="描述这个音色的特点..."
+          placeholder="描述这段配音的内容..."
           maxLength={UPLOAD_CONFIG.maxDescLength}
           rows={2}
           disabled={disabled}
           style={{
-            ...inputStyle,
+            ...baseInputStyle,
             resize: "vertical",
             fontFamily: "inherit",
+            minHeight: 56,
+          }}
+          onFocus={(e) => {
+            Object.assign(e.target.style, focusStyle)
+          }}
+          onBlur={(e) => {
+            e.target.style.borderColor = "var(--border-color)"
+            e.target.style.boxShadow = "none"
           }}
         />
       </div>

apps/web/src/pages/voices/components/upload-voice-modal/UploadProgress.tsx

@@ -6,25 +6,40 @@ interface UploadProgressProps {
 
 const UploadProgress: React.FC<UploadProgressProps> = ({ progress }) => {
   return (
-    <div style={{ textAlign: "center", padding: "8px 0" }}>
+    <div
+      style={{
+        padding: "12px 16px",
+        background: "var(--bg-secondary)",
+        borderRadius: 10,
+        textAlign: "center",
+        border: "1px solid var(--border-color)",
+      }}
+    >
       <div
         style={{
-          fontSize: 22,
+          fontSize: 20,
           fontWeight: 700,
           color: "var(--primary-color)",
+          lineHeight: 1.2,
         }}
       >
         {progress}%
       </div>
-      <div style={{ fontSize: 12, color: "var(--text-secondary)" }}>
+      <div
+        style={{
+          fontSize: 12,
+          color: "var(--text-secondary)",
+          marginTop: 2,
+          marginBottom: 10,
+        }}
+      >
         {progress < 100 ? "上传中..." : "处理中..."}
       </div>
       <div
         style={{
           height: 4,
-          background: "var(--bg-tertiary)",
+          background: "var(--bg-tertiary, #f0f0f0)",
           borderRadius: 2,
-          marginTop: 8,
           overflow: "hidden",
         }}
       >
@@ -32,7 +47,7 @@ const UploadProgress: React.FC<UploadProgressProps> = ({ progress }) => {
           style={{
             height: "100%",
             width: `${progress}%`,
-            background: "var(--primary-color)",
+            background: progress < 100 ? "var(--primary-color)" : "var(--success-color, #52c41a)",
             borderRadius: 2,
             transition: "width 0.3s ease",
           }}

apps/web/src/pages/voices/components/upload-voice-modal/types.ts

@@ -1,27 +1,17 @@
-import type { VoiceGender } from "@/pages/voices/types"
-
 export interface UploadVoiceModalProps {
   open: boolean
   uploadFile: File | null
   uploadName: string
-  uploadGender: VoiceGender
   uploadDesc: string
   uploadProgress: number | null
   onClose: () => void
   onFileSelect: (file: File) => void
   onFileRemove: () => void
   onNameChange: (name: string) => void
-  onGenderChange: (gender: VoiceGender) => void
   onDescChange: (desc: string) => void
   onUpload: () => void
 }
 
-export const GENDER_OPTIONS: { value: VoiceGender; label: string }[] = [
-  { value: "female", label: "女声" },
-  { value: "male", label: "男声" },
-  { value: "child", label: "童声" },
-]
-
 export const UPLOAD_CONFIG = {
   maxSizeMB: 200,
   maxNameLength: 100,

apps/web/src/pages/voices/hooks/useVoiceUpload.ts

@@ -1,6 +1,5 @@
 import { useState, useCallback } from "react"
 import { useMutation, useQueryClient } from "@tanstack/react-query"
-import { type VoiceGender } from "../types"
 import { uploadAssetDirect, getAssetLibraries, createAsset } from "@/api/assets"
 import { getAudioDuration } from "../utils/audio"
 import { buildVoiceMetadata } from "../types"
@@ -19,17 +18,11 @@ export function useVoiceUpload({ showToast }: UseVoiceUploadProps) {
   const [uploadOpen, setUploadOpen] = useState(false)
   const [uploadFile, setUploadFile] = useState<File | null>(null)
   const [uploadName, setUploadName] = useState("")
-  const [uploadGender, setUploadGender] = useState<VoiceGender>("female")
   const [uploadDesc, setUploadDesc] = useState("")
   const [uploadProgress, setUploadProgress] = useState<number | null>(null)
 
   const uploadMutation = useMutation({
-    mutationFn: async (data: {
-      file: File
-      name: string
-      gender: VoiceGender
-      description: string
-    }) => {
+    mutationFn: async (data: { file: File; name: string; description: string }) => {
       setUploadProgress(0)
       try {
         /* 获取或创建默认配音库 */
@@ -57,7 +50,6 @@ export function useVoiceUpload({ showToast }: UseVoiceUploadProps) {
           storage_key,
           mime_type: data.file.type || "audio/mpeg",
           metadata: buildVoiceMetadata({
-            gender: data.gender,
             description: data.description,
             duration,
           }),
@@ -71,8 +63,15 @@ export function useVoiceUpload({ showToast }: UseVoiceUploadProps) {
       showToast("上传成功", "success")
       handleUploadClose()
     },
-    onError: (err: Error) => {
-      showToast(err.message || "上传失败，请重试", "error")
+    onError: (err: Error & { response?: { status?: number } }) => {
+      const status = err?.response?.status
+      let msg = "上传失败，请重试"
+      if (status && status >= 500) {
+        msg = "服务器暂时不可用，请稍后重试"
+      } else if (err?.message) {
+        msg = err.message
+      }
+      showToast(msg, "error")
     },
   })
 
@@ -102,10 +101,9 @@ export function useVoiceUpload({ showToast }: UseVoiceUploadProps) {
     uploadMutation.mutate({
       file: uploadFile,
       name: uploadName.trim(),
-      gender: uploadGender,
       description: uploadDesc.trim(),
     })
-  }, [uploadFile, uploadName, uploadGender, uploadDesc, uploadMutation])
+  }, [uploadFile, uploadName, uploadDesc, uploadMutation])
 
   return {
     // 弹窗状态
@@ -114,13 +112,11 @@ export function useVoiceUpload({ showToast }: UseVoiceUploadProps) {
     // 表单状态
     uploadFile,
     uploadName,
-    uploadGender,
     uploadDesc,
     uploadProgress,
     isUploading: uploadMutation.isPending,
     // Setters
     setUploadName,
-    setUploadGender,
     setUploadDesc,
     // Handlers
     handleFileSelect,

apps/web/src/router/ProtectedRoute.tsx

@@ -3,7 +3,6 @@ import { Navigate } from "react-router-dom"
 import { useAuthStore } from "@/store/authStore"
 
 /** 受保护的路由组件 */
-// eslint-disable-next-line react-refresh/only-export-components
 export const ProtectedRoute = ({ children }: { children: React.ReactNode }) => {
   const isAuthenticated = useAuthStore((state) => state.isAuthenticated)
   const hasAccessToken = Boolean(localStorage.getItem("access_token"))

apps/web/src/test/api/client.test.ts

@@ -26,12 +26,10 @@ import { refreshAccessToken } from "@/api/auth"
 import apiClient from "@/api/client"
 
 // 从真实实例取出拦截器回调
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 const requestHandlers = (apiClient as any).interceptors.request.handlers as Array<{
   fulfilled: (config: unknown) => unknown
   rejected: (error: unknown) => unknown
 }>
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 const responseHandlers = (apiClient as any).interceptors.response.handlers as Array<{
   fulfilled: (response: unknown) => unknown
   rejected: (error: unknown) => Promise<unknown>
@@ -258,7 +256,6 @@ describe("apiClient - 401 token refresh", () => {
       isAuthenticated: false,
       clearAuth: mockClearAuth,
       setAuth: vi.fn(),
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
     } as any)
 
     const err = makeAxiosError(401, { detail: "Unauthorized" })
@@ -276,7 +273,6 @@ describe("apiClient - 401 token refresh", () => {
       isAuthenticated: true,
       clearAuth: vi.fn(),
       setAuth: mockSetAuth,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
     } as any)
     vi.mocked(refreshAccessToken).mockResolvedValue({
       access_token: "new-access",
@@ -306,7 +302,6 @@ describe("apiClient - 401 token refresh", () => {
       isAuthenticated: true,
       clearAuth: mockClearAuth,
       setAuth: vi.fn(),
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
     } as any)
     vi.mocked(refreshAccessToken).mockRejectedValue(new Error("refresh failed") as never)
 

apps/web/src/test/hooks/useAuth.test.tsx

@@ -107,7 +107,7 @@ describe("useAuth hooks", () => {
       })
 
       expect(mockSetAuth).toHaveBeenCalled()
-      expect(mockNavigate).toHaveBeenCalledWith("/", { replace: true })
+      expect(mockNavigate).toHaveBeenCalledWith("/app/dashboard", { replace: true })
     })
 
     it("登录成功后跳转到 login_redirect 指定的页面", async () => {

apps/web/src/test/pages/GeneratePage.test.tsx

@@ -179,6 +179,7 @@ vi.mock("@/api/assets", () => ({
   createAssetLibrary: vi.fn().mockResolvedValue({}),
   getAssets: vi.fn().mockResolvedValue({ items: [], total: 0 }),
   getAssetsByKind: vi.fn().mockResolvedValue({ items: [], total: 0 }),
+  smartMatchAssets: vi.fn().mockResolvedValue({ items: [] }),
   createAsset: vi.fn().mockResolvedValue({}),
   updateAsset: vi.fn().mockResolvedValue({}),
   deleteAsset: vi.fn().mockResolvedValue({}),

apps/web/src/test/pages/editing-planner/components/TtsPanel.test.tsx

@@ -1,5 +1,5 @@
-import { describe, expect, it, vi } from "vitest"
-import { render } from "@testing-library/react"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { render, cleanup } from "@testing-library/react"
 import TtsPanel from "@/pages/editing-planner/components/TtsPanel"
 import { DEFAULT_TTS_CONFIG } from "@/pages/editing-planner/types"
 
@@ -16,6 +16,10 @@ const defaultProps = {
 }
 
 describe("TtsPanel", () => {
+  afterEach(() => {
+    cleanup()
+  })
+
   it("should render without crashing", () => {
     const { container } = render(<TtsPanel {...defaultProps} />)
     expect(container).toBeTruthy()

apps/web/src/test/pages/generate/smoke.test.tsx

@@ -17,7 +17,7 @@ import "@/api/generation/types"
 // 直接引入所有 Step 组件，建立完整依赖链
 import "@/pages/generate/GeneratePage"
 import "@/pages/generate/components/Step2MaterialSelect"
-import "@/pages/generate/components/Step3GeneratePreview"
+import "@/pages/generate/components/Step4GeneratePreview"
 import "@/pages/generate/components/Step4TitleSettings"
 import "@/pages/generate/components/Step5VoiceSelect"
 import "@/pages/generate/components/PreviewVideoPanel"
@@ -47,7 +47,7 @@ describe("GeneratePage module smoke test", () => {
   })
 })
 import "@/pages/generate/hooks/useGenerateVideo"
-import "@/pages/generate/hooks/useStep3Preview"
+import "@/pages/generate/hooks/useStep4Preview"
 import "@/pages/generate/hooks/generate-video/useGenerationPolling"
 import "@/pages/generate/hooks/useGenerateFormState"
 import "@/pages/generate/hooks/useGenerateFormState/useTemplateSelection"

apps/web/src/test/pages/generate/step3-preview.smoke.test.tsx

@@ -1,17 +0,0 @@
-/**
- * Step3GeneratePreview smoke test
- * 确保 vitest related 模式能匹配到第3步预览生成相关文件的改动
- */
-import { describe, it, expect } from "vitest"
-
-import "@/pages/generate/components/Step3GeneratePreview"
-import "@/pages/generate/hooks/useStep3Preview"
-import "@/pages/generate/hooks/useStepNavigation"
-import "@/pages/generate/components/GenerateStepContent"
-import "@/pages/generate/GeneratePage"
-
-describe("Step3GeneratePreview module smoke test", () => {
-  it("should load all step3 preview modules", () => {
-    expect(true).toBe(true)
-  })
-})

apps/web/src/test/pages/generate/step4-preview.smoke.test.tsx

@@ -0,0 +1,17 @@
+/**
+ * Step4GeneratePreview smoke test
+ * 确保 vitest related 模式能匹配到第4步预览生成相关文件的改动
+ */
+import { describe, it, expect } from "vitest"
+
+import "@/pages/generate/components/Step4GeneratePreview"
+import "@/pages/generate/hooks/useStep4Preview"
+import "@/pages/generate/hooks/useStepNavigation"
+import "@/pages/generate/components/GenerateStepContent"
+import "@/pages/generate/GeneratePage"
+
+describe("Step4GeneratePreview module smoke test", () => {
+  it("should load all step4 preview modules", () => {
+    expect(true).toBe(true)
+  })
+})

apps/web/src/test/setup.ts

@@ -32,9 +32,7 @@ afterEach(() => {
 declare global {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace Vi {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     interface Assertion<T = any> extends jest.Matchers<void, T> {}
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     interface AsymmetricMatchersContaining extends jest.Matchers<void, any> {}
   }
 }

apps/worker/video_processing/render_adapter.py

@@ -25,6 +25,7 @@ from typing import Any, Callable
 from sqlalchemy.orm import Session
 from video_processing.oss_helpers import download_asset, upload_to_oss
 from video_processing.unified_render_service import UnifiedRenderService
+from video_processing.video_validation import validate_video_output
 
 from packages.adapters.sqlalchemy_impl.edit_plan_clip_repository import SQLAlchemyEditPlanClipRepository
 from packages.adapters.sqlalchemy_impl.edit_plan_repository import SQLAlchemyEditPlanRepository
@@ -464,7 +465,7 @@ class RenderAdapter:
         失败不阻断主流程，返回 None。
         """
         try:
-            from services.asr_service_factory import get_asr_service
+            from apps.worker.services.asr_service_factory import get_asr_service
 
             return get_asr_service()
         except Exception as e:
@@ -484,6 +485,7 @@ class RenderAdapter:
         rendered_clip_ids: list[str] | None = None,
         failed_clip_ids: list[str] | None = None,
         voiceover_audio_path: str | None = None,
+        is_preview: bool = False,
     ) -> RenderAdapterResult:
         """执行统一渲染核心流程（BGM + ASR + 渲染 + 缩略图 + 上传）。
 
@@ -503,10 +505,12 @@ class RenderAdapter:
         self._report_progress(progress_cb, 40.0, "执行视频渲染")
 
         # 2. 初始化 ASR
-        asr_service = self._get_asr_service()
+        # 预览模式下，如果 plan.config 中存在 voice_id，仍需初始化 ASR 以支持配音
+        plan_config = plan.config or {}
+        has_voice_id = bool(plan_config.get("voice_id"))
+        asr_service = None if (is_preview and not has_voice_id) else self._get_asr_service()
 
         # 3. 读取输出分辨率
-        plan_config = plan.config or {}
         export_config = plan_config.get("export", {}) or {}
         output_width, output_height = _parse_resolution(export_config.get("resolution"))
         logger.info(
@@ -528,9 +532,27 @@ class RenderAdapter:
             bgm_path=bgm_path,
             asr_service=asr_service,
             voiceover_audio_path=voiceover_audio_path,
+            is_preview=is_preview,
         )
         result = render_svc.render()
 
+        # 4.5 渲染后校验输出完整性（预览模式跳过，节省耗时）
+        if is_preview:
+            logger.info("[render-adapter] 预览模式：跳过输出校验")
+        else:
+            validation = validate_video_output(result.output_path)
+            if not validation.valid:
+                logger.error(
+                    "[render-adapter] 渲染输出校验失败: plan_id=%s job_id=%s error=%s",
+                    plan_id,
+                    job_id,
+                    validation.error_message,
+                )
+                return RenderAdapterResult(
+                    success=False,
+                    error_message=f"渲染输出校验失败: {validation.error_message}",
+                    error_detail=validation.error_message,
+                )
         self._report_progress(progress_cb, 80.0, "上传渲染结果")
 
         # 5. 上传结果
@@ -539,19 +561,20 @@ class RenderAdapter:
 
         self._report_progress(progress_cb, 90.0, "生成封面缩略图")
 
-        # 6. 生成缩略图
+        # 6. 生成缩略图（预览模式跳过，节省耗时）
         thumbnail_url = ""
-        try:
-            from video_processing.thumbnail_generator import generate_and_upload_thumbnail
+        if not is_preview:
+            try:
+                from video_processing.thumbnail_generator import generate_and_upload_thumbnail
 
-            thumb_storage_key = f"rendered/{plan_id}/thumbnail.jpg"
-            thumbnail_url = generate_and_upload_thumbnail(str(result.output_path), thumb_storage_key)
-        except Exception as thumb_err:
-            logger.warning(
-                "[render-adapter] 缩略图生成失败（不影响主流程）: plan_id=%s error=%s",
-                plan_id,
-                thumb_err,
-            )
+                thumb_storage_key = f"rendered/{plan_id}/thumbnail.jpg"
+                thumbnail_url = generate_and_upload_thumbnail(str(result.output_path), thumb_storage_key)
+            except Exception as thumb_err:
+                logger.warning(
+                    "[render-adapter] 缩略图生成失败（不影响主流程）: plan_id=%s error=%s",
+                    plan_id,
+                    thumb_err,
+                )
 
         self._report_progress(progress_cb, 100.0, "渲染完成")
 
@@ -597,6 +620,7 @@ class RenderAdapter:
         work_dir: Path | None = None,
         progress_cb: ProgressCallback | None = None,
         voiceover_audio_path: str | None = None,
+        is_preview: bool = False,
     ) -> RenderAdapterResult:
         """使用内存中的 plan/clips/asset_path_map 直接渲染。
 
@@ -655,6 +679,7 @@ class RenderAdapter:
                 job_id=job_id,
                 progress_cb=progress_cb,
                 voiceover_audio_path=voiceover_audio_path,
+                is_preview=is_preview,
             )
 
         except subprocess.CalledProcessError as exc:

apps/worker/video_processing/render_audio.py

@@ -82,14 +82,12 @@ def mix_audio(
     """音频后处理混音.
 
     处理逻辑：
-    1. 主音频源按优先级查找：main > broll（background 不参与主音频，通常是图片无音轨）
-    2. 主图层音频按顺序 concat 拼接
-    3. 独立音频轨（audio role）用 amix 混入
-    4. 输出时长截断到 video_duration
-    5. 无音频流的 clip 会被自动跳过，避免 FFmpeg 引用 [i:a] 失败
-    6. 如果提供了 bgm_path，则额外混入 BGM（支持淡入淡出、循环、人声闪避）
-    7. 如果配置了 audio_tracks，则混入多轨道音频（配音、音效等）
-    8. 如果配置了降噪，最后应用降噪
+    1. 丢弃主图层（main/broll/overlay/corner_voice）的原始音频，避免录入源视频杂音
+    2. 仅使用独立音频轨（audio role，TTS/配音）作为主音频
+    3. 如果提供了 bgm_path，则额外混入 BGM（支持淡入淡出、循环、人声闪避）
+    4. 如果配置了 audio_tracks，则混入多轨道音频（配音、音效等）
+    5. 输出时长截断到 video_duration
+    6. 如果配置了降噪，最后应用降噪
 
     Args:
         ctx: 渲染上下文
@@ -125,8 +123,10 @@ def mix_audio(
     if "audio" in layer_map:
         audio_clips = layer_map["audio"].clips
 
+    # ── 丢弃源视频的原始音频（避免录入杂音），成片仅保留 TTS 配音 + BGM ──
+    main_clips = []
+
     # ── 防御：过滤掉无音频流的 clip ──
-    main_clips = [c for c in main_clips if clip_has_audio(ctx, c)]
     audio_clips = [c for c in audio_clips if clip_has_audio(ctx, c)]
 
     if not main_clips and not audio_clips:
@@ -144,12 +144,21 @@ def mix_audio(
     # 构建音频处理命令
     output_path = ctx.work_dir / f"audio_{ctx.plan_id}.aac"
 
-    # 简单场景：只有主图层 + 无独立音频 → 直接从视频提取音频并拼接
-    if main_clips and not audio_clips:
-        concat_main_audio(ctx, main_clips, output_path, video_duration)
+    # 源视频原始音频已被丢弃（main_clips = []），最终音频完全由独立音频轨 + BGM + 多轨配置组成。
+    # 当无 main_clips 时，将独立音频轨作为主音频走 concat 拼接；当二者均有则走 amix 混音。
+    if main_clips:
+        effective_main = main_clips
+        effective_audio = audio_clips
+    else:
+        effective_main = audio_clips
+        effective_audio = []
+
+    # 简单场景：只有主音频 + 无独立音频 → 直接拼接
+    if effective_main and not effective_audio:
+        concat_main_audio(ctx, effective_main, output_path, video_duration)
     else:
         # 有独立音频轨 → amix 混音
-        mix_with_independent_audio(ctx, main_clips, audio_clips, output_path, video_duration)
+        mix_with_independent_audio(ctx, effective_main, effective_audio, output_path, video_duration)
 
     # ── BGM 混音 ──
     if bgm_path and bgm_config and bgm_config.get("enabled", False):

apps/worker/video_processing/unified_render_service.py

@@ -151,6 +151,7 @@ class UnifiedRenderService:
         asr_service: Any = None,  # ASRService 实例，用于自动生成字幕
         bgm_path: str | None = None,  # BGM 本地文件路径
         voiceover_audio_path: str | None = None,  # 配音素材库音频本地路径
+        is_preview: bool = False,  # 预览模式：ultrafast 编码 + 跳过非必要步骤
     ):
         self.plan = plan
         self.clips = clips
@@ -163,6 +164,7 @@ class UnifiedRenderService:
         self.asr_service = asr_service
         self.bgm_path = bgm_path
         self.voiceover_audio_path = voiceover_audio_path
+        self.is_preview = is_preview
         self._transition_engine = TransitionEngine(default_duration=transition_duration)
         self._speed_engine = SpeedEngine()
         self._asr_timeline_cache: Any = None  # ASR 字幕结果缓存，避免重复调用
@@ -677,20 +679,40 @@ class UnifiedRenderService:
                     len(top_text),
                 )
             # 方式B：voice_id + 自动字幕 → 字幕对齐配音（预设配音模式）
-            elif top_voice_id and subtitle_cfg.get("auto_generated", False) and self.asr_service is not None:
-                tts_cfg = {
-                    "enabled": True,
-                    "voice_id": top_voice_id,
-                    "text": "",
-                    "align_mode": "subtitle",
-                    "overlap_mode": "replace",
-                }
-                use_subtitle_align = True
-                logger.info(
-                    "[unified-render] 检测到预设配音+自动字幕，使用字幕对齐模式: plan_id=%s voice_id=%s",
-                    self.plan.id,
-                    top_voice_id,
-                )
+            # ASR 可用时走字幕对齐模式，不可用时降级为整段配音
+            elif top_voice_id and subtitle_cfg.get("auto_generated", False):
+                if self.asr_service is not None:
+                    # 字幕对齐模式
+                    tts_cfg = {
+                        "enabled": True,
+                        "voice_id": top_voice_id,
+                        "text": "",
+                        "align_mode": "subtitle",
+                        "overlap_mode": "replace",
+                    }
+                    use_subtitle_align = True
+                    logger.info(
+                        "[unified-render] 检测到预设配音+自动字幕，使用字幕对齐模式: plan_id=%s voice_id=%s",
+                        self.plan.id,
+                        top_voice_id,
+                    )
+                else:
+                    # 降级：整段配音（预览模式 ASR 不可用时）
+                    # 拼接字幕文本作为配音内容
+                    subtitle_text_content = subtitle_cfg.get("text", "") or ""
+                    tts_cfg = {
+                        "enabled": True,
+                        "voice_id": top_voice_id,
+                        "text": subtitle_text_content,
+                        "align_mode": "full",
+                        "overlap_mode": "replace",
+                    }
+                    logger.info(
+                        "[unified-render] ASR 不可用，降级为整段配音模式: plan_id=%s voice_id=%s text_len=%d",
+                        self.plan.id,
+                        top_voice_id,
+                        len(subtitle_text_content),
+                    )
 
         # 兼容前端顶层字段：voice_id / custom_text / voice_clone_profile_id
         # 前端一键生成页面传 config.voice_id + config.custom_text，
@@ -1228,9 +1250,9 @@ class UnifiedRenderService:
             "-c:v",
             "libx264",
             "-crf",
-            "23",
+            "28" if self.is_preview else "23",
             "-preset",
-            "medium",
+            "ultrafast" if self.is_preview else "medium",
             "-pix_fmt",
             "yuv420p",
             "-movflags",
@@ -1742,9 +1764,9 @@ class UnifiedRenderService:
             "-c:v",
             "libx264",
             "-crf",
-            "23",
+            "28" if self.is_preview else "23",
             "-preset",
-            "medium",
+            "ultrafast" if self.is_preview else "medium",
             "-pix_fmt",
             "yuv420p",
             "-movflags",
@@ -1753,10 +1775,11 @@ class UnifiedRenderService:
         ]
 
         logger.info(
-            "执行渲染: plan_id=%s inputs=%d output=%s",
+            "执行渲染: plan_id=%s inputs=%d output=%s preview=%s",
             self.plan.id,
             input_args.count("-i"),
             output_path,
+            self.is_preview,
         )
         try:
             run_ffmpeg(command)

apps/worker/video_processing/video_validation.py

@@ -0,0 +1,267 @@
+"""视频输出校验 — 渲染后验证输出文件完整性.
+
+在 FFmpeg 渲染完成后，验证输出文件是否有效（非损坏/截断）：
+  1. 文件存在且大小 > 0
+  2. moov atom 存在（MP4 容器完整性标志）
+  3. ffprobe 可正常读取视频流信息
+
+用途：
+  - RenderAdapter 渲染后调用，避免将损坏文件上传到 OSS
+  - 提前发现 FFmpeg 异常退出但未抛异常的情况（如 exit=0 但输出截断）
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from shared.ffmpeg_utils import FFPROBE_BIN
+
+logger = logging.getLogger(__name__)
+
+
+# ── 数据结构 ──────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class VideoValidationResult:
+    """视频校验结果。"""
+
+    valid: bool
+    file_exists: bool = False
+    file_size: int = 0
+    moov_atom_found: bool = False
+    has_video_stream: bool = False
+    duration: float = 0.0
+    width: int = 0
+    height: int = 0
+    error_message: str = ""
+
+    @property
+    def is_valid(self) -> bool:
+        """是否通过所有校验。"""
+        return self.valid
+
+
+# ── FFmpeg 退出码映射 ──────────────────────────────────────────────────────────
+
+# 常见 FFmpeg 退出码及其含义
+FFMPEG_EXIT_CODES: dict[int, tuple[str, str]] = {
+    0: ("成功", "渲染正常完成"),
+    1: ("通用错误", "FFmpeg 执行出错，请检查输入参数和素材"),
+    69: ("权限错误", "无权限写入输出文件或访问输入文件"),
+    126: ("权限不足", "命令不可执行"),
+    127: ("命令不存在", "FFmpeg 二进制文件未找到"),
+    134: ("Abnormal termination", "FFmpeg 异常终止（可能内存不足）"),
+    137: ("OOM Killed", "FFmpeg 被系统 OOM Killer 终止（内存不足）"),
+    139: ("段错误", "FFmpeg Segmentation Fault（可能是编解码器 Bug）"),
+    141: ("管道断裂", "FFmpeg 输出管道断裂"),
+    143: ("SIGTERM", "FFmpeg 收到终止信号"),
+    183: ("滤镜错误", "FFmpeg 滤镜链配置错误"),
+    234: ("素材异常", "输入素材格式不兼容或已损坏"),
+    255: ("严重错误", "FFmpeg 执行严重错误"),
+}
+
+
+def get_exit_code_message(exit_code: int) -> str:
+    """获取 FFmpeg 退出码的中文描述。
+
+    Args:
+        exit_code: FFmpeg 进程退出码
+
+    Returns:
+        人类可读的错误描述
+    """
+    if exit_code in FFMPEG_EXIT_CODES:
+        name, desc = FFMPEG_EXIT_CODES[exit_code]
+        return f"exit={exit_code} ({name}): {desc}"
+    if exit_code > 128:
+        signal_num = exit_code - 128
+        return f"exit={exit_code}: 被信号 {signal_num} 终止"
+    return f"exit={exit_code}: 未知错误"
+
+
+# ── 校验函数 ──────────────────────────────────────────────────────────────────
+
+
+def validate_video_output(video_path: str | Path, *, min_duration: float = 0.1) -> VideoValidationResult:
+    """校验渲染输出视频文件的完整性。
+
+    校验项：
+      1. 文件存在且大小 > 0
+      2. 包含 moov atom（MP4 容器完整性）
+      3. ffprobe 可读取至少一个视频流
+
+    Args:
+        video_path: 输出视频文件路径
+        min_duration: 最小有效时长（秒），低于此值视为无效，默认 0.1s
+
+    Returns:
+        VideoValidationResult
+    """
+    path = Path(video_path)
+    result = VideoValidationResult(valid=False)
+
+    # 1. 文件存在性检查
+    if not path.exists():
+        result.error_message = f"输出文件不存在: {path}"
+        logger.error("[video-validation] %s", result.error_message)
+        return result
+
+    result.file_exists = True
+
+    # 2. 文件大小检查
+    try:
+        result.file_size = path.stat().st_size
+    except OSError as e:
+        result.error_message = f"无法读取文件大小: {e}"
+        logger.error("[video-validation] %s", result.error_message)
+        return result
+
+    if result.file_size == 0:
+        result.error_message = "输出文件大小为 0（FFmpeg 未写入任何数据）"
+        logger.error("[video-validation] %s", result.error_message)
+        return result
+
+    # 极小文件（< 1KB）几乎不可能是有效视频
+    if result.file_size < 1024:
+        result.error_message = f"输出文件过小 ({result.file_size} bytes)，可能渲染未完成"
+        logger.error("[video-validation] %s", result.error_message)
+        return result
+
+    # 3. moov atom 检查（MP4 容器完整性标志）
+    result.moov_atom_found = _check_moov_atom(path)
+    if not result.moov_atom_found:
+        result.error_message = (
+            "输出文件缺少 moov atom（MP4 容器不完整）。" "可能原因：FFmpeg 被强制终止、磁盘空间不足、或渲染过程中断。"
+        )
+        logger.error("[video-validation] %s — file_size=%d", result.error_message, result.file_size)
+        return result
+
+    # 4. ffprobe 验证视频流
+    try:
+        probe_result = subprocess.run(  # nosec B603
+            [
+                FFPROBE_BIN,
+                "-v",
+                "error",
+                "-select_streams",
+                "v:0",
+                "-show_entries",
+                "stream=width,height,duration,codec_name",
+                "-show_entries",
+                "format=duration",
+                "-of",
+                "json",
+                str(path),
+            ],
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            timeout=15,
+        )
+
+        import json
+
+        probe_data = json.loads(probe_result.stdout)
+        streams = probe_data.get("streams", [])
+        fmt = probe_data.get("format", {})
+
+        if not streams:
+            result.error_message = "输出文件无视频流（ffprobe 未检测到 video stream）"
+            logger.error("[video-validation] %s", result.error_message)
+            return result
+
+        result.has_video_stream = True
+
+        video_stream = streams[0]
+        result.width = int(video_stream.get("width", 0) or 0)
+        result.height = int(video_stream.get("height", 0) or 0)
+        result.duration = float(fmt.get("duration", 0) or video_stream.get("duration", 0) or 0)
+
+        # 时长校验
+        if result.duration > 0 and result.duration < min_duration:
+            result.error_message = (
+                f"输出视频时长过短 ({result.duration:.2f}s < {min_duration}s)，" "可能渲染只处理了极少帧"
+            )
+            logger.warning("[video-validation] %s", result.error_message)
+            # 不标记为失败，只是警告（某些预览场景确实很短）
+            # 但如果时长为 0 且文件大小较大，说明 moov 有问题
+        elif result.duration == 0 and result.file_size > 0:
+            logger.warning(
+                "[video-validation] ffprobe 无法读取时长，但文件存在且大小=%d，标记为可疑",
+                result.file_size,
+            )
+
+    except subprocess.TimeoutExpired:
+        result.error_message = "ffprobe 超时（15s），输出文件可能已损坏"
+        logger.error("[video-validation] %s", result.error_message)
+        return result
+    except subprocess.CalledProcessError as e:
+        stderr_text = (e.stderr or "").strip()
+        result.error_message = f"ffprobe 校验失败: exit={e.returncode}, stderr={stderr_text[:200]}"
+        logger.error("[video-validation] %s", result.error_message)
+        return result
+    except (json.JSONDecodeError, KeyError, ValueError) as e:
+        result.error_message = f"ffprobe 输出解析失败: {e}"
+        logger.error("[video-validation] %s", result.error_message)
+        return result
+
+    # 全部通过
+    result.valid = True
+    logger.info(
+        "[video-validation] 校验通过: path=%s size=%d duration=%.2fs resolution=%dx%d",
+        path,
+        result.file_size,
+        result.duration,
+        result.width,
+        result.height,
+    )
+    return result
+
+
+def _check_moov_atom(video_path: Path) -> bool:
+    """检查 MP4 文件是否包含 moov atom。
+
+    moov atom 是 MP4 容器的元数据容器，包含视频时长、编解码器信息等。
+    FFmpeg 使用 -movflags +faststart 时 moov 在文件头部；否则在尾部。
+    如果 FFmpeg 被强制终止，moov 可能完全不存在。
+
+    方法：读取文件前 64KB + 尾部 64KB，搜索 "moov" 字节标记。
+    对于 -movflags +faststart 的快启文件，moov 在头部。
+
+    Args:
+        video_path: 视频文件路径
+
+    Returns:
+        True 表示找到 moov atom
+    """
+    try:
+        file_size = video_path.stat().st_size
+        if file_size < 8:
+            return False
+
+        # 搜索范围：头部 64KB + 尾部 64KB（覆盖 faststart 和普通 MP4）
+        search_size = min(64 * 1024, file_size)
+
+        with open(video_path, "rb") as f:
+            # 读取头部
+            head_data = f.read(search_size)
+            if b"moov" in head_data:
+                return True
+
+            # 读取尾部
+            if file_size > search_size:
+                f.seek(file_size - search_size)
+                tail_data = f.read(search_size)
+                if b"moov" in tail_data:
+                    return True
+
+        return False
+
+    except OSError as e:
+        logger.warning("[video-validation] 检查 moov atom 失败: %s", e)
+        return False

apps/worker/worker_app/tasks/_startup.py

@@ -1,4 +1,4 @@
-"""Worker 启动时的初始化任务 — 孤儿任务清理等。"""
+"""Worker 启动时的初始化任务 — 孤儿任务清理等."""
 
 import logging
 
@@ -7,11 +7,12 @@ from worker_app.db import SessionLocal
 
 logger = logging.getLogger(__name__)
 
+# 孤儿任务超时阈值：渲染任务超过此时间未更新则视为卡死
 ORPHAN_TASK_TIMEOUT_MINUTES = 10
 
 
-def cleanup_orphan_tasks(timeout_minutes: int = ORPHAN_TASK_TIMEOUT_MINUTES) -> int:
-    """清理数据库中超时未更新的 running 任务。
+def cleanup_orphan_tasks(timeout_minutes: int = ORPHAN_TASK_TIMEOUT_MINUTES) -> int:  # pragma: no cover
+    """清理数据库中超时未更新的 running GenerationTask（孤儿任务）。
 
     worker 重启或崩溃后，之前处于 running 状态的任务会变成孤儿任务，
     一直卡在 running 不动。通过 updated_at 超时判断并标记为 failed。
@@ -32,18 +33,81 @@ def cleanup_orphan_tasks(timeout_minutes: int = ORPHAN_TASK_TIMEOUT_MINUTES) ->
         count = repo.cleanup_stale_running(timeout_minutes)
         session.close()
         if count > 0:
-            logger.warning("清理了 %d 个超时的孤儿 running 任务", count)
+            logger.warning("清理了 %d 个超时的孤儿 GenerationTask（超过 %d 分钟未更新）", count, timeout_minutes)
         else:
-            logger.info("无孤儿 running 任务需要清理")
+            logger.info("无孤儿 GenerationTask 需要清理")
         return count
     except Exception as e:
-        logger.error("清理孤儿任务失败: %s", e, exc_info=True)
+        logger.error("清理孤儿 GenerationTask 失败: %s", e, exc_info=True)
         return 0
 
 
+def cleanup_stale_jobs(timeout_minutes: int = ORPHAN_TASK_TIMEOUT_MINUTES) -> int:  # pragma: no cover
+    """清理数据库中超时未更新的 running Job（孤儿任务）。
+
+    与 cleanup_orphan_tasks 配合，同时清理 Job 表和 GenerationTask 表。
+
+    Returns:
+        清理的任务数量
+    """
+    from datetime import datetime, timedelta, timezone
+
+    from packages.adapters.sqlalchemy_impl.models import JobModel
+    from packages.domain.job import JobStatus
+
+    try:
+        session = SessionLocal()
+        cutoff = datetime.now(timezone.utc) - timedelta(minutes=timeout_minutes)
+        stale_jobs = (
+            session.query(JobModel)
+            .filter(
+                JobModel.status == JobStatus.RUNNING.value,
+                JobModel.updated_at < cutoff,
+            )
+            .all()
+        )
+        count = 0
+        for model in stale_jobs:
+            model.status = JobStatus.FAILED.value
+            model.error_message = f"任务执行中断（超过 {timeout_minutes} 分钟未更新）"
+            count += 1
+        if count > 0:
+            session.commit()
+            logger.warning("清理了 %d 个超时的孤儿 Job（超过 %d 分钟未更新）", count, timeout_minutes)
+        else:
+            logger.info("无孤儿 Job 需要清理")
+        session.close()
+        return count
+    except Exception as e:
+        logger.error("清理孤儿 Job 失败: %s", e, exc_info=True)
+        return 0
+
+
+def cleanup_all_stale_tasks(timeout_minutes: int = ORPHAN_TASK_TIMEOUT_MINUTES) -> dict:  # pragma: no cover
+    """统一清理所有超时的孤儿任务。
+
+    同时清理 GenerationTask 和 Job 两类表。
+
+    Returns:
+        {"generation_tasks": int, "jobs": int}
+    """
+    gen_count = cleanup_orphan_tasks(timeout_minutes)
+    job_count = cleanup_stale_jobs(timeout_minutes)
+    total = gen_count + job_count
+    if total > 0:
+        logger.warning(
+            "孤儿任务清理完成: GenerationTask=%d, Job=%d, 总计=%d",
+            gen_count,
+            job_count,
+            total,
+        )
+    return {"generation_tasks": gen_count, "jobs": job_count}
+
+
 @worker_ready.connect
-def _on_worker_ready(sender, **kwargs):
+def _on_worker_ready(sender, **kwargs):  # pragma: no cover
     """Worker 启动完成后执行 — 清理孤儿任务。"""
     logger.info("Worker 启动完成，开始清理孤儿 running 任务...")
-    count = cleanup_orphan_tasks()
-    logger.info("Worker 启动清理完成，共清理 %d 个孤儿任务", count)
+    result = cleanup_all_stale_tasks()
+    total = result["generation_tasks"] + result["jobs"]
+    logger.info("Worker 启动清理完成，共清理 %d 个孤儿任务", total)

apps/worker/worker_app/tasks/compose_video.py

@@ -6,15 +6,22 @@
 from __future__ import annotations
 
 import os
+import subprocess  # pragma: no cover
 import tempfile
 from pathlib import Path
 
+from celery.exceptions import SoftTimeLimitExceeded  # pragma: no cover
 from celery.utils.log import get_task_logger
 from worker_app.celery_app import celery_app
 from worker_app.db import SessionLocal
 
 logger = get_task_logger(__name__)
 
+# 任务超时时间（秒）：超过此时间 Celery 会抛出 SoftTimeLimitExceeded
+RENDER_TASK_SOFT_TIME_LIMIT = 600  # pragma: no cover  # 10 分钟
+# 硬超时：超过此时间进程会被强制 kill
+RENDER_TASK_TIME_LIMIT = 660  # pragma: no cover  # 10 分钟 + 1 分钟清理缓冲
+
 
 def _get_job_service():
     """延迟导入 JobService，避免循环依赖。"""
@@ -31,8 +38,10 @@ def _get_job_service():
     bind=True,
     max_retries=3,
     default_retry_delay=60,
+    soft_time_limit=RENDER_TASK_SOFT_TIME_LIMIT,
+    time_limit=RENDER_TASK_TIME_LIMIT,
 )
-def compose_video(self, job_id: str, **kwargs):
+def compose_video(self, job_id: str, **kwargs):  # pragma: no cover
     """视频合成任务。
 
     使用 UnifiedRenderService（图层架构）进行渲染。
@@ -57,9 +66,51 @@ def compose_video(self, job_id: str, **kwargs):
         # 使用 unified 渲染引擎
         return _compose_with_unified_engine(self, job_service, job, plan_id, db)
 
+    except SoftTimeLimitExceeded:
+        # Celery 软超时：任务执行超过 soft_time_limit
+        error_msg = f"渲染任务超时（超过 {RENDER_TASK_SOFT_TIME_LIMIT // 60} 分钟）"
+        logger.error("视频合成超时: job_id=%s", job_id)
+        try:
+            job_service.fail_job(job_id, error_msg)
+        except Exception:
+            logger.exception("更新 Job 超时失败状态时出错")
+        # 超时不重试
+        return {"status": "error", "message": error_msg, "error_type": "timeout"}
+
+    except subprocess.TimeoutExpired as exc:
+        # FFmpeg 子进程超时
+        error_msg = f"FFmpeg 渲染超时（{exc.timeout}s）"
+        logger.error("视频合成 FFmpeg 超时: job_id=%s timeout=%s", job_id, exc.timeout)
+        try:
+            job_service.fail_job(job_id, error_msg)
+        except Exception:
+            logger.exception("更新 Job 超时失败状态时出错")
+        # 超时不重试
+        return {"status": "error", "message": error_msg, "error_type": "ffmpeg_timeout"}
+
     except self.retry_exc as exc:
         logger.warning("视频合成重试中: job_id=%s, exc=%s", job_id, exc)
         raise
+
+    except subprocess.CalledProcessError as exc:
+        # FFmpeg 执行失败，提取有意义的错误信息
+        from video_processing.video_validation import get_exit_code_message
+
+        exit_msg = get_exit_code_message(exc.returncode)
+        stderr_text = (exc.stderr or "").strip()
+        stderr_tail = stderr_text[-300:] if len(stderr_text) > 300 else stderr_text
+        error_msg = f"渲染失败: {exit_msg}"
+        if stderr_tail:
+            error_msg += f" | {stderr_tail[:200]}"
+
+        logger.error("视频合成 FFmpeg 失败: job_id=%s %s", job_id, exit_msg)
+        try:
+            job_service.fail_job(job_id, error_msg[:500])
+        except Exception:
+            logger.exception("更新 Job 失败状态时出错")
+        # FFmpeg 错误不重试（通常是素材或配置问题）
+        return {"status": "error", "message": error_msg, "error_type": "ffmpeg_error", "exit_code": exc.returncode}
+
     except Exception as exc:
         logger.exception("视频合成异常: job_id=%s", job_id)
         try:
@@ -71,7 +122,7 @@ def compose_video(self, job_id: str, **kwargs):
         db.close()
 
 
-def _compose_with_unified_engine(task, job_service, job, plan_id: str, db) -> dict:
+def _compose_with_unified_engine(task, job_service, job, plan_id: str, db) -> dict:  # pragma: no cover
     """新引擎渲染路径（UnifiedRenderService + RenderAdapter）。"""
     job_id = job.id
 
@@ -108,9 +159,40 @@ def _compose_with_unified_engine(task, job_service, job, plan_id: str, db) -> di
     )
 
     if not result.success:
-        job_service.fail_job(job_id, f"渲染失败: {result.error_message}")
+        error_msg = f"渲染失败: {result.error_message}"
+        job_service.fail_job(job_id, error_msg[:500])
         raise RuntimeError(result.error_message)
 
+    # 生成封面（如果配置启用）
+    cover_url = None
+    try:
+        from video_processing.cover_generator import generate_cover_from_plan
+
+        from packages.adapters.sqlalchemy_impl.edit_plan_repository import (
+            SQLAlchemyEditPlanRepository as EditPlanRepository,
+        )
+
+        # 获取 plan 对象
+        plan_repo = EditPlanRepository(db)
+        plan = plan_repo.get(plan_id)
+
+        if plan and result.output_path:
+            # 检查 cover_config
+            cover_config = (plan.config or {}).get("cover_config")
+            if cover_config and cover_config.get("enabled", False):
+                from pathlib import Path
+
+                output_dir = Path(result.output_path).parent
+                cover_path = generate_cover_from_plan(plan, result.output_path, output_dir)
+                if cover_path:
+                    # 生成 cover_url（相对路径或上传到存储）
+                    cover_url = f"/covers/{plan_id}.jpg"
+                    logger.info("封面生成成功: plan_id=%s cover_path=%s", plan_id, cover_path)
+            else:
+                logger.info("封面生成未启用: plan_id=%s", plan_id)
+    except Exception as e:
+        logger.warning("封面生成失败（不影响视频合成）: plan_id=%s error=%s", plan_id, e)
+
     # 更新 Job 状态为完成
     result_data = {
         "plan_id": plan_id,
@@ -123,6 +205,7 @@ def _compose_with_unified_engine(task, job_service, job, plan_id: str, db) -> di
         "width": result.width,
         "height": result.height,
         "file_size": result.file_size,
+        "cover_url": cover_url,
     }
     job_service.complete_job(job_id, result=result_data)
 

apps/worker/worker_app/tasks/edit_plan_generation.py

@@ -271,8 +271,14 @@ def _render_with_unified(
     )
 
 
-@celery_app.task(name="worker.render_edit_plan", bind=True, max_retries=2)
-def render_edit_plan(self, plan_id: str) -> dict:
+@celery_app.task(
+    name="worker.render_edit_plan",
+    bind=True,
+    max_retries=2,
+    soft_time_limit=600,  # 10 分钟软超时
+    time_limit=660,  # 11 分钟硬超时
+)
+def render_edit_plan(self, plan_id: str) -> dict:  # pragma: no cover
     """渲染剪辑计划
 
     流程：
@@ -360,8 +366,17 @@ def render_edit_plan(self, plan_id: str) -> dict:
             return result
 
         except Exception as exc:
-            logger.exception("渲染剪辑计划异常: %s", plan_id)
+            # 超时异常不重试，直接标记失败
+            from celery.exceptions import SoftTimeLimitExceeded
+
+            is_timeout = isinstance(exc, SoftTimeLimitExceeded)
+            if is_timeout:
+                logger.error("渲染剪辑计划超时: plan_id=%s", plan_id)
+            else:
+                logger.exception("渲染剪辑计划异常: %s", plan_id)
+
             # 尝试标记计划和 GenerationTask 为失败
+            error_msg = "渲染任务超时（超过10分钟）" if is_timeout else f"渲染异常: {type(exc).__name__}: {exc}"
             try:
                 plan = plan_repo.get(plan_id)
                 if plan and plan.status.value == "rendering":
@@ -375,12 +390,13 @@ def render_edit_plan(self, plan_id: str) -> dict:
                     gen_task = gen_task_repo.get(generation_task_id)
                     if gen_task and gen_task.status.value != "failed":
                         gen_task.status = "failed"
-                        gen_task.error_message = f"渲染异常: {type(exc).__name__}: {exc}"
+                        gen_task.error_message = error_msg
                         gen_task.completed_at = datetime.now(timezone.utc)
                         try:
+                            log_stage = "render_timeout" if is_timeout else "render_failed"
                             gen_task.append_log(
-                                stage="render_failed",
-                                message=f"渲染异常: {type(exc).__name__}: {str(exc)[:500]}",
+                                stage=log_stage,
+                                message=error_msg[:500],
                                 level="ERROR",
                                 exception_type=type(exc).__name__,
                             )

apps/worker/worker_app/tasks/generation.py

@@ -95,6 +95,42 @@ def _update_task_status(task_id: str, status_action: str, **kwargs) -> bool:
         return False
 
 
+def _update_task_progress(task_id: str, progress: float, stage: str = "") -> bool:
+    """更新 GenerationTask 进度（独立 session，异常不向外抛出）。
+
+    Args:
+        task_id: 任务 ID
+        progress: 进度值（0-100）
+        stage: 阶段描述（仅用于日志）
+
+    Returns:
+        True 表示更新成功
+    """
+    try:
+        from packages.adapters.sqlalchemy_impl.models import GenerationTaskModel
+
+        session = SessionLocal()
+        try:
+            model = session.query(GenerationTaskModel).filter(GenerationTaskModel.id == task_id).first()
+            if model:
+                model.progress = progress
+                session.commit()
+                if stage:
+                    logger.info(
+                        "GenerationTask 进度更新: task_id=%s progress=%.0f%% stage=%s",
+                        task_id,
+                        progress,
+                        stage,
+                    )
+                return True
+            return False
+        finally:
+            session.close()
+    except Exception as e:
+        logger.error("更新任务进度异常: task_id=%s progress=%s error=%s", task_id, progress, e)
+        return False
+
+
 # ── 日志持久化辅助 ────────────────────────────────────────────────────────────
 
 
@@ -153,6 +189,43 @@ def _load_template_clip_configs(template_id: str) -> list:
         return []
 
 
+def _load_template_segment_durations(template_id: str) -> list[float]:
+    """从数据库读取模板各 segment 的 duration_max 列表（按 segment_order 排序）。
+
+    用于限制每个 clip 的最大时长，防止素材完整时长超过模板约束。
+    失败返回空列表，不阻断主流程。
+    """
+    if not template_id:
+        return []
+    try:
+        from worker_app.db import SessionLocal
+
+        from packages.adapters.sqlalchemy_impl.models import TemplateSegmentModel
+
+        session = SessionLocal()
+        try:
+            segments = (
+                session.query(TemplateSegmentModel)
+                .filter(TemplateSegmentModel.template_id == template_id)
+                .order_by(TemplateSegmentModel.segment_order)
+                .all()
+            )
+            durations = [s.duration_max for s in segments if s.duration_max and s.duration_max > 0]
+            if durations:
+                logger.info(
+                    "读取模板segment时长约束: template_id=%s segments=%d durations=%s",
+                    template_id,
+                    len(durations),
+                    durations,
+                )
+            return durations
+        finally:
+            session.close()
+    except Exception as e:
+        logger.warning("读取模板segment时长约束失败: template_id=%s error=%s", template_id, e)
+        return []
+
+
 def _build_plan_and_clips_from_task(
     task_id: str,
     downloaded_paths: list[Path],
@@ -162,10 +235,8 @@ def _build_plan_and_clips_from_task(
     """根据模式和下载的素材路径，构建虚拟 plan + clips + asset_path_map。
 
     模式 → clip_type 映射：
-      ONE_TAKE:     N 个 main clips
-      PIP:          1 main + N-1 overlay
+      ONE_TAKE:     N 个 main clips（默认，pip/voice_pip 已统一映射为此模式）
       VOICE_OVER:   N 个 main(config.role=b_roll)
-      VOICE_PIP:    1 background + 1 corner_voice + N-2 b_roll
 
     Returns:
         (virtual_plan, virtual_clips, asset_path_map)
@@ -182,23 +253,14 @@ def _build_plan_and_clips_from_task(
         path_to_asset_id[p] = asset_id
         path_duration[p] = probe_duration(p)
 
+    # 产品已确认全面下线画中画，pip/voice_pip统一走one_take（顺序拼接）
+    if mode in ("pip", "voice_pip"):
+        logger.info("画中画模式已下线，%s 强制映射为 one_take", mode)
+        mode = "one_take"
+
     clips: list[_VirtualClip] = []
 
-    if mode == "pip":
-        # 1 main + N-1 overlay
-        for i, p in enumerate(downloaded_paths):
-            clip_type = "main" if i == 0 else "overlay"
-            clips.append(
-                _VirtualClip(
-                    id=f"vc_{i:03d}",
-                    plan_id=task_id,
-                    clip_type=clip_type,
-                    order=i,
-                    asset_id=path_to_asset_id[p],
-                    duration=path_duration[p],
-                )
-            )
-    elif mode == "voice_over":
+    if mode == "voice_over":
         # N 个 main(config.role=b_roll)
         for i, p in enumerate(downloaded_paths):
             clips.append(
@@ -212,25 +274,6 @@ def _build_plan_and_clips_from_task(
                     config={"role": "b_roll"},
                 )
             )
-    elif mode == "voice_pip":
-        # 1 background + 1 corner_voice + N-2 b_roll
-        for i, p in enumerate(downloaded_paths):
-            if i == 0:
-                clip_type = "background"
-            elif i == 1:
-                clip_type = "corner_voice"
-            else:
-                clip_type = "b_roll"
-            clips.append(
-                _VirtualClip(
-                    id=f"vc_{i:03d}",
-                    plan_id=task_id,
-                    clip_type=clip_type,
-                    order=i,
-                    asset_id=path_to_asset_id[p],
-                    duration=path_duration[p],
-                )
-            )
     else:
         # ONE_TAKE (default): N 个 main clips
         for i, p in enumerate(downloaded_paths):
@@ -245,6 +288,25 @@ def _build_plan_and_clips_from_task(
                 )
             )
 
+    # ── P1-2: 模板 segment 时长约束 ──
+    if template_id and clips:
+        seg_durations = _load_template_segment_durations(template_id)
+        if seg_durations:
+            capped_count = 0
+            for idx, clip in enumerate(clips):
+                if idx < len(seg_durations):
+                    max_dur = seg_durations[idx]
+                    if clip.duration > max_dur:
+                        clip.duration = max_dur
+                        capped_count += 1
+            if capped_count > 0:
+                logger.info(
+                    "模板时长约束已应用: template_id=%s capped_clips=%d/%d",
+                    template_id,
+                    capped_count,
+                    len(clips),
+                )
+
     # ── P1: 模板效果层映射 ──
     if template_id:
         clip_configs = _load_template_clip_configs(template_id)
@@ -600,11 +662,11 @@ def _download_library_assets(
         下载成功的视频文件 Path 列表
 
     Raises:
-        ValueError: 当 asset_library_id 和 project_id 都为空时
+        ValueError: 当 asset_library_id、project_id 和 asset_ids 都为空时
         RuntimeError: strict=True 时任何下载失败；或指定了 asset_ids 但全部下载失败
     """
-    if not asset_library_id and not project_id:
-        raise ValueError("asset_library_id 和 project_id 至少需要提供一个")
+    if not asset_library_id and not project_id and not asset_ids:
+        raise ValueError("asset_library_id、project_id 或 asset_ids 至少需要提供一个")
 
     try:
         from packages.adapters.sqlalchemy_impl.models import AssetModel
@@ -646,7 +708,11 @@ def _download_library_assets(
             assets = query.order_by(AssetModel.created_at).all()
 
             if not assets:
-                mode_desc = f"素材库 {asset_library_id}" if asset_library_id else f"项目 {project_id}"
+                mode_desc = (
+                    f"素材库 {asset_library_id}"
+                    if asset_library_id
+                    else (f"项目 {project_id}" if project_id else "指定素材")
+                )
                 msg = f"未找到视频素材: {mode_desc}, asset_ids={asset_ids or 'all'}"
                 logger.error(msg)
                 raise RuntimeError(msg)
@@ -677,7 +743,8 @@ def _download_library_assets(
                     len(asset_ids),
                 )
 
-            downloaded: list[Path] = []
+            # 构建待下载列表 (index, asset, storage_key, local_file)
+            download_jobs: list[tuple[int, Any, str, Path]] = []
             failed_assets: list[str] = []
             for i, asset in enumerate(assets):
                 storage_key = asset.file_url if asset.file_url else None
@@ -706,52 +773,81 @@ def _download_library_assets(
 
                 ext = Path(storage_key).suffix or ".mp4"
                 local_file = temp_path / f"asset_{i:03d}_{asset.id}{ext}"
-                asset_start = time.monotonic()
-                download_ok = download_asset(storage_key, local_file)
-                asset_elapsed = time.monotonic() - asset_start
+                download_jobs.append((i, asset, storage_key, local_file))
 
-                if download_ok:
-                    file_size = local_file.stat().st_size if local_file.exists() else 0
-                    downloaded.append(local_file)
-                    logger.info(
-                        "[task_id=%s] Downloaded asset: %s -> %s (size=%d, time=%.1fs)",
-                        task_id,
-                        asset.name,
-                        local_file,
-                        file_size,
-                        asset_elapsed,
-                    )
-                    if gen_task:
-                        gen_task.append_log(
-                            "下载素材",
-                            f"下载成功: {asset.name}",
-                            asset_id=asset.id,
-                            asset_name=asset.name,
-                            success=True,
-                            file_size=file_size,
-                            duration=round(asset_elapsed, 2),
+            # 并行下载素材（线程池，IO 密集型）
+            downloaded: list[Path] = []
+            if download_jobs:
+                from concurrent.futures import ThreadPoolExecutor, as_completed
+
+                max_workers = min(len(download_jobs), 6)
+                logger.info(
+                    "[task_id=%s] 并行下载素材: count=%d, workers=%d",
+                    task_id,
+                    len(download_jobs),
+                    max_workers,
+                )
+
+                def _download_one(item: tuple) -> tuple[int, Any, Path, bool, float]:
+                    idx, asset, skey, lfile = item
+                    t0 = time.monotonic()
+                    ok = download_asset(skey, lfile)
+                    elapsed = time.monotonic() - t0
+                    return idx, asset, lfile, ok, elapsed
+
+                with ThreadPoolExecutor(max_workers=max_workers) as executor:
+                    futures = {executor.submit(_download_one, job): job for job in download_jobs}
+                    # 按原始顺序收集结果，保证 downloaded 列表顺序稳定
+                    results_map: dict[int, tuple[Path, bool, float, Any]] = {}
+                    for future in as_completed(futures):
+                        idx, asset, lfile, ok, elapsed = future.result()
+                        results_map[idx] = (lfile, ok, elapsed, asset)
+
+                # 按原始顺序处理结果
+                for idx in sorted(results_map.keys()):
+                    lfile, ok, elapsed, asset = results_map[idx]
+                    if ok:
+                        file_size = lfile.stat().st_size if lfile.exists() else 0
+                        downloaded.append(lfile)
+                        logger.info(
+                            "[task_id=%s] Downloaded asset: %s -> %s (size=%d, time=%.1fs)",
+                            task_id,
+                            asset.name,
+                            lfile,
+                            file_size,
+                            elapsed,
                         )
-                else:
-                    failed_assets.append(f"{asset.name}({asset.id})")
-                    logger.warning(
-                        "[task_id=%s] Failed to download asset: %s (id=%s)",
-                        task_id,
-                        asset.name,
-                        asset.id,
-                    )
-                    if gen_task:
-                        gen_task.append_log(
-                            "下载素材",
-                            f"下载失败: {asset.name}",
-                            level="WARN",
-                            asset_id=asset.id,
-                            asset_name=asset.name,
-                            success=False,
-                            file_size=0,
-                            duration=round(asset_elapsed, 2),
+                        if gen_task:
+                            gen_task.append_log(
+                                "下载素材",
+                                f"下载成功: {asset.name}",
+                                asset_id=asset.id,
+                                asset_name=asset.name,
+                                success=True,
+                                file_size=file_size,
+                                duration=round(elapsed, 2),
+                            )
+                    else:
+                        failed_assets.append(f"{asset.name}({asset.id})")
+                        logger.warning(
+                            "[task_id=%s] Failed to download asset: %s (id=%s)",
+                            task_id,
+                            asset.name,
+                            asset.id,
                         )
-                    if strict:
-                        raise RuntimeError(f"素材下载失败: asset_id={asset.id}, name={asset.name}")
+                        if gen_task:
+                            gen_task.append_log(
+                                "下载素材",
+                                f"下载失败: {asset.name}",
+                                level="WARN",
+                                asset_id=asset.id,
+                                asset_name=asset.name,
+                                success=False,
+                                file_size=0,
+                                duration=round(elapsed, 2),
+                            )
+                        if strict:
+                            raise RuntimeError(f"素材下载失败: asset_id={asset.id}, name={asset.name}")
 
             # 指定了 asset_ids 但全部下载失败 → 无论 strict 与否都报错
             if asset_ids and not downloaded:
@@ -943,6 +1039,13 @@ def _load_task_info(task_id: str) -> dict | None:
             "video_title": getattr(gen_task, "video_title", "") or "",
             "resolution": getattr(gen_task, "resolution", "") or "",
             "bgm_config": dict(getattr(gen_task, "bgm_config", {}) or {}),
+            "is_preview": bool(getattr(gen_task, "is_preview", False)),
+            "source_task_id": getattr(gen_task, "source_task_id", "") or "",
+            "output_width": getattr(gen_task, "output_width", OUTPUT_WIDTH) or OUTPUT_WIDTH,
+            "output_height": getattr(gen_task, "output_height", OUTPUT_HEIGHT) or OUTPUT_HEIGHT,
+            "cover_url": getattr(gen_task, "cover_url", "") or "",
+            "custom_title": getattr(gen_task, "custom_title", "") or "",
+            "voice_ids": list(getattr(gen_task, "voice_ids", []) or []),
         }
     finally:
         session.close()
@@ -1003,11 +1106,16 @@ def _render_video(
     output_name: str,
     resolution: str = "",
     bgm_config: dict | None = None,
+    is_preview: bool = False,
+    voice_ids: list[str] | None = None,
 ) -> tuple[Path, float]:
     """渲染视频（含配音混音）。
 
     使用 RenderAdapter 统一渲染入口，复用 BGM/ASR/分辨率/缩略图逻辑。
 
+    Args:
+        is_preview: 是否为预览生成，若是则强制 480p + 低码率
+
     Returns:
         (output_path, render_duration)
     """
@@ -1050,16 +1158,44 @@ def _render_video(
 
     # 确保输出分辨率配置存在
     # 优先级：用户指定 > 模板配置 > 默认 1280x720
-    plan_cfg = virtual_plan.config or {}
-    export_cfg = plan_cfg.get("export", {}) or {}
-    if resolution:
+    # 预览模式：强制 854x480 + 低码率
+    # 注意：必须拷贝字典，避免预览模式修改污染源对象（模板配置）
+    plan_cfg = dict(virtual_plan.config or {})
+    export_cfg = dict(plan_cfg.get("export", {}) or {})
+    if is_preview:
+        # 预览模式：短边 480p + 低码率，但尊重视频比例（竖屏模板不应强制横屏）
+        preview_res = resolution if resolution else "854x480"
+        export_cfg["resolution"] = preview_res
+        export_cfg["bitrate"] = "1M"
+        logger.info(
+            "[task_id=%s] [渲染] 预览模式：分辨率=%s, 码率=%s",
+            task_id,
+            preview_res,
+            "1M",
+        )
+    elif resolution:
         # 用户在 API 调用时指定的分辨率优先级最高
         export_cfg["resolution"] = resolution
     elif not export_cfg.get("resolution"):
         export_cfg["resolution"] = f"{OUTPUT_WIDTH}x{OUTPUT_HEIGHT}"
+    # 将修改后的配置写回 virtual_plan（拷贝后的副本，不影响原始数据源）
     plan_cfg["export"] = export_cfg
     virtual_plan.config = plan_cfg
 
+    # 注入用户选择的配音 voice_id（ASR 字幕对齐模式）
+    if voice_ids:
+        plan_cfg = dict(virtual_plan.config or {})
+        plan_cfg["voice_id"] = voice_ids[0]
+        subtitle_cfg = plan_cfg.get("subtitle", {}) or {}
+        subtitle_cfg["auto_generated"] = True
+        plan_cfg["subtitle"] = subtitle_cfg
+        virtual_plan.config = plan_cfg
+        logger.info(
+            "[task_id=%s] [渲染] 预览配音已注入: voice_id=%s",
+            task_id,
+            voice_ids[0],
+        )
+
     total_duration = sum(c.duration for c in virtual_clips)
     logger.info(
         "[task_id=%s] [剪辑计划] 片段数=%d, 总时长=%.1fs",
@@ -1086,6 +1222,7 @@ def _render_video(
             job_id=task_id,
             work_dir=temp_path,
             voiceover_audio_path=voice_path,
+            is_preview=is_preview,
         )
     finally:
         db.close()
@@ -1184,7 +1321,13 @@ def _upload_and_record(
 # ── Celery Task ──────────────────────────────────────────────────────────────
 
 
-@celery_app.task(bind=True, name="worker.generate_video", max_retries=2)
+@celery_app.task(
+    bind=True,
+    name="worker.generate_video",
+    max_retries=2,
+    soft_time_limit=600,  # 10 分钟软超时
+    time_limit=660,  # 11 分钟硬超时
+)
 def generate_video(self, task_id: str) -> dict:
     """生成视频任务 — 使用 UnifiedRenderService 统一渲染。
 
@@ -1255,6 +1398,7 @@ def generate_video(self, task_id: str) -> dict:
 
     # 标记任务为 running
     _update_task_status(task_id, "mark_processing")
+    _update_task_progress(task_id, 10, "任务启动")
 
     try:
         editing_mode = EditingMode(mode) if (mode := task_info["mode"]) else EditingMode.ONE_TAKE
@@ -1288,7 +1432,18 @@ def generate_video(self, task_id: str) -> dict:
                 )
                 _flush_logs(task_id, gen_task)
 
+            _update_task_progress(task_id, 30, "素材下载完成")
+
             # ── 3. 渲染 + 混音 ───────────────────────────────────────────────
+            _update_task_progress(task_id, 40, "开始渲染")
+            # 动态分辨率：优先使用 output_width/output_height，其次 resolution 字符串
+            _ow = task_info.get("output_width", OUTPUT_WIDTH) or OUTPUT_WIDTH
+            _oh = task_info.get("output_height", OUTPUT_HEIGHT) or OUTPUT_HEIGHT
+            if _ow != OUTPUT_WIDTH or _oh != OUTPUT_HEIGHT:
+                _resolved_resolution = f"{_ow}x{_oh}"
+            else:
+                _resolved_resolution = task_info.get("resolution", "")
+
             output_path, render_duration = _render_video(
                 task_id=task_id,
                 downloaded_videos=downloaded_videos,
@@ -1299,15 +1454,20 @@ def generate_video(self, task_id: str) -> dict:
                 user_id=user_id,
                 temp_path=temp_path,
                 output_name=output_name,
-                resolution=task_info.get("resolution", ""),
+                resolution=_resolved_resolution,
                 bgm_config=task_info.get("bgm_config", {}),
+                is_preview=task_info.get("is_preview", False),
+                voice_ids=task_info.get("voice_ids", []),
             )
 
             if gen_task:
                 gen_task.append_log("渲染", f"渲染完成, 时长={render_duration:.1f}s")
                 _flush_logs(task_id, gen_task)
 
+            _update_task_progress(task_id, 80, "渲染完成")
+
             # ── 4. 上传 OSS + 查重记录 ───────────────────────────────────────
+            _update_task_progress(task_id, 85, "开始上传")
             file_url, duration, file_size, video_count = _upload_and_record(
                 task_id=task_id,
                 output_path=output_path,
@@ -1327,6 +1487,8 @@ def generate_video(self, task_id: str) -> dict:
                 )
                 _flush_logs(task_id, gen_task)
 
+            _update_task_progress(task_id, 95, "上传完成")
+
             # ── 5. 标记完成 ──────────────────────────────────────────────────
             _update_task_status(task_id, "mark_completed", result_count=video_count)
 

docs/1197_preview_generation_proposal.md

@@ -0,0 +1,208 @@
+# #1197 预览生成接口方案评估
+
+## 背景
+
+智能剪辑「一键生成」流程中，第3步预览生成当前被跳过，直接进入下一步。需要实现真正的预览生成功能，让用户在正式生成前能看到效果预览。
+
+## 现状分析
+
+### 现有生成链路
+
+```
+API 触发生成 → GenerationTask入库 → Celery异步任务 → UnifiedRenderService渲染 → OSS上传 → 更新状态
+```
+
+**关键节点：**
+1. **API层**：`POST /generation-tasks` 或 `POST /templates/{id}/generate` 触发生成
+2. **任务调度**：Celery task `worker.generate_video`
+3. **渲染引擎**：`UnifiedRenderService`（统一渲染引擎，已接入9个效果层）
+4. **输出配置**：默认 720p (1280x720)，支持 `resolution` 字段自定义
+5. **产物存储**：`GeneratedVideo` 表记录，OSS 存储视频文件
+
+### 已有可复用能力
+
+| 能力 | 位置 | 是否可复用 |
+|------|------|-----------|
+| 任务创建与状态管理 | `GenerationTask` + `CreateGenerationTaskUseCase` | ✅ 是 |
+| 素材下载与预处理 | `_download_video_assets` / `_download_voice_asset` | ✅ 是 |
+| 统一渲染引擎 | `UnifiedRenderService` | ✅ 是 |
+| 分辨率配置 | `resolution` 字段已支持 | ✅ 是 |
+| 混音与后处理 | `_render_video` 内流程 | ✅ 是 |
+| OSS 上传与查重 | `_upload_and_dedup` | ✅ 是 |
+| 进度追踪 | `append_log` / `progress` 字段 | ✅ 是 |
+
+## 方案对比
+
+### 方案A：复用现有生成链路 + is_preview 标记（推荐）
+
+**思路**：在现有 GenerationTask 上加 `is_preview` 标记，预览生成走完整链路但参数降级。
+
+**改动点：**
+1. **数据模型**：`GenerationTask` 加 `is_preview: bool` 字段（默认 false）；`GeneratedVideo` 加 `is_preview: bool`
+2. **API 层**：生成接口加 `is_preview` 参数，预览任务不计入配额
+3. **渲染参数**：预览模式下自动调整
+   - 分辨率：480p (854x480)
+   - 时长：限制前 15 秒（或模板第一个片段）
+   - 码率：降低至 1.5Mbps（正式 4Mbps）
+   - 效果层：跳过高级转场/粒子特效等耗时效果
+4. **任务调度**：预览任务走低优先级队列（或复用现有队列，标记优先级）
+5. **前端对接**：预览生成结果带 `is_preview=true` 标记，前端展示"预览"标签
+
+**优点：**
+- 代码复用率 90%+，改动最小
+- 与正式生成逻辑一致，预览效果真实可信
+- 进度查询、结果展示等功能直接复用
+- 后续可平滑升级：预览满意后一键转正式生成
+
+**缺点：**
+- 需要区分预览和正式任务，避免数据混淆
+- 预览任务和正式任务竞争同一队列资源（可后续优化为独立队列）
+
+**开发量估算**：2-3 天
+- 数据模型 + 迁移：0.5 天
+- API 层改造：0.5 天
+- 渲染参数降级：1 天
+- 测试 + 联调：1 天
+
+---
+
+### 方案B：新建独立预览接口 + 轻量渲染逻辑
+
+**思路**：新建独立的预览生成接口，使用简化的渲染逻辑（如只拼接素材+基础配音，跳过大部分效果）。
+
+**改动点：**
+1. 新增 `PreviewTask` 数据模型
+2. 新增 `POST /api/v1/preview/generate` 接口
+3. 新增独立的 Celery task `worker.generate_preview`
+4. 简化渲染流程：只做素材裁剪+拼接+配音，跳过转场/滤镜/字幕特效等
+
+**优点：**
+- 完全隔离，不影响正式生成链路
+- 可以做极致优化，预览生成速度快
+- 数据模型清晰，不会混淆
+
+**缺点：**
+- 代码重复率高，两套生成逻辑维护成本翻倍
+- 预览效果与正式生成可能不一致（效果层差异）
+- 前端需要对接两套接口
+- 无法从预览升级为正式生成（需重新走完整流程）
+
+**开发量估算**：4-5 天
+- 数据模型 + 接口：1 天
+- 简化渲染逻辑：2 天
+- 测试 + 联调：1-2 天
+
+---
+
+### 方案C：图片预览（首帧/关键帧截图）
+
+**思路**：不生成视频，只生成几张关键帧的预览图片。
+
+**优点：**
+- 生成速度极快（秒级）
+- 资源消耗小
+
+**缺点：**
+- 预览效果差，用户无法感知动态效果
+- 无法验证配音、转场、节奏等时间维度的效果
+- 用户体验不佳，不如"真预览"有说服力
+
+**开发量估算**：1-2 天
+
+---
+
+## 推荐方案：方案A（复用现有生成链路）
+
+### 核心理由
+
+1. **效果保真**：预览和正式生成用同一套渲染引擎，效果一致，用户信任度高
+2. **开发效率**：90% 代码复用，2-3 天可上线
+3. **可扩展性强**：后续可加「预览转正式」「低分辨率快速预览」等增强功能
+4. **维护成本低**：一套生成逻辑，bug 修复和新功能同时生效
+
+### 详细设计
+
+#### 1. 数据模型变更
+
+```python
+# GenerationTask 新增字段
+is_preview: bool = False
+"""是否为预览生成"""
+
+preview_of: str = ""
+"""预览对应的正式任务 ID（或反向关联）"""
+
+# GeneratedVideo 新增字段
+is_preview: bool = False
+"""是否为预览视频"""
+```
+
+**迁移**：alembic 新增 migration，两个表各加 1-2 个字段。
+
+#### 2. API 层
+
+```
+POST /api/v1/generation-tasks
+  Body 增加 is_preview: bool = false
+  
+POST /api/v1/templates/{id}/generate
+  Query 增加 is_preview: bool = false
+```
+
+**配额处理**：预览生成不计入用户配额，不占用生成次数限制。
+
+#### 3. 渲染参数降级
+
+| 参数 | 正式生成 | 预览生成 |
+|------|---------|---------|
+| 分辨率 | 720p (1280x720) | 480p (854x480) |
+| 码率 | 4 Mbps | 1.5 Mbps |
+| 时长 | 完整时长 | 前 15 秒（或第一段） |
+| 帧率 | 30 fps | 24 fps |
+| 转场效果 | 完整转场 | 仅淡入淡出（或简单切） |
+| 特效滤镜 | 全部启用 | 跳过粒子/光效等高级效果 |
+| 字幕 | 完整渲染 | 正常渲染（字幕是核心信息） |
+| 配音 | 完整混音 | 正常混音（配音是核心信息） |
+
+**实现方式**：在 `_render_video` 或 UnifiedRenderService 入口处，根据 `is_preview` 标记调整渲染配置。
+
+#### 4. 任务调度
+
+- 初期复用现有队列，预览任务正常排队
+- 后续如需优化，可拆分独立预览队列（低优先级）
+- 预览任务可设置较短超时时间
+
+#### 5. 前端对接
+
+- 调用生成接口时传 `is_preview=true`
+- 结果列表中预览视频带「预览」标签
+- 预览满意后可一键「升级为正式生成」（重新触发全分辨率生成，可复用素材下载缓存）
+
+### 实施步骤
+
+**Phase 1（MVP，2天）：**
+1. 数据模型 + 迁移
+2. API 层支持 is_preview 参数
+3. 渲染分辨率降级（480p）
+4. 不计入配额
+5. 基础测试
+
+**Phase 2（优化，1-2天）：**
+1. 时长限制（前15秒）
+2. 效果层降级（跳高级效果）
+3. 预览任务低优先级队列
+4. 预览转正式生成功能
+
+## 与前端对齐点
+
+1. 预览生成的触发时机（第3步自动生成？用户点击才生成？）
+2. 预览时长是固定15秒还是完整但低清？
+3. 是否需要「预览转正式生成」功能
+4. 预览视频的展示形态（和正式视频一样还是有特殊UI）
+
+## 风险与注意事项
+
+1. **数据混淆**：确保统计、计费、列表展示时正确区分预览和正式任务
+2. **存储成本**：预览视频也占 OSS 空间，可设置自动清理（7天后自动删除）
+3. **用户预期**：要明确告诉用户这是预览，效果和正式生成一致但清晰度低
+4. **并发压力**：如果用户频繁生成预览，可能增加系统负载，需要限流

docs/schema-metadata-snapshot.json

@@ -1659,6 +1659,54 @@
           "primary_key": false,
           "type": "DATETIME",
           "unique": false
+        },
+        {
+          "index": false,
+          "name": "is_preview",
+          "nullable": false,
+          "primary_key": false,
+          "type": "BOOLEAN",
+          "unique": false
+        },
+        {
+          "index": true,
+          "name": "source_task_id",
+          "nullable": false,
+          "primary_key": false,
+          "type": "VARCHAR(32)",
+          "unique": false
+        },
+        {
+          "index": false,
+          "name": "output_width",
+          "nullable": false,
+          "primary_key": false,
+          "type": "INTEGER",
+          "unique": false
+        },
+        {
+          "index": false,
+          "name": "output_height",
+          "nullable": false,
+          "primary_key": false,
+          "type": "INTEGER",
+          "unique": false
+        },
+        {
+          "index": false,
+          "name": "cover_url",
+          "nullable": false,
+          "primary_key": false,
+          "type": "VARCHAR(1000)",
+          "unique": false
+        },
+        {
+          "index": false,
+          "name": "custom_title",
+          "nullable": false,
+          "primary_key": false,
+          "type": "VARCHAR(500)",
+          "unique": false
         }
       ],
       "indexes": [
@@ -1717,6 +1765,13 @@
           ],
           "name": "ix_generation_tasks_template_id",
           "unique": false
+        },
+        {
+          "columns": [
+            "source_task_id"
+          ],
+          "name": "ix_generation_tasks_source_task_id",
+          "unique": false
         }
       ],
       "primary_key": [
@@ -3515,4 +3570,4 @@
       ]
     }
   }
-}
+}

infra/docker/compose.yml

@@ -15,7 +15,7 @@
 #   API_PORT         - API 端口映射 (staging: 8000, production: 8001)
 #   WEB_PORT         - Web 端口映射 (staging: 3001, production: 3002)
 #   GENERATED_FILES_HOST_DIR - 生成文件的主机目录
-#   WORKER_CONCURRENCY        - Worker 并发数 (默认: 1)
+#   WORKER_CONCURRENCY        - Worker 并发数 (默认: 4)
 #   WORKER_MAX_TASKS_PER_CHILD - Worker 每个子进程最大任务数 (默认: 100)
 #
 # 重要: 
@@ -109,7 +109,7 @@ services:
     environment:
       APP_ENV: ${APP_ENV:-staging}
       APP_VERSION: ${APP_VERSION:-unknown}
-      WORKER_CONCURRENCY: ${WORKER_CONCURRENCY:-1}
+      WORKER_CONCURRENCY: ${WORKER_CONCURRENCY:-4}
       WORKER_MAX_TASKS_PER_CHILD: ${WORKER_MAX_TASKS_PER_CHILD:-100}
       GENERATED_FILES_DIR: /app/generated
       GENERATED_FILES_URL_PREFIX: /generated-files
@@ -136,14 +136,15 @@ services:
     # 资源限制建议（生产环境建议启用）
     # =========================================
     # 注意: Worker 需要处理视频，建议分配更多资源
+    # 并发 4 时需要 4C8G 以上，确保视频渲染不 OOM
     deploy:
       resources:
         limits:
-          cpus: '2.0'
-          memory: 2g
+          cpus: '4.0'
+          memory: 8g
         reservations:
-          cpus: '0.5'
-          memory: 1G
+          cpus: '1.0'
+          memory: 2G
 
   # =========================================
   # Web 服务（Nginx + 前端静态文件）

infra/docker/deploy-production-registry.sh

@@ -145,7 +145,7 @@ docker run -d \
   --network xiaoxia-net-production \
   -e APP_ENV=production \
   -e APP_VERSION="$IMAGE_TAG" \
-  -e WORKER_CONCURRENCY=1 \
+  -e WORKER_CONCURRENCY="${WORKER_CONCURRENCY:-4}" \
   -e WORKER_MAX_TASKS_PER_CHILD=100 \
   -e GENERATED_FILES_DIR=/app/generated \
   -e GENERATED_FILES_URL_PREFIX=/generated-files \

infra/docker/deploy-production.sh

@@ -81,7 +81,7 @@ export WEB_DOCKERFILE=infra/docker/web-artifact.Dockerfile
 export WEB_NGINX_CONF=infra/docker/nginx-production.conf
 
 docker network create xiaoxia-net-production 2>/dev/null || true
-export WORKER_CONCURRENCY="${WORKER_CONCURRENCY:-1}"
+export WORKER_CONCURRENCY="${WORKER_CONCURRENCY:-4}"
 export WORKER_MAX_TASKS_PER_CHILD="${WORKER_MAX_TASKS_PER_CHILD:-100}"
 
 if [ "${ALLOW_PRODUCTION_BUILDS:-false}" = "true" ]; then