fix(ci): black format test_dedup_pure.py

fix(ci): fix remaining unit test failures (3x assert mismatch + ai_service shallow copy)
fix(ci): fix test_dedup_pure sys.modules pollution + add ffmpeg step
2026-07-26 12:43:33 +08:00 · 2026-07-26 12:31:22 +08:00 · 2026-07-26 11:07:39 +08:00 · 2026-07-26 10:01:08 +08:00 · 2026-07-26 01:55:14 +00:00 · 2026-07-26 09:49:08 +08:00
324 changed files with 56545 additions and 20049 deletions
@@ -0,0 +1,162 @@
+name: ACR Cleanup
+
+on:
+  schedule:
+    - cron: '0 19 * * *'  # UTC 19:00 = 北京时间凌晨3:00
+  workflow_dispatch:
+    inputs:
+      pr_sha:
+        description: "PR commit SHA（仅清理指定PR镜像，留空则全量清理）"
+        required: false
+        default: ""
+      dry_run:
+        description: "预览模式（dry-run），不实际删除"
+        required: false
+        default: "true"
+  pull_request_target:
+    types: [closed]
+    branches: [develop, main]
+
+concurrency:
+  group: acr-cleanup-${{ gitea.ref }}
+  cancel-in-progress: false
+
+jobs:
+  cleanup:
+    name: ACR Image Cleanup
+    runs-on: ci-l2
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    env:
+      ACR_REGISTRY: xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com
+      ACR_NAMESPACE: xiaoxiakeji
+      ACR_SERVICE: registry.aliyuncs.com:cn-hangzhou:china:cri-fvec8o9q4mmxrkaa
+      GITEA_URL: https://git.xiaoxiajianji.com
+      GITEA_REPO: xiaoxia/xiaoxia-saas
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      # ====== Cron模式：获取staging运行中镜像作为白名单 ======
+      - name: Get staging running images (whitelist)
+        id: protected_images
+        if: gitea.event_name != 'pull_request_target' && !gitea.event.inputs.pr_sha
+        env:
+          STAGING_SSH_KEY: ${{ secrets.PREVIEW_SSH_KEY }}
+        run: |
+          set +e
+          echo "获取staging服务器运行中镜像作为白名单..."
+          mkdir -p ~/.ssh
+          echo "$STAGING_SSH_KEY" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+
+          staging_host="${STAGING_SSH_HOST:-47.98.113.167}"
+          staging_port="${STAGING_SSH_PORT:-22222}"
+
+          ssh-keyscan -p "$staging_port" -H "$staging_host" >> ~/.ssh/known_hosts 2>/dev/null
+
+          # 获取所有运行容器的镜像，提取tag部分
+          IMAGES=$(ssh -p "$staging_port" -i ~/.ssh/id_rsa -o StrictHostKeyChecking=no \
+            "root@$staging_host" "docker ps --format '{{.Image}}' 2>/dev/null" 2>/dev/null | grep -v "^$" | sort -u)
+
+          PROTECTED_TAGS=""
+          if [ -n "$IMAGES" ]; then
+            while IFS= read -r img; do
+              # 从完整镜像名中提取tag（最后一个冒号后）
+              tag=$(echo "$img" | rev | cut -d: -f1 | rev)
+              if [ -n "$tag" ] && [ "$tag" != "latest" ] && [ ${#tag} -gt 5 ]; then
+                if [ -z "$PROTECTED_TAGS" ]; then
+                  PROTECTED_TAGS="$tag"
+                else
+                  PROTECTED_TAGS="$PROTECTED_TAGS,$tag"
+                fi
+              fi
+            done <<< "$IMAGES"
+          fi
+
+          echo "staging运行中镜像tag: ${PROTECTED_TAGS:-（无）}"
+          echo "protected_tags=$PROTECTED_TAGS" >> $GITEA_OUTPUT
+
+      # ====== Docker登录 ======
+      - name: Docker login to ACR
+        env:
+          ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+          ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+        run: |
+          printf '%s' "$ACR_PASSWORD" | docker login "$ACR_REGISTRY" -u "$ACR_USERNAME" --password-stdin
+
+      # ====== 模式1：PR关闭时清理 ======
+      - name: Cleanup PR images (PR closed)
+        if: gitea.event_name == 'pull_request_target'
+        env:
+          ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+          ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          PR_SHA: ${{ gitea.event.pull_request.head.sha }}
+          PR_NUMBER: ${{ gitea.event.pull_request.number }}
+        run: |
+          echo "============================================"
+          echo "  PR #$PR_NUMBER 已关闭，清理对应镜像"
+          echo "  Head SHA: ${PR_SHA::12}"
+          echo "============================================"
+          echo ""
+          python3 scripts/ci/acr_cleanup.py \
+            --pr-sha "$PR_SHA" \
+            --execute
+
+      # ====== 模式2：Cron全量清理 ======
+      - name: Full cleanup (cron / manual)
+        if: gitea.event_name != 'pull_request_target' && !gitea.event.inputs.pr_sha
+        env:
+          ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+          ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          PROTECTED_TAGS: ${{ steps.protected_images.outputs.protected_tags }}
+          DRY_RUN_INPUT: ${{ gitea.event.inputs.dry_run }}
+        run: |
+          echo "============================================"
+          echo "  ACR 全量清理（${{ gitea.event_name }}）"
+          echo "============================================"
+          echo ""
+
+          # 决定是否dry-run
+          DRY_RUN_FLAG=""
+          if [ "$DRY_RUN_INPUT" = "true" ]; then
+            DRY_RUN_FLAG="--dry-run"
+            echo "模式: 预览模式 (dry-run)"
+          else
+            echo "模式: 执行模式"
+          fi
+          echo ""
+
+          python3 scripts/ci/acr_cleanup.py \
+            --keep 20 \
+            --protected-tags "$PROTECTED_TAGS" \
+            $DRY_RUN_FLAG
+
+      # ====== 模式3：手动指定PR SHA清理 ======
+      - name: Cleanup specific PR image (manual)
+        if: gitea.event_name == 'workflow_dispatch' && gitea.event.inputs.pr_sha
+        env:
+          ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+          ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+          PR_SHA: ${{ gitea.event.inputs.pr_sha }}
+          DRY_RUN_INPUT: ${{ gitea.event.inputs.dry_run }}
+        run: |
+          echo "手动清理PR镜像: ${PR_SHA::12}"
+          echo ""
+
+          DRY_RUN_FLAG=""
+          if [ "$DRY_RUN_INPUT" = "true" ]; then
+            DRY_RUN_FLAG="--dry-run"
+          fi
+
+          python3 scripts/ci/acr_cleanup.py \
+            --pr-sha "$PR_SHA" \
+            $DRY_RUN_FLAG
@@ -24,6 +24,17 @@ concurrency:
  group: ci-pipeline-${{ gitea.event_name }}-${{ gitea.ref }}
  # PR事件取消进行中的旧run，push事件不取消（确保完整CI跑完）
  cancel-in-progress: ${{ gitea.event_name == 'pull_request' }}
+env:
+  CI_PG_HOST: host.docker.internal
+  CI_LOCAL_PG_PORT: "5432"
+  CI_PG_USER: postgres
+  CI_PG_PASSWORD: postgres
+  CI_PG_DB: xiaoxia_saas
+  CI_SHARED_PG_PORT: "5433"
+  CI_SHARED_PG_USER: postgres
+  CI_SHARED_PG_PASSWORD: ci_pg_2026!
+  CI_DEFAULT_DB: xiaoxia_saas
+
 jobs:
  check-frontend-only:
    name: Check if frontend-only change
@@ -251,7 +262,7 @@ jobs:
    permissions:
      contents: read
    env:
-      DATABASE_URL: postgresql+psycopg://postgres:postgres@host.docker.internal:5432/xiaoxia_saas
+      DATABASE_URL: postgresql+psycopg://${{ env.CI_PG_USER }}:${{ env.CI_PG_PASSWORD }}@${{ env.CI_PG_HOST }}:${{ env.CI_LOCAL_PG_PORT }}/${{ env.CI_PG_DB }}
      USE_IN_MEMORY_DB: 'false'
      CI_USE_SHARED_PG: 'true'
    steps:
@@ -335,6 +346,7 @@ jobs:
      OSS_ACCESS_KEY_SECRET: placeholder
      OSS_BUCKET_NAME: xiaoxia-autocut
      OSS_ENDPOINT: oss-cn-hangzhou.aliyuncs.com
+      JWT_SECRET_KEY: test-jwt-secret-for-ci-only-2026
    steps:
    - name: Checkout code
      shell: sh
@@ -399,13 +411,14 @@ jobs:
      - validate-type-check
      - validate-migration
    env:
-      DATABASE_URL: postgresql+psycopg://postgres:postgres@host.docker.internal:5432/xiaoxia_saas
+      DATABASE_URL: postgresql+psycopg://${{ env.CI_PG_USER }}:${{ env.CI_PG_PASSWORD }}@${{ env.CI_PG_HOST }}:${{ env.CI_LOCAL_PG_PORT }}/${{ env.CI_PG_DB }}
      USE_IN_MEMORY_DB: 'false'
      CI_USE_SHARED_PG: 'true'
      OSS_ACCESS_KEY_ID: placeholder
      OSS_ACCESS_KEY_SECRET: placeholder
      OSS_BUCKET_NAME: xiaoxia-autocut
      OSS_ENDPOINT: oss-cn-hangzhou.aliyuncs.com
+      JWT_SECRET_KEY: test-jwt-secret-for-ci-only-2026
    steps:
    - name: Checkout code
      shell: sh
@@ -627,65 +640,83 @@ jobs:
          echo "Docker login failed ($i/3), retrying in 5s..."
          sleep 5
        done
-    - name: Pre-build worker base images (fallback if not exist)
+    - name: Pre-build worker base images (3-level cache)
      if: matrix.service == 'worker'
      id: prebuild
-      shell: sh
+      shell: bash
      run: |
        set -eu
-        REGISTRY="git.xiaoxiajianji.com/xiaoxia-saas"
-        BASE_BUILDER="${REGISTRY}/worker-base-builder:latest"
-        BASE_RUNTIME="${REGISTRY}/worker-base-runtime:latest"
-        
-        # 尝试拉取基础镜像
-        echo "检查基础镜像..."
-        if docker pull "$BASE_BUILDER" 2>/dev/null && docker pull "$BASE_RUNTIME" 2>/dev/null; then
-          echo "基础镜像已存在，使用远程镜像"
-          echo "fallback=false" >> $GITHUB_OUTPUT
-        else
-          echo "基础镜像不存在，本地构建（fallback模式）..."
-          
-          # 构建builder基础镜像
-          echo "构建 worker-base-builder..."
-          # 用buildx docker-container驱动构建（兼容DooD模式：普通docker build看不到容器内文件）
-          BUILDER_NAME="ci-pr-builder-${GITHUB_RUN_ID:-local}"
-          if ! docker buildx inspect "$BUILDER_NAME" > /dev/null 2>&1; then
-            docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
-          else
-            docker buildx use "$BUILDER_NAME"
-          fi
-          docker buildx inspect --bootstrap > /dev/null 2>&1
-          
-          # 构建builder基础镜像（带重试，buildx容器偶发不稳定）
-          echo "构建 worker-base-builder..."
-          for attempt in 1 2 3; do
-            if docker buildx build --load -f infra/docker/worker-base-builder.Dockerfile -t "$BASE_BUILDER" .; then
-              echo "worker-base-builder 构建成功"
-              break
-            fi
-            echo "worker-base-builder 构建失败，重试 $attempt/3..."
-            docker buildx rm "$BUILDER_NAME" 2>/dev/null || true
-            docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
-            sleep 3
-          done
-          
-          # 构建runtime基础镜像
-          echo "构建 worker-base-runtime..."
-          for attempt in 1 2 3; do
-            if docker buildx build --load -f infra/docker/worker-base-runtime.Dockerfile -t "$BASE_RUNTIME" .; then
-              echo "worker-base-runtime 构建成功"
-              break
-            fi
-            echo "worker-base-runtime 构建失败，重试 $attempt/3..."
-            docker buildx rm "$BUILDER_NAME" 2>/dev/null || true
-            docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
-            sleep 3
-          done
-          
-          echo "fallback=true" >> $GITHUB_OUTPUT
-          echo "基础镜像本地构建完成"
-        fi
+        GITEA_REGISTRY="git.xiaoxiajianji.com/xiaoxia-saas"
+        ACR_REGISTRY="xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji"
+        GITEA_BUILDER="${GITEA_REGISTRY}/worker-base-builder:latest"
+        GITEA_RUNTIME="${GITEA_REGISTRY}/worker-base-runtime:latest"
+        ACR_BUILDER="${ACR_REGISTRY}/worker-base-builder:latest"
+        ACR_RUNTIME="${ACR_REGISTRY}/worker-base-runtime:latest"

+        # L1: 本地daemon缓存（DooD模式8runner共享宿主机daemon）
+        echo "=== L1 本地缓存 ==="
+        if docker image inspect "$ACR_BUILDER" > /dev/null 2>&1 \
+           && docker image inspect "$ACR_RUNTIME" > /dev/null 2>&1; then
+          echo "本地缓存命中"
+          echo "has_local_base=true" >> $GITHUB_OUTPUT
+          exit 0
+        fi
+        echo "本地无缓存"
+
+        # L2: Gitea registry缓存（内网快）
+        echo "=== L2 Registry拉取 ==="
+        if docker pull "$GITEA_BUILDER" 2>/dev/null && docker pull "$GITEA_RUNTIME" 2>/dev/null; then
+          echo "Registry拉取成功，重tag供Dockerfile使用"
+          docker tag "$GITEA_BUILDER" "$ACR_BUILDER"
+          docker tag "$GITEA_RUNTIME" "$ACR_RUNTIME"
+          echo "has_local_base=true" >> $GITHUB_OUTPUT
+          exit 0
+        fi
+        echo "Registry无缓存，需本地构建"
+
+        # L3: 本地构建
+        echo "=== L3 本地构建 ==="
+        BUILDER_NAME="ci-pr-builder-${GITHUB_RUN_ID:-local}"
+        if ! docker buildx inspect "$BUILDER_NAME" > /dev/null 2>&1; then
+          docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
+        else
+          docker buildx use "$BUILDER_NAME"
+        fi
+        docker buildx inspect --bootstrap > /dev/null 2>&1
+
+        echo "构建 worker-base-builder..."
+        for attempt in 1 2 3; do
+          if docker buildx build --load -f infra/docker/worker-base-builder.Dockerfile -t "$ACR_BUILDER" .; then
+            echo "worker-base-builder 构建成功"
+            break
+          fi
+          echo "worker-base-builder 失败，重试 $attempt/3..."
+          docker buildx rm "$BUILDER_NAME" 2>/dev/null || true
+          docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
+          sleep 3
+        done
+
+        echo "构建 worker-base-runtime..."
+        for attempt in 1 2 3; do
+          if docker buildx build --load -f infra/docker/worker-base-runtime.Dockerfile -t "$ACR_RUNTIME" .; then
+            echo "worker-base-runtime 构建成功"
+            break
+          fi
+          echo "worker-base-runtime 失败，重试 $attempt/3..."
+          docker buildx rm "$BUILDER_NAME" 2>/dev/null || true
+          docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
+          sleep 3
+        done
+
+        # 推送到Gitea registry供后续复用
+        echo "=== 推送缓存到Registry ==="
+        docker tag "$ACR_BUILDER" "$GITEA_BUILDER"
+        docker tag "$ACR_RUNTIME" "$GITEA_RUNTIME"
+        docker push "$GITEA_BUILDER" 2>/dev/null || echo "push builder失败（不影响）"
+        docker push "$GITEA_RUNTIME" 2>/dev/null || echo "push runtime失败（不影响）"
+
+        echo "has_local_base=true" >> $GITHUB_OUTPUT
+        echo "基础镜像构建完成"
    - name: Build PR image (verify only, no push)
      shell: sh
      run: |
@@ -699,15 +730,15 @@ jobs:
          EXTRA_BUILD_ARGS="$EXTRA_BUILD_ARGS NGINX_CONF=infra/docker/nginx-staging.conf"
        fi

-        # Worker fallback模式：基础镜像本地已构建，用普通docker build绕过buildx
-        if [ "${{ matrix.service }}" = "worker" ] && [ "${{ steps.prebuild.outputs.fallback }}" = "true" ]; then
-          echo "Fallback模式：用普通docker build（基础镜像本地已构建）"
+        # Worker有本地base镜像时：用BuildKit直接构建（快，无需起buildx容器）
+        if [ "${{ matrix.service }}" = "worker" ] && [ "${{ steps.prebuild.outputs.has_local_base }}" = "true" ]; then
+          echo "本地base镜像已就绪，BuildKit快速构建"
          BUILD_ARG_STR=""
          for arg in $EXTRA_BUILD_ARGS; do
            BUILD_ARG_STR="$BUILD_ARG_STR --build-arg $arg"
          done
-          docker build -f ${{ matrix.dockerfile }} -t "${IMAGE_TAG}" $BUILD_ARG_STR .
-          echo "Fallback PR Build successful"
+          DOCKER_BUILDKIT=1 docker build -f ${{ matrix.dockerfile }} -t "${IMAGE_TAG}" $BUILD_ARG_STR .
+          echo "快速构建成功"
          exit 0
        fi

@@ -1083,12 +1114,13 @@ jobs:
      shell: sh
      run: bash scripts/ci/step_timer_start.sh
    - name: Run Playwright E2E on staging
-      shell: sh
+      shell: bash
      run: |
        set -eu
        # DooD模式下不能用-v挂载（宿主机路径与CI容器路径不一致）
        # 改用 docker create + docker cp 方式把代码拷进容器
-        CONTAINER_NAME="staging-e2e-$$"
+        CONTAINER_NAME="staging-e2e-${GITHUB_SHA::8}"
+        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 \
@@ -1147,12 +1179,13 @@ jobs:
      shell: sh
      run: bash scripts/ci/step_timer_start.sh
    - name: Run API integration tests on staging
-      shell: sh
+      shell: bash
      run: |
        set -eu
        # DooD模式下不能用-v挂载（宿主机路径与CI容器路径不一致）
        # 改用 docker create + docker cp 方式把代码拷进容器
-        CONTAINER_NAME="staging-api-tests-$$"
+        CONTAINER_NAME="staging-api-tests-${GITHUB_SHA::8}"
+        docker rm -f "$CONTAINER_NAME" 2>/dev/null || true
        docker create --name "$CONTAINER_NAME" \
          -e E2E_BASE_URL=https://staging.xiaoxiajianji.com \
          -e E2E_API_BASE=https://staging-api.xiaoxiajianji.com/api/v1 \
@@ -1197,7 +1230,7 @@ jobs:
    runs-on: runtime-builder
    timeout-minutes: ${{ matrix.timeout }}
    needs:
-    if: startsWith(github.ref, 'refs/tags/v')
+    if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'push' && github.ref_name == 'main')
    strategy:
      fail-fast: false
      matrix:
@@ -1274,10 +1307,16 @@ jobs:
      run: |
        set -eu
        REGISTRY="xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji"
-        IMAGE_TAG="${REGISTRY}/${{ matrix.image_name }}:${GITHUB_REF_NAME}"
+        # 根据ref类型设置镜像标签：tag用版本号，分支用分支名+sha
+        if [[ "$GITHUB_REF" == refs/tags/* ]]; then
+          TAG_NAME="${GITHUB_REF_NAME}"
+        else
+          TAG_NAME="${GITHUB_REF_NAME}-${GITHUB_SHA::8}"
+        fi
+        IMAGE_TAG="${REGISTRY}/${{ matrix.image_name }}:${TAG_NAME}"
        CACHE_REF="${REGISTRY}/${{ matrix.cache_name }}:main"

-        EXTRA_BUILD_ARGS="APP_VERSION=\"${GITHUB_REF_NAME}\""
+        EXTRA_BUILD_ARGS="APP_VERSION=\"${TAG_NAME}\""
        if [ "${{ matrix.service }}" = "web" ]; then
          EXTRA_BUILD_ARGS="$EXTRA_BUILD_ARGS NGINX_CONF=infra/docker/nginx-production.conf"
        fi
@@ -1575,4 +1614,89 @@ jobs:
        [ ${{ job.status }} = "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
+
+  canary-release:
+    name: Canary Release to Production
+    runs-on: runtime-builder
+    timeout-minutes: 120
+    concurrency:
+      group: canary-release-production
+      cancel-in-progress: false
+    if: github.event_name == 'push' && github.ref_name == 'main'
+    needs:
+    - build-production
+    - staging-api-tests
+    steps:
+    - name: Checkout code
+      shell: sh
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: |
+        curl -sH "Authorization: token $GITHUB_TOKEN"           "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}"           | bash
+    - name: Record job start time
+      shell: sh
+      run: bash scripts/ci/step_timer_start.sh
+    - name: Notify canary release start
+      continue-on-error: true
+      shell: sh
+      env:
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+      run: |
+        set +e
+        NOTIFY_MODE=start JOB_NAME="Canary Release" python3 scripts/ci_notify.py
+    - name: Install SSH client
+      shell: sh
+      run: |
+        set -eu
+        apt-get update -qq && apt-get install -y -qq openssh-client curl >/dev/null 2>&1
+        echo "openssh-client installed"
+    - name: Run canary release
+      shell: bash
+      env:
+        PRODUCTION_SSH_HOST: ${{ secrets.PRODUCTION_SSH_HOST }}
+        PRODUCTION_SSH_USER: ${{ secrets.PRODUCTION_SSH_USER }}
+        PRODUCTION_SSH_PORT: ${{ secrets.PRODUCTION_SSH_PORT }}
+        PRODUCTION_SSH_KEY: ${{ secrets.PRODUCTION_SSH_KEY }}
+        ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+        ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+      run: |
+        set -eu
+        IMAGE_TAG="main-${GITHUB_SHA::8}"
+        export IMAGE_TAG
+        echo "Canary release version: $IMAGE_TAG"
+        bash scripts/ci/canary_release.sh
+    - name: Job duration summary
+      if: always()
+      shell: sh
+      run: bash scripts/ci/step_timer_end.sh
+    - name: Notify on success
+      continue-on-error: true
+      if: success()
+      shell: sh
+      env:
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+      run: |
+        set +e
+        NOTIFY_MODE=success JOB_NAME="Canary Release" python3 scripts/ci_notify.py
+    - name: Notify on failure
+      continue-on-error: true
+      if: failure()
+      shell: sh
+      env:
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+      run: |
+        set +e
+        NOTIFY_MODE=failure JOB_NAME="Canary Release" python3 scripts/ci_notify.py
+    - name: Report CI trace
+      if: always()
+      shell: sh
+      env:
+        AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+      run: |
+        STATUS="ok"
+        [ ${{ job.status }} = "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
@@ -93,44 +93,31 @@ jobs:
      shell: sh
      run: |
        set -eu
-        NPM_CACHE_VOLUME="xiaoxia-npm-cache"
-        if ! docker volume inspect "$NPM_CACHE_VOLUME" >/dev/null 2>&1; then
-          docker volume create "$NPM_CACHE_VOLUME" >/dev/null
-          echo "Created npm cache volume: $NPM_CACHE_VOLUME"
-        fi
+        cd apps/web

-        docker run --rm \
-          -v "$PWD:/workspace" \
-          -v "$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules" \
-          -w /workspace/apps/web \
-          -e VITE_API_URL=https://staging-api.xiaoxiajianji.com \
-          docker.m.daocloud.io/library/node:20 \
-          sh -lc '
-            PACKAGE_LOCK_HASH=$(md5sum package-lock.json 2>/dev/null | cut -d" " -f1)
-            CACHE_HASH_FILE="node_modules/.package-lock-hash"
-            CACHE_VALID=false
-            if [ -f "$CACHE_HASH_FILE" ] && [ "$(cat "$CACHE_HASH_FILE")" = "$PACKAGE_LOCK_HASH" ] && [ -x "node_modules/.bin/vite" ] && [ -x "node_modules/.bin/tsc" ]; then
-              CACHE_VALID=true
-              echo "Cache hit: dependencies valid, skipping npm ci"
-            fi
-            if [ "$CACHE_VALID" = "false" ]; then
-              echo "Cache miss or invalid: running npm ci..."
-              if ! npm ci --include=dev; then
-                echo "npm ci failed, cleaning node_modules and retrying..."
-                rm -rf node_modules
-                mkdir -p node_modules
-                npm ci --include=dev
-              fi
-              echo "$PACKAGE_LOCK_HASH" > "$CACHE_HASH_FILE"
-              echo "Dependencies installed, cache updated"
-            fi
-            echo "Running TypeScript check..."
-            npx --no-install tsc
-            echo "Running Vite build..."
-            npx --no-install vite build
-            echo "Build completed successfully"
-            ls -la dist/
-          '
+        # 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
+          echo "npm ci failed, retry $i/3..."
+          [ $i -eq 3 ] && exit 1
+          rm -rf node_modules
+          sleep 5
+        done
+
+        # TypeScript check
+        echo "=== TypeScript check ==="
+        npx --no-install tsc --noEmit
+
+        # Vite build
+        echo "=== Vite build ==="
+        export VITE_API_URL=https://staging-api.xiaoxiajianji.com
+        npx --no-install vite build
+
+        echo "=== Build completed ==="
+        ls -la dist/

    - name: Install SSH client and rsync
      shell: sh
@@ -0,0 +1,64 @@
+"""#642 - 生成任务新增 bgm_config 字段
+
+Revision ID: 052_generation_task_bgm_config
+Revises: 051_generation_task_resolution
+Create Date: 2026-07-25
+
+Changes:
+1. generation_tasks 表新增 bgm_config 字段（JSON类型），存储用户自定义BGM配置
+2. 为空时使用默认空字典
+
+背景：
+#642 一键生成支持自定义BGM 功能在 SQLAlchemy 模型中加了 bgm_config 字段，
+但遗漏了 alembic migration，导致 staging 环境数据库没有该列，
+创建生成任务时直接 500。
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "052_generation_task_bgm_config"
+down_revision = "051_generation_task_resolution"
+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 = 'bgm_config'"
+            )
+        )
+        if result.scalar() is not None:
+            return
+
+    op.add_column(
+        "generation_tasks",
+        sa.Column(
+            "bgm_config",
+            sa.JSON,
+            nullable=False,
+            server_default=sa.text("'{}'::json"),
+        ),
+    )
+
+
+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 = 'bgm_config'"
+            )
+        )
+        if result.scalar() is None:
+            return
+
+    op.drop_column("generation_tasks", "bgm_config")
@@ -1,4 +1,4 @@
-from datetime import datetime
+from datetime import datetime, timezone

 import psycopg2
 import redis
@@ -13,7 +13,7 @@ router = APIRouter(tags=["Health"])
 async def health_check():
    return {
        "status": "healthy",
-        "timestamp": datetime.utcnow().isoformat(),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
        "version": settings.APP_VERSION,
    }

@@ -33,7 +33,7 @@ async def startup_check():
    all_ready = all(check["status"] == "healthy" for check in checks.values())
    response = {
        "status": "started" if all_ready else "starting",
-        "timestamp": datetime.utcnow().isoformat(),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
        "checks": checks,
    }
    if not all_ready:
@@ -0,0 +1,65 @@
+"""模板编辑器 API 路由包.
+
+将原来 2560 行的 templates_editor.py 巨无霸拆分为 12 个模块：
+- schemas.py:        所有 Pydantic model
+- dependencies.py:   依赖注入
+- _utils.py:         工具函数
+- _fallback.py:      自动兜底逻辑
+- draft.py:          草稿管理（详情/更新/发布/版本/回滚）
+- clips.py:          片段管理（CRUD/分割/合并/重排/批量删除/从素材创建）
+- adjustments.py:    片段调整（速度/音量/裁剪/批量调速）
+- bgm.py:            BGM 管理
+- effects.py:        转场 + 滤镜
+- export.py:         导出配置
+- cover.py:          封面管理 + AI 生成封面
+- subtitles.py:      字幕管理
+- ai_features.py:    AI 推荐
+- generation.py:     生成（触发/进度/记录）
+- timeline.py:       时间线
+
+挂载路径: /api/v1/templates/{template_id}/editor/
+"""
+
+from __future__ import annotations
+
+# 向后兼容：测试和其他模块可能直接从 templates_editor 导入这些符号
+from app.auth import get_current_user  # noqa: F401
+from app.dependencies import get_db_session  # noqa: F401
+from fastapi import APIRouter
+
+from .adjustments import router as adjustments_router
+from .ai_features import router as ai_features_router
+from .bgm import router as bgm_router
+from .clips import router as clips_router
+from .cover import router as cover_router
+from .dependencies import get_draft_plan_id, get_editor_services  # noqa: F401
+from .draft import router as draft_router
+from .effects import router as effects_router
+from .export import router as export_router
+from .generation import router as generation_router
+from .subtitles import router as subtitles_router
+from .timeline import router as timeline_router
+
+# 主 router，所有子路由都合并到这里
+router = APIRouter(tags=["Template Editor"])
+
+# 合并所有子模块的路由（不用 include_router 是因为子路由有空路径 ""）
+_sub_routers = [
+    draft_router,
+    clips_router,
+    adjustments_router,
+    bgm_router,
+    effects_router,
+    export_router,
+    cover_router,
+    subtitles_router,
+    ai_features_router,
+    generation_router,
+    timeline_router,
+]
+
+for sub in _sub_routers:
+    for route in sub.routes:
+        router.routes.append(route)
+
+__all__ = ["router"]
@@ -0,0 +1,163 @@
+"""模板编辑器自动兜底逻辑.
+
+generate_editor_draft 触发生成前的自动修复流程：
+1. draft → editing 状态迁移
+2. 无片段时从模板复制片段配置
+3. 为无素材片段分配指定素材
+4. 项目有素材库时自动选素材
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+from typing import Any
+
+from app.services.edit_plan_service import EditPlanService
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.template_clip_config_repository import (
+    SQLAlchemyTemplateClipConfigRepository,
+)
+from packages.adapters.sqlalchemy_impl.template_repository import (
+    SQLAlchemyTemplateRepository,
+)
+from packages.domain.edit_plan import EditPlanStatus
+
+logger = logging.getLogger(__name__)
+
+
+def _auto_fallback_draft_to_editing(
+    svc: EditPlanService, plan_id: str, plan_check
+) -> None:
+    """自动兜底 1: draft → editing"""
+    if plan_check.status == EditPlanStatus.DRAFT:
+        logger.info("模板编辑器自动兜底: plan=%s draft→editing", plan_id)
+        svc.transition_status(plan_id, EditPlanStatus.EDITING)
+
+
+def _auto_fallback_copy_template_clips(
+    svc: EditPlanService, plan_id: str, plan_check, db: Session
+) -> None:
+    """自动兜底 2: 无片段 + 有 template_id → 从模板复制片段配置"""
+    existing_clips = svc.count_clips(plan_id)
+    if existing_clips == 0 and plan_check.template_id:
+        logger.info(
+            "模板编辑器自动兜底: plan=%s 无片段，从模板 %s 复制片段配置",
+            plan_id,
+            plan_check.template_id,
+        )
+        clip_config_repo = SQLAlchemyTemplateClipConfigRepository(db)
+        configs = clip_config_repo.list_by_template(plan_check.template_id)
+        if configs:
+            for cfg in configs:
+                svc.create_clip(
+                    plan_id=plan_id,
+                    clip_type=cfg.clip_type.value
+                    if hasattr(cfg.clip_type, "value")
+                    else cfg.clip_type,
+                    order=cfg.order,
+                    template_clip_config_id=cfg.id,
+                    duration=cfg.default_duration,
+                    transition_effect=cfg.transition_effect.value
+                    if hasattr(cfg.transition_effect, "value")
+                    else cfg.transition_effect,
+                )
+            logger.info(
+                "模板编辑器自动兜底: plan=%s 从 template_clip_configs 复制了 %d 个片段",
+                plan_id,
+                len(configs),
+            )
+        else:
+            tpl_repo = SQLAlchemyTemplateRepository(db)
+            segments = tpl_repo.list_segments(plan_check.template_id)
+            for seg in segments:
+                avg_duration = (seg.duration_min + seg.duration_max) / 2
+                svc.create_clip(
+                    plan_id=plan_id,
+                    clip_type="main",
+                    order=seg.segment_order,
+                    duration=avg_duration,
+                    config={
+                        "material_type": seg.material_type or "",
+                        "template_segment_id": seg.id,
+                    },
+                )
+            logger.info(
+                "模板编辑器自动兜底: plan=%s 从旧模板 segments 复制了 %d 个片段",
+                plan_id,
+                len(segments),
+            )
+
+
+def _auto_fallback_assign_assets(
+    svc: EditPlanService, plan_id: str, plan_check
+) -> list:
+    """自动兜底 3: 为没有素材的片段分配素材。返回剩余无素材片段列表。"""
+    all_clips = svc.list_clips(plan_id)
+    clips_without_asset = [c for c in all_clips if not c.asset_id]
+    config_asset_ids = (plan_check.config or {}).get("asset_ids", [])
+
+    if clips_without_asset and config_asset_ids:
+        logger.info(
+            "模板编辑器自动兜底3: plan=%s 为 %d 个无素材片段分配 %d 个指定素材",
+            plan_id,
+            len(clips_without_asset),
+            len(config_asset_ids),
+        )
+        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 = []
+
+    return clips_without_asset
+
+
+def _auto_fallback_auto_material_mode(
+    svc: EditPlanService,
+    plan_id: str,
+    plan_check,
+    clips_without_asset: list,
+    asset_library_repo: Any,
+    asset_repo: Any,
+) -> None:
+    """自动兜底 4: 项目有视频素材库时自动选素材"""
+    if not clips_without_asset:
+        return
+    if not plan_check.project_id:
+        return
+
+    logger.info(
+        "模板编辑器自动兜底4: plan=%s 自动选素材分配给 %d 个无素材片段",
+        plan_id,
+        len(clips_without_asset),
+    )
+    libs = asset_library_repo.find_by_project(plan_check.project_id)
+    video_lib = None
+    for lib in libs:
+        lib_kind = lib.kind.value if hasattr(lib.kind, "value") else lib.kind
+        if lib_kind == "video":
+            video_lib = lib
+            break
+
+    if video_lib:
+        assets = asset_repo.find_by_library(video_lib.id)
+        ready_videos = [
+            a
+            for a in assets
+            if (a.status.value if hasattr(a.status, "value") else a.status) == "ready"
+            and a.mime_type
+            and a.mime_type.startswith("video")
+        ]
+        if ready_videos:
+            random.shuffle(ready_videos)
+            for i, clip in enumerate(clips_without_asset):
+                asset = ready_videos[i % len(ready_videos)]
+                svc.assign_asset(clip.id, asset.id)
+            logger.info(
+                "模板编辑器自动兜底4: plan=%s 从素材库 %s 分配了 %d 个素材",
+                plan_id,
+                video_lib.name,
+                len(ready_videos),
+            )
@@ -0,0 +1,109 @@
+"""模板编辑器内部工具函数.
+
+纯函数，不依赖请求上下文。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .schemas import ClipAdjustResponse
+
+# 时间线场景颜色映射
+_CLIP_TYPE_COLORS = {
+    "intro": "#6366f1",
+    "title": "#6366f1",
+    "product": "#818cf8",
+    "showcase": "#10b981",
+    "scene": "#10b981",
+    "subtitle": "#f59e0b",
+    "text": "#f59e0b",
+    "cta": "#ef4444",
+    "outro": "#ef4444",
+    "voiceover": "#8b5cf6",
+    "transition": "#64748b",
+}
+_DEFAULT_COLOR = "#6366f1"
+
+
+def _format_time(seconds: float) -> str:
+    """秒数格式化为 m:ss"""
+    m = int(seconds) // 60
+    s = int(seconds) % 60
+    return f"{m}:{s:02d}"
+
+
+def _clip_type_to_scene_label(clip_type: str, text_content: str) -> str:
+    """片段类型转时间线场景标签"""
+    type_labels = {
+        "intro": "开场",
+        "title": "标题",
+        "product": "产品展示",
+        "showcase": "场景展示",
+        "scene": "场景",
+        "subtitle": "字幕",
+        "text": "文字",
+        "cta": "结尾 CTA",
+        "outro": "结尾",
+        "voiceover": "配音",
+        "transition": "转场",
+    }
+    label = type_labels.get(clip_type, clip_type or "片段")
+    if text_content:
+        short = text_content[:20].strip()
+        if short:
+            return f"{label} - {short}"
+    return label
+
+
+# ── 片段调整相关工具 ────────────────────────────────────────────────────────
+
+
+def _get_clip_config(clip) -> dict:
+    """安全获取 clip.config"""
+    config = getattr(clip, "config", {}) or {}
+    if not isinstance(config, dict):
+        config = {}
+    return config
+
+
+def _get_adjust_volume(clip) -> float:
+    """获取片段音量"""
+    config = _get_clip_config(clip)
+    return float(config.get("volume", 1.0))
+
+
+def _get_adjust_trim(clip) -> tuple[float, float]:
+    """获取片段裁剪起止"""
+    config = _get_clip_config(clip)
+    trim_start = float(config.get("trim_start", 0.0))
+    trim_end = float(config.get("trim_end", 0.0))
+    return trim_start, trim_end
+
+
+def _build_adjust_response(clip) -> ClipAdjustResponse:
+    """构造片段调整响应"""
+    trim_start, trim_end = _get_adjust_trim(clip)
+    return ClipAdjustResponse(
+        clip_id=clip.id,
+        speed=clip.playback_speed,
+        volume=_get_adjust_volume(clip),
+        trim_start=trim_start,
+        trim_end=trim_end,
+        duration=clip.duration,
+    )
+
+
+def _validate_trim(trim_start: float, trim_end: float, total_duration: float) -> None:
+    """校验裁剪时长合法性"""
+    if trim_start + trim_end >= total_duration:
+        raise ValueError(
+            f"裁剪总时长（{trim_start + trim_end:.2f}s）不能大于等于片段总时长（{total_duration:.2f}s）"
+        )
+
+
+def _clip_value(value: Any) -> str:
+    """获取枚举/字符串值的统一方法"""
+    if hasattr(value, "value"):
+        return value.value
+    return str(value)
@@ -0,0 +1,167 @@
+"""片段调整路由.
+
+端点：
+- PUT /clips/{clip_id}/speed         调速
+- PUT /clips/{clip_id}/volume        调音量
+- PUT /clips/{clip_id}/trim          裁剪
+- PUT /clips/{clip_id}/adjustments   统一调整
+- POST /clips/batch-speed            批量调速
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException
+
+from ._utils import _build_adjust_response, _get_adjust_trim, _get_clip_config, _validate_trim
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import (
+    BatchSpeedRequest,
+    BatchSpeedResponse,
+    ClipAdjustmentsRequest,
+    ClipAdjustResponse,
+    SpeedAdjustRequest,
+    TrimAdjustRequest,
+    VolumeAdjustRequest,
+)
+
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.put("/clips/{clip_id}/speed", response_model=ClipAdjustResponse)
+def adjust_editor_clip_speed(
+    template_id: str,
+    clip_id: str,
+    body: SpeedAdjustRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipAdjustResponse:
+    """调整片段播放速度"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    updated = plan_svc.update_clip(clip_id, playback_speed=body.speed)
+    return _build_adjust_response(updated)
+
+
+@router.put("/clips/{clip_id}/volume", response_model=ClipAdjustResponse)
+def adjust_editor_clip_volume(
+    template_id: str,
+    clip_id: str,
+    body: VolumeAdjustRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipAdjustResponse:
+    """调整片段音量"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    config = dict(_get_clip_config(clip))
+    config["volume"] = body.volume
+    updated = plan_svc.update_clip(clip_id, config=config)
+    return _build_adjust_response(updated)
+
+
+@router.put("/clips/{clip_id}/trim", response_model=ClipAdjustResponse)
+def adjust_editor_clip_trim(
+    template_id: str,
+    clip_id: str,
+    body: TrimAdjustRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipAdjustResponse:
+    """裁剪片段（trim in/out）"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    try:
+        _validate_trim(body.trim_start, body.trim_end, clip.duration)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+    config = dict(_get_clip_config(clip))
+    config["trim_start"] = body.trim_start
+    config["trim_end"] = body.trim_end
+    updated = plan_svc.update_clip(clip_id, config=config)
+    return _build_adjust_response(updated)
+
+
+@router.put("/clips/{clip_id}/adjustments", response_model=ClipAdjustResponse)
+def adjust_editor_clip_all(
+    template_id: str,
+    clip_id: str,
+    body: ClipAdjustmentsRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipAdjustResponse:
+    """统一调整片段的 speed / volume / trim"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    update_kwargs: dict[str, Any] = {}
+    config_updates: dict[str, Any] = {}
+
+    if body.speed is not None:
+        update_kwargs["playback_speed"] = body.speed
+    if body.volume is not None:
+        config_updates["volume"] = body.volume
+    if body.trim_start is not None:
+        config_updates["trim_start"] = body.trim_start
+    if body.trim_end is not None:
+        config_updates["trim_end"] = body.trim_end
+
+    current_trim_start, current_trim_end = _get_adjust_trim(clip)
+    new_trim_start = body.trim_start if body.trim_start is not None else current_trim_start
+    new_trim_end = body.trim_end if body.trim_end is not None else current_trim_end
+
+    if body.trim_start is not None or body.trim_end is not None:
+        try:
+            _validate_trim(new_trim_start, new_trim_end, clip.duration)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e)) from e
+
+    if config_updates:
+        config = dict(_get_clip_config(clip))
+        config.update(config_updates)
+        update_kwargs["config"] = config
+
+    if not update_kwargs:
+        return _build_adjust_response(clip)
+
+    updated = plan_svc.update_clip(clip_id, **update_kwargs)
+    return _build_adjust_response(updated)
+
+
+@router.post("/clips/batch-speed", response_model=BatchSpeedResponse)
+def batch_adjust_editor_speed(
+    template_id: str,
+    body: BatchSpeedRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> BatchSpeedResponse:
+    """批量调整草稿内所有片段的播放速度"""
+    _, plan_svc = services
+    clips = plan_svc.list_clips(plan_id, limit=500, skip=0)
+    count = 0
+    for clip in clips:
+        plan_svc.update_clip(clip.id, playback_speed=body.speed)
+        count += 1
+
+    return BatchSpeedResponse(updated_count=count, plan_id=plan_id)
@@ -0,0 +1,121 @@
+"""AI 功能路由.
+
+端点：
+- POST /ai-recommend       AI 推荐片段方案
+"""
+
+from __future__ import annotations
+
+import logging
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from packages.domain.config_schemas import normalize_plan_config
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import AIRecommendRequest, AIRecommendResponse
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.post("/ai-recommend", response_model=AIRecommendResponse)
+def editor_ai_recommend(
+    template_id: str,
+    body: AIRecommendRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> AIRecommendResponse:
+    """AI 推荐片段方案"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    plan_status = plan.status.value if hasattr(plan.status, "value") else plan.status
+    if plan_status not in ("draft", "editing"):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="当前草稿状态不支持AI推荐，请先编辑后再试",
+        )
+
+    from packages.shared.ai_service import run_ai_recommend
+
+    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,
+    )
+
+    try:
+        plan_svc.delete_all_clips(plan_id)
+
+        for clip_data in result["clips"]:
+            plan_svc.create_clip(
+                plan_id=plan_id,
+                clip_type=clip_data["clip_type"],
+                order=clip_data["order"],
+                text_content=clip_data.get("text_content", ""),
+                duration=clip_data["duration"],
+                transition_effect=clip_data.get("transition_effect", "cut"),
+                asset_id=clip_data.get("asset_id", ""),
+                start_time=clip_data.get("start_time", 0.0),
+                config=clip_data.get("config", {}),
+            )
+
+        normalized_config = normalize_plan_config(result.get("config", {}))
+        plan_svc.update_plan(
+            plan_id,
+            config=normalized_config,
+            total_duration=result["total_duration"],
+        )
+    except Exception as _e:
+        logger.exception(
+            "模板编辑器AI推荐写入失败: template_id=%s plan_id=%s",
+            template_id,
+            plan_id,
+        )
+        try:
+            db.rollback()
+        except Exception:
+            pass
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="AI推荐结果保存失败，请稍后重试",
+        ) from _e
+
+    logger.info(
+        "模板编辑器AI推荐: template_id=%s plan_id=%s clips=%d duration=%.1f by user=%s",
+        template_id,
+        plan_id,
+        len(result["clips"]),
+        result["total_duration"],
+        current_user.user.id,
+    )
+
+    return AIRecommendResponse(
+        plan_id=plan_id,
+        clips=[
+            {
+                "clip_type": c["clip_type"],
+                "order": c["order"],
+                "text_content": c.get("text_content", ""),
+                "duration": c["duration"],
+                "transition_effect": c.get("transition_effect", "cut"),
+                "asset_id": c.get("asset_id", ""),
+                "start_time": c.get("start_time", 0.0),
+                "config": c.get("config", {}),
+            }
+            for c in result["clips"]
+        ],
+        config=normalized_config,
+        total_duration=result["total_duration"],
+        confidence=result["confidence"],
+    )
@@ -0,0 +1,133 @@
+"""BGM 管理路由.
+
+端点：
+- GET  /bgm              获取 BGM 配置
+- PUT  /bgm              更新 BGM 配置
+- GET  /bgm/presets      预设 BGM 列表
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import BGMConfigUpdateRequest
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.get("/bgm", response_model=dict[str, Any])
+def get_editor_bgm(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """获取草稿的 BGM 配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+    config = plan.config or {}
+    return {
+        "plan_id": plan.id,
+        "bgm": config.get("bgm", {}),
+    }
+
+
+@router.put("/bgm", response_model=dict[str, Any])
+def update_editor_bgm(
+    template_id: str,
+    body: BGMConfigUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+):
+    """更新草稿的 BGM 配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    config = dict(plan.config) if plan.config else {}
+    current_bgm = dict(config.get("bgm", {}))
+    update_data = body.model_dump(exclude_none=True)
+    current_bgm.update(update_data)
+
+    if current_bgm.get("enabled"):
+        has_source = any(
+            current_bgm.get(key)
+            for key in ("asset_id", "preset_id", "audio_url")
+            if current_bgm.get(key)
+        )
+        if not has_source:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="启用 BGM 时需要指定素材来源（asset_id / preset_id / audio_url）",
+            )
+
+    config["bgm"] = current_bgm
+    updated_plan = plan_svc.update_plan_config(plan_id, config)
+
+    logger.info(
+        "模板编辑器更新BGM: template_id=%s plan_id=%s enabled=%s by user=%s",
+        template_id,
+        plan_id,
+        current_bgm.get("enabled", False),
+        current_user.user.id,
+    )
+
+    return {
+        "plan_id": updated_plan.id,
+        "bgm": current_bgm,
+    }
+
+
+@router.get("/bgm/presets", response_model=dict[str, Any])
+def list_editor_bgm_presets(
+    style: str | None = Query(default=None, description="按风格筛选"),
+    keyword: str | None = Query(default=None, description="关键词搜索"),
+    skip: int = Query(default=0, ge=0, description="分页偏移"),
+    limit: int = Query(default=50, ge=1, le=200, description="每页数量"),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """获取预设 BGM 列表"""
+    from packages.domain.preset_bgm import (
+        BGM_STYLES,
+        PRESET_BGM_LIBRARY,
+        list_preset_bgm_by_style,
+        search_preset_bgm,
+    )
+
+    bgm_list = PRESET_BGM_LIBRARY
+    if keyword:
+        bgm_list = search_preset_bgm(keyword)
+    elif style:
+        bgm_list = list_preset_bgm_by_style(style)
+
+    total = len(bgm_list)
+    paged = bgm_list[skip : skip + limit]
+
+    return {
+        "total": total,
+        "skip": skip,
+        "limit": limit,
+        "styles": BGM_STYLES,
+        "items": [
+            {
+                "id": bgm.id,
+                "name": bgm.name,
+                "style": bgm.style,
+                "style_label": BGM_STYLES.get(bgm.style, bgm.style),
+                "duration": bgm.duration,
+                "artist": bgm.artist,
+                "description": bgm.description,
+                "tags": bgm.tags,
+                "audio_url": bgm.audio_url,
+            }
+            for bgm in paged
+        ],
+    }
@@ -0,0 +1,318 @@
+"""片段管理路由.
+
+端点：
+- GET    /clips                    片段列表
+- POST   /clips                    创建片段
+- GET    /clips/{clip_id}          片段详情
+- PUT    /clips/{clip_id}          更新片段
+- DELETE /clips/{clip_id}          删除片段
+- POST   /clips/{clip_id}/split    分割片段
+- POST   /clips/merge              合并片段
+- POST   /clips/reorder            重排片段
+- POST   /clips/batch-delete       批量删除
+- POST   /clips/from-assets        从素材创建片段
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import (
+    ClipBatchDeleteRequest,
+    ClipBatchDeleteResponse,
+    ClipReorderRequest,
+    ClipReorderResponse,
+    ClipsFromAssetsRequest,
+    ClipsFromAssetsResponse,
+    EditorClipCreateRequest,
+    EditorClipListResponse,
+    EditorClipResponse,
+    EditorClipUpdateRequest,
+    MergeClipsRequest,
+    SplitClipRequest,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["Template Editor"])
+
+
+def _clip_to_response(clip) -> EditorClipResponse:
+    """统一构造片段响应"""
+    return EditorClipResponse(
+        id=clip.id,
+        plan_id=clip.plan_id,
+        clip_type=clip.clip_type.value
+        if hasattr(clip.clip_type, "value")
+        else str(clip.clip_type),
+        order=clip.order,
+        duration=clip.duration,
+        text_content=clip.text_content or "",
+        transition_effect=clip.transition_effect.value
+        if hasattr(clip.transition_effect, "value")
+        else str(clip.transition_effect),
+        playback_speed=clip.playback_speed or 1.0,
+        config=clip.config or {},
+    )
+
+
+@router.get("/clips", response_model=EditorClipListResponse)
+def list_draft_clips(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    skip: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=500),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """获取草稿的片段列表"""
+    _, plan_svc = services
+    clips = plan_svc.list_clips(plan_id, skip=skip, limit=limit)
+    total = plan_svc.count_clips(plan_id)
+    return EditorClipListResponse(
+        items=[_clip_to_response(c) for c in clips],
+        total=total,
+    )
+
+
+@router.post("/clips", response_model=EditorClipResponse, status_code=status.HTTP_201_CREATED)
+def create_draft_clip(
+    template_id: str,
+    req: EditorClipCreateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """在草稿中创建新片段"""
+    _, plan_svc = services
+    try:
+        clip = plan_svc.create_clip(
+            plan_id,
+            clip_type=req.clip_type,
+            order=req.order,
+            duration=req.duration,
+            text_content=req.text_content,
+            transition_effect=req.transition_effect,
+            config=req.config,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return _clip_to_response(clip)
+
+
+@router.put("/clips/{clip_id}", response_model=EditorClipResponse)
+def update_draft_clip(
+    template_id: str,
+    clip_id: str,
+    req: EditorClipUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """更新草稿中的片段"""
+    _, plan_svc = services
+    try:
+        clip = plan_svc.update_clip(
+            clip_id,
+            order=req.order,
+            duration=req.duration,
+            text_content=req.text_content,
+            transition_effect=req.transition_effect,
+            playback_speed=req.playback_speed,
+            config=req.config,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return _clip_to_response(clip)
+
+
+@router.delete("/clips/{clip_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_draft_clip(
+    template_id: str,
+    clip_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """删除草稿中的片段"""
+    _, plan_svc = services
+    success = plan_svc.delete_clip(clip_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="片段不存在")
+    return None
+
+
+@router.get("/clips/{clip_id}", response_model=EditorClipResponse)
+def get_draft_clip_detail(
+    template_id: str,
+    clip_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """获取草稿中的片段详情"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if clip is None:
+        raise HTTPException(status_code=404, detail="片段不存在")
+    if clip.plan_id != plan_id:
+        raise HTTPException(status_code=404, detail="片段不存在")
+    return _clip_to_response(clip)
+
+
+@router.post("/clips/{clip_id}/split", response_model=dict[str, Any], status_code=status.HTTP_200_OK)
+def split_draft_clip(
+    template_id: str,
+    clip_id: str,
+    body: SplitClipRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """将一个片段从指定时间点分割为两个片段"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if clip is None or clip.plan_id != plan_id:
+        raise HTTPException(status_code=404, detail="片段不存在")
+    try:
+        result = plan_svc.split_clip(clip_id, body.split_time)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)
+        ) from exc
+    left = result["left_clip"]
+    right = result["right_clip"]
+    return {
+        "left_clip": {
+            "id": left.id,
+            "plan_id": left.plan_id,
+            "clip_type": left.clip_type,
+            "order": left.order,
+            "duration": left.duration,
+            "start_time": left.start_time,
+        },
+        "right_clip": {
+            "id": right.id,
+            "plan_id": right.plan_id,
+            "clip_type": right.clip_type,
+            "order": right.order,
+            "duration": right.duration,
+            "start_time": right.start_time,
+        },
+    }
+
+
+@router.post("/clips/merge", response_model=dict[str, Any], status_code=status.HTTP_200_OK)
+def merge_draft_clips(
+    template_id: str,
+    body: MergeClipsRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """将多个连续的同类型片段合并为一个片段"""
+    _, plan_svc = services
+    for cid in body.clip_ids:
+        clip = plan_svc.get_clip(cid)
+        if clip is None or clip.plan_id != plan_id:
+            raise HTTPException(status_code=404, detail=f"片段不存在: {cid}")
+    try:
+        merged = plan_svc.merge_clips(body.clip_ids)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)
+        ) from exc
+    return {
+        "id": merged.id,
+        "plan_id": merged.plan_id,
+        "clip_type": merged.clip_type,
+        "order": merged.order,
+        "duration": merged.duration,
+        "text_content": merged.text_content,
+    }
+
+
+@router.post("/clips/reorder", response_model=ClipReorderResponse)
+def reorder_editor_clips(
+    template_id: str,
+    body: ClipReorderRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipReorderResponse:
+    """批量重排片段顺序"""
+    _, plan_svc = services
+    count = 0
+    for item in body.items:
+        try:
+            plan_svc.update_clip(item.clip_id, order=item.new_order)
+            count += 1
+        except ValueError:
+            pass
+
+    return ClipReorderResponse(updated_count=count, plan_id=plan_id)
+
+
+@router.post("/clips/batch-delete", response_model=ClipBatchDeleteResponse)
+def batch_delete_editor_clips(
+    template_id: str,
+    body: ClipBatchDeleteRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipBatchDeleteResponse:
+    """批量删除片段"""
+    _, plan_svc = services
+    deleted = 0
+    for clip_id in body.clip_ids:
+        if plan_svc.delete_clip(clip_id):
+            deleted += 1
+
+    return ClipBatchDeleteResponse(deleted_count=deleted, plan_id=plan_id)
+
+
+@router.post("/clips/from-assets", response_model=ClipsFromAssetsResponse)
+def create_clips_from_assets_editor(
+    template_id: str,
+    body: ClipsFromAssetsRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> ClipsFromAssetsResponse:
+    """从素材批量创建片段"""
+    _, plan_svc = services
+    clips = []
+    for i, asset_id in enumerate(body.asset_ids):
+        try:
+            clip = plan_svc.create_clip(
+                plan_id,
+                clip_type="main",
+                order=body.start_order + i if hasattr(body, "start_order") else i,
+                duration=5.0,
+                asset_id=asset_id,
+            )
+            clips.append(clip)
+        except ValueError:
+            pass
+
+    logger.info(
+        "模板编辑器从素材创建片段: template_id=%s plan_id=%s count=%d by user=%s",
+        template_id,
+        plan_id,
+        len(clips),
+        current_user.user.id,
+    )
+
+    return ClipsFromAssetsResponse(
+        created_count=len(clips),
+        plan_id=plan_id,
+        clip_ids=[c.id for c in clips],
+    )
@@ -0,0 +1,209 @@
+"""封面管理路由.
+
+端点：
+- GET  /cover              封面配置
+- PUT  /cover              更新封面
+- POST /cover/extract      抽帧生成封面
+- POST /cover/smart        智能选帧
+- POST /generate-cover     AI 生成封面
+"""
+
+from __future__ import annotations
+
+import logging
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException
+
+from packages.domain.config_schemas import normalize_plan_config
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import (
+    CoverConfigResponse,
+    CoverExtractRequest,
+    CoverGenerateResponse,
+    CoverSmartRequest,
+    CoverUpdateRequest,
+    GenerateCoverRequest,
+    GenerateCoverResponse,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.get("/cover", response_model=CoverConfigResponse)
+def get_editor_cover(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> CoverConfigResponse:
+    """获取草稿封面配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+    config = plan.config or {}
+    cover_config = config.get("cover", {})
+
+    return CoverConfigResponse(
+        type=cover_config.get("cover_type", "auto"),
+        image_url=cover_config.get("cover_image_url", ""),
+        frame_time=cover_config.get("frame_time", 0.0),
+    )
+
+
+@router.put("/cover", response_model=CoverConfigResponse)
+def update_editor_cover(
+    template_id: str,
+    body: CoverUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> CoverConfigResponse:
+    """更新草稿封面配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    config = dict(plan.config) if plan.config else {}
+    current_cover = dict(config.get("cover", {}))
+    update_data = body.model_dump(exclude_none=True)
+    current_cover.update(update_data)
+
+    config["cover"] = current_cover
+    normalized = normalize_plan_config(config)
+    plan_svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
+
+    return CoverConfigResponse(
+        type=current_cover.get("cover_type", "auto"),
+        image_url=current_cover.get("cover_image_url", ""),
+        frame_time=current_cover.get("frame_time", 0.0),
+    )
+
+
+@router.post("/cover/extract", response_model=CoverGenerateResponse)
+def extract_editor_cover(
+    template_id: str,
+    body: CoverExtractRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> CoverGenerateResponse:
+    """从指定片段抽帧生成封面"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    clip = plan_svc.get_clip(body.clip_id)
+    if not clip or clip.plan_id != plan_id:
+        raise HTTPException(status_code=400, detail="片段不存在或不属于当前草稿")
+
+    cover_url = f"cover/extract/{plan_id}_{body.clip_id}_{body.frame_time}.jpg"
+
+    config = dict(plan.config) if plan.config else {}
+    cover_config = dict(config.get("cover", {}))
+    cover_config.update(
+        {
+            "cover_type": "extract",
+            "cover_image_url": cover_url,
+            "clip_id": body.clip_id,
+            "frame_time": body.frame_time,
+        }
+    )
+    config["cover"] = cover_config
+    normalized = normalize_plan_config(config)
+    plan_svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
+
+    logger.info(
+        "模板编辑器封面抽帧: template_id=%s plan_id=%s clip_id=%s by user=%s",
+        template_id,
+        plan_id,
+        body.clip_id,
+        current_user.user.id,
+    )
+
+    return CoverGenerateResponse(
+        type="extract",
+        image_url=cover_url,
+        frame_time=body.frame_time,
+    )
+
+
+@router.post("/cover/smart", response_model=CoverGenerateResponse)
+def smart_editor_cover(
+    template_id: str,
+    body: CoverSmartRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> CoverGenerateResponse:
+    """智能选帧生成封面"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    cover_url = f"cover/smart/{plan_id}_smart.jpg"
+    strategy = getattr(body, "strategy", "auto")
+
+    config = dict(plan.config) if plan.config else {}
+    cover_config = dict(config.get("cover", {}))
+    cover_config.update(
+        {
+            "cover_type": "smart",
+            "cover_image_url": cover_url,
+            "strategy": strategy,
+        }
+    )
+    config["cover"] = cover_config
+    normalized = normalize_plan_config(config)
+    plan_svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
+
+    logger.info(
+        "模板编辑器智能封面: template_id=%s plan_id=%s strategy=%s by user=%s",
+        template_id,
+        plan_id,
+        strategy,
+        current_user.user.id,
+    )
+
+    return CoverGenerateResponse(
+        type="smart",
+        image_url=cover_url,
+        frame_time=None,
+    )
+
+
+@router.post("/generate-cover", response_model=GenerateCoverResponse)
+def editor_generate_cover(
+    template_id: str,
+    body: GenerateCoverRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> GenerateCoverResponse:
+    """AI 生成封面"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    from packages.shared.ai_service import run_generate_cover
+
+    cover_data = run_generate_cover(
+        plan_id=plan_id,
+        asset_ids=body.asset_ids,
+        cover_type=body.cover_type,
+        frame_time=body.frame_time,
+    )
+
+    current_config = dict(plan.config) if plan.config else {}
+    current_config["cover"] = cover_data
+    normalized = normalize_plan_config(current_config)
+    plan_svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
+
+    logger.info(
+        "模板编辑器封面生成: template_id=%s plan_id=%s type=%s by user=%s",
+        template_id,
+        plan_id,
+        body.cover_type,
+        current_user.user.id,
+    )
+
+    return GenerateCoverResponse(plan_id=plan_id, cover=cover_data)
@@ -0,0 +1,141 @@
+"""模板编辑器依赖注入.
+
+核心依赖：
+- get_editor_services: 获取模板+计划服务
+- get_draft_plan_id: 根据 template_id 获取或创建草稿，返回 plan_id
+- _check_queue_limits: 生成队列限流检查
+"""
+
+from __future__ import annotations
+
+import logging
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.core.task_enqueue import GLOBAL_PENDING_LIMIT, USER_PENDING_LIMIT
+from app.dependencies import get_db_session
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.template_repository import (
+    SQLAlchemyTemplateRepository,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def get_editor_services(
+    db: Session = Depends(get_db_session),
+) -> tuple[EditTemplateService, EditPlanService]:
+    """获取模板编辑器所需的两个服务"""
+    return EditTemplateService(db), EditPlanService(db)
+
+
+def get_draft_plan_id(
+    template_id: str,
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    db: Session = Depends(get_db_session),
+) -> str:
+    """路径依赖：根据 template_id 获取或创建草稿，返回 plan_id.
+
+    这是模板编辑器路由的核心依赖——所有编辑器端点都先经过这里，
+    确保 template_id → plan_id 的映射始终存在。
+
+    兼容策略：优先从新模板系统（edit_templates 表）查找，
+    若不存在则回退到旧模板系统（templates 表），确保用户自建模板可用。
+    """
+    tpl_svc, plan_svc = services
+    user_id = str(current_user.user.id)
+
+    # 1. 草稿已存在 → 直接返回
+    draft = tpl_svc.get_template_draft(template_id)
+    if draft is not None:
+        return draft.id
+
+    # 2. 新系统有模板 → 用新服务创建草稿
+    if tpl_svc.get_template(template_id) is not None:
+        draft = tpl_svc.create_template_draft(template_id, user_id=user_id)
+        return draft.id
+
+    # 3. 回退到旧模板系统（templates 表）
+    old_repo = SQLAlchemyTemplateRepository(db)
+    old_template = old_repo.get(template_id, user_id=user_id)
+    if old_template is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="模板不存在")
+
+    # 4. 基于旧模板创建草稿计划
+    from app.services.plan_generator_service import PlanGeneratorService
+
+    from packages.domain.edit_template import EditTemplate, EditTemplateStatus
+    from packages.domain.template_clip_config import ClipType, TemplateClipConfig
+
+    # 构造伪 EditTemplate 对象（只填 generate_from_template 需要的字段）
+    pseudo_template = EditTemplate(
+        id=old_template.id,
+        name=old_template.name,
+        editing_mode=old_template.mode,
+        status=EditTemplateStatus.ACTIVE,
+    )
+
+    # 将旧模板 segments 转换为 clip_configs
+    clip_configs: list[TemplateClipConfig] = []
+    for seg in old_template.segments or []:
+        clip_configs.append(
+            TemplateClipConfig(
+                id=f"seg_{seg.id}",
+                template_id=old_template.id,
+                clip_type=ClipType.MAIN,
+                order=seg.segment_order,
+                min_duration=seg.duration_min,
+                max_duration=seg.duration_max,
+            )
+        )
+
+    generator = PlanGeneratorService(db)
+    result = generator.generate_from_template(
+        template=pseudo_template,
+        clip_configs=clip_configs,
+        asset_ids=[],
+        created_by_user_id=user_id,
+        name=f"{old_template.name} - 草稿",
+    )
+    plan = result["plan"]
+
+    # 标记为模板草稿（后续可复用 tpl_svc.get_template_draft 的查找逻辑）
+    plan_svc.update_plan_config(plan.id, {"is_template_draft": True})
+
+    logger.info(
+        "旧模板自动创建草稿: template_id=%s draft_plan_id=%s user_id=%s",
+        template_id,
+        plan.id,
+        user_id,
+    )
+    return plan.id
+
+
+def _check_queue_limits(gen_task_repo, user_id: str) -> None:
+    """队列限流预检查"""
+    try:
+        has_count = (
+            hasattr(gen_task_repo, "count_pending_by_user")
+            and hasattr(gen_task_repo, "count_pending_total")
+        )
+        if has_count:
+            user_pending = gen_task_repo.count_pending_by_user(user_id)
+            global_pending = gen_task_repo.count_pending_total()
+            if user_pending >= USER_PENDING_LIMIT:
+                raise HTTPException(
+                    status_code=429,
+                    detail=f"您的待处理任务过多（当前 {user_pending}/{USER_PENDING_LIMIT}），请等待完成后再提交",
+                )
+            if global_pending >= GLOBAL_PENDING_LIMIT:
+                raise HTTPException(
+                    status_code=503,
+                    detail="系统繁忙，请稍后再试",
+                )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.warning("[模板编辑器队列限流] 检查失败，跳过: %s", e)
@@ -0,0 +1,164 @@
+"""草稿管理路由.
+
+端点：
+- GET    /              获取草稿详情
+- PUT    /              更新草稿
+- POST   /publish       发布草稿到模板
+- GET    /versions      模板版本历史
+- POST   /rollback      回滚到指定版本
+"""
+
+from __future__ import annotations
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import (
+    EditorDraftResponse,
+    EditorPublishResponse,
+    EditorRollbackRequest,
+    EditorRollbackResponse,
+    EditorTemplateVersionItem,
+    EditorUpdateRequest,
+    EditorVersionListResponse,
+)
+
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.get("", response_model=EditorDraftResponse)
+def get_editor_draft(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """获取模板编辑器草稿详情
+
+    首次访问时自动创建草稿。
+    """
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+    clips = plan_svc.list_clips(plan_id)
+    return EditorDraftResponse(
+        plan_id=plan.id,
+        template_id=plan.template_id,
+        name=plan.name,
+        status=plan.status.value if hasattr(plan.status, "value") else str(plan.status),
+        config=plan.config or {},
+        total_duration=plan.total_duration,
+        clip_count=len(clips),
+    )
+
+
+@router.put("", response_model=EditorDraftResponse)
+def update_editor_draft(
+    template_id: str,
+    req: EditorUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """更新模板编辑器草稿"""
+    _, plan_svc = services
+    plan = plan_svc.update_plan(
+        plan_id,
+        name=req.name,
+        config=req.config,
+        total_duration=req.total_duration,
+    )
+    clips = plan_svc.list_clips(plan_id)
+    return EditorDraftResponse(
+        plan_id=plan.id,
+        template_id=plan.template_id,
+        name=plan.name,
+        status=plan.status.value if hasattr(plan.status, "value") else str(plan.status),
+        config=plan.config or {},
+        total_duration=plan.total_duration,
+        clip_count=len(clips),
+    )
+
+
+@router.post("/publish", response_model=EditorPublishResponse, status_code=status.HTTP_200_OK)
+def publish_draft_to_template(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """将草稿发布（同步）到正式模板
+
+    草稿的 config 和 clips 会同步覆盖到模板，事务保证一致性。
+    """
+    tpl_svc, plan_svc = services
+    try:
+        tpl = tpl_svc.publish_template_from_draft(template_id, plan_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    clips = plan_svc.list_clips(plan_id)
+    return EditorPublishResponse(
+        template_id=tpl.id,
+        status="published",
+        clip_count=len(clips),
+        version=tpl.version,
+    )
+
+
+@router.get("/versions", response_model=EditorVersionListResponse)
+def list_template_versions(
+    template_id: str,
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+    limit: int = Query(default=50, ge=1, le=200),
+):
+    """查询模板发布版本历史"""
+    tpl_svc, _ = services
+    versions = tpl_svc.list_template_versions(template_id, limit=limit)
+    items = [
+        EditorTemplateVersionItem(
+            version=v.version,
+            name=v.name,
+            editing_mode=v.editing_mode,
+            clip_count=len(v.clip_configs),
+            change_note=v.change_note,
+            published_by=v.published_by,
+            created_at=(
+                v.created_at.isoformat()
+                if hasattr(v.created_at, "isoformat")
+                else str(v.created_at)
+            ),
+        )
+        for v in versions
+    ]
+    return EditorVersionListResponse(versions=items, total=len(items))
+
+
+@router.post("/rollback", response_model=EditorRollbackResponse, status_code=status.HTTP_200_OK)
+def rollback_template(
+    template_id: str,
+    request: EditorRollbackRequest,
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """回滚模板到指定历史版本
+
+    回滚本身也是一次发布，版本号会 +1，可以再次回滚。
+    """
+    tpl_svc, _ = services
+    try:
+        tpl = tpl_svc.rollback_to_version(template_id, request.version)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    clip_configs = tpl_svc.list_clip_configs(template_id)
+    return EditorRollbackResponse(
+        template_id=tpl.id,
+        status="rolled_back",
+        rollback_to_version=request.version,
+        new_version=tpl.version,
+        clip_count=len(clip_configs),
+    )
@@ -0,0 +1,195 @@
+"""转场 & 滤镜路由.
+
+端点：
+- GET  /transition-presets           转场预设列表
+- PUT  /clips/{clip_id}/transition   单片段转场
+- POST /transitions/batch            批量转场
+- GET  /filter-presets               滤镜预设列表
+- GET  /filter                       滤镜配置
+- PUT  /filter                       更新滤镜
+"""
+
+from __future__ import annotations
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException
+
+from packages.domain.config_schemas import normalize_plan_config
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import (
+    BatchTransitionRequest,
+    BatchTransitionResponse,
+    ClipTransitionResponse,
+    FilterConfigResponse,
+    FilterPresetListResponse,
+    FilterUpdateRequest,
+    TransitionPresetListResponse,
+    TransitionUpdateRequest,
+)
+
+router = APIRouter(tags=["Template Editor"])
+
+
+# ── 转场 ────────────────────────────────────────────────────────────────────
+
+
+@router.get("/transition-presets", response_model=TransitionPresetListResponse)
+def list_editor_transition_presets(
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> TransitionPresetListResponse:
+    """获取转场预设列表"""
+    from packages.domain.transition_presets import TRANSITION_PRESETS
+
+    items = [
+        {
+            "id": p["id"],
+            "name": p["name"],
+            "category": p.get("category", "通用"),
+            "duration": p.get("default_duration", 0.5),
+            "description": p.get("description", ""),
+        }
+        for p in TRANSITION_PRESETS
+    ]
+    return TransitionPresetListResponse(items=items, total=len(items))
+
+
+@router.put("/clips/{clip_id}/transition", response_model=ClipTransitionResponse)
+def update_editor_clip_transition(
+    template_id: str,
+    clip_id: str,
+    body: TransitionUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipTransitionResponse:
+    """设置单个片段的转场效果"""
+    _, plan_svc = services
+    try:
+        clip = plan_svc.update_clip(
+            clip_id,
+            transition_effect=body.effect,
+            transition_duration=body.duration,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return ClipTransitionResponse(
+        clip_id=clip.id,
+        effect=clip.transition_effect.value
+        if hasattr(clip.transition_effect, "value")
+        else clip.transition_effect,
+        duration=clip.transition_duration or 0.5,
+    )
+
+
+@router.post("/transitions/batch", response_model=BatchTransitionResponse)
+def batch_update_editor_transitions(
+    template_id: str,
+    body: BatchTransitionRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> BatchTransitionResponse:
+    """批量设置所有片段的转场效果"""
+    _, plan_svc = services
+    clips = plan_svc.list_clips(plan_id, limit=500)
+    updated = 0
+    for clip in clips:
+        if clip.order > 0:  # 第一个片段不加转场
+            try:
+                plan_svc.update_clip(
+                    clip.id,
+                    transition_effect=body.effect,
+                    transition_duration=body.duration,
+                )
+                updated += 1
+            except ValueError:
+                pass
+
+    return BatchTransitionResponse(
+        updated_count=updated,
+        plan_id=plan_id,
+    )
+
+
+# ── 滤镜 ────────────────────────────────────────────────────────────────────
+
+
+@router.get("/filter-presets", response_model=FilterPresetListResponse)
+def list_editor_filter_presets(
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> FilterPresetListResponse:
+    """获取滤镜预设列表"""
+    from packages.domain.filter_presets import FILTER_PRESETS
+
+    items = [
+        {
+            "id": p["id"],
+            "name": p["name"],
+            "category": p.get("category", "通用"),
+            "thumbnail": p.get("thumbnail", ""),
+            "description": p.get("description", ""),
+        }
+        for p in FILTER_PRESETS
+    ]
+    return FilterPresetListResponse(items=items, total=len(items))
+
+
+@router.get("/filter", response_model=FilterConfigResponse)
+def get_editor_filter(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> FilterConfigResponse:
+    """获取草稿的全局滤镜配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+    config = plan.config or {}
+    filter_config = config.get("filter", {})
+
+    return FilterConfigResponse(
+        plan_id=plan.id,
+        enabled=filter_config.get("enabled", False),
+        preset_id=filter_config.get("preset_id", ""),
+        intensity=filter_config.get("intensity", 1.0),
+        brightness=filter_config.get("brightness", 0.0),
+        contrast=filter_config.get("contrast", 1.0),
+        saturation=filter_config.get("saturation", 1.0),
+        warmth=filter_config.get("warmth", 0.0),
+    )
+
+
+@router.put("/filter", response_model=FilterConfigResponse)
+def update_editor_filter(
+    template_id: str,
+    body: FilterUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> FilterConfigResponse:
+    """更新草稿的全局滤镜配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    config = dict(plan.config) if plan.config else {}
+    current_filter = dict(config.get("filter", {}))
+    update_data = body.model_dump(exclude_none=True)
+    current_filter.update(update_data)
+
+    config["filter"] = current_filter
+    updated_plan = plan_svc.update_plan_config(plan_id, normalize_plan_config(config))
+
+    return FilterConfigResponse(
+        plan_id=updated_plan.id,
+        enabled=current_filter.get("enabled", False),
+        preset_id=current_filter.get("preset_id", ""),
+        intensity=current_filter.get("intensity", 1.0),
+        brightness=current_filter.get("brightness", 0.0),
+        contrast=current_filter.get("contrast", 1.0),
+        saturation=current_filter.get("saturation", 1.0),
+        warmth=current_filter.get("warmth", 0.0),
+    )
@@ -0,0 +1,106 @@
+"""导出配置路由.
+
+端点：
+- GET /export-presets      导出预设列表
+- GET /export              导出配置
+- PUT /export              更新导出配置
+"""
+
+from __future__ import annotations
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends
+
+from packages.domain.config_schemas import normalize_plan_config
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import ExportConfigResponse, ExportPresetListResponse, ExportUpdateRequest
+
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.get("/export-presets", response_model=ExportPresetListResponse)
+def list_editor_export_presets(
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ExportPresetListResponse:
+    """获取导出预设列表"""
+    from packages.domain.export_presets import EXPORT_PRESETS
+
+    items = [
+        {
+            "id": p["id"],
+            "name": p["name"],
+            "resolution": p.get("resolution", "1080p"),
+            "fps": p.get("fps", 30),
+            "video_bitrate": p.get("bitrate", ""),
+            "audio_bitrate": p.get("audio_bitrate", 128),
+            "format": p.get("format", "mp4"),
+            "quality_preset": p.get("quality_preset", "balanced"),
+            "description": p.get("description", ""),
+            "size_hint": p.get("size_hint", ""),
+        }
+        for p in EXPORT_PRESETS
+    ]
+    return ExportPresetListResponse(items=items, total=len(items))
+
+
+@router.get("/export", response_model=ExportConfigResponse)
+def get_editor_export(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ExportConfigResponse:
+    """获取草稿的导出配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+    config = plan.config or {}
+    export_config = config.get("export", {})
+
+    return ExportConfigResponse(
+        plan_id=plan.id,
+        resolution=export_config.get("resolution", "1080p"),
+        fps=export_config.get("fps", 30),
+        video_bitrate=export_config.get("video_bitrate", 4000),
+        audio_bitrate=export_config.get("audio_bitrate", 128),
+        format=export_config.get("format", "mp4"),
+        quality_preset=export_config.get("quality_preset", "balanced"),
+        watermark_enabled=export_config.get("watermark_enabled", True),
+        watermark_text=export_config.get("watermark_text", ""),
+    )
+
+
+@router.put("/export", response_model=ExportConfigResponse)
+def update_editor_export(
+    template_id: str,
+    body: ExportUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ExportConfigResponse:
+    """更新草稿的导出配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    config = dict(plan.config) if plan.config else {}
+    current_export = dict(config.get("export", {}))
+    update_data = body.model_dump(exclude_none=True)
+    current_export.update(update_data)
+
+    config["export"] = current_export
+    updated_plan = plan_svc.update_plan_config(plan_id, normalize_plan_config(config))
+    updated_export = (updated_plan.config or {}).get("export", {})
+
+    return ExportConfigResponse(
+        plan_id=updated_plan.id,
+        resolution=updated_export.get("resolution", "1080p"),
+        fps=updated_export.get("fps", 30),
+        video_bitrate=updated_export.get("video_bitrate", 4000),
+        audio_bitrate=updated_export.get("audio_bitrate", 128),
+        format=updated_export.get("format", "mp4"),
+        quality_preset=updated_export.get("quality_preset", "balanced"),
+        watermark_enabled=updated_export.get("watermark_enabled", True),
+        watermark_text=updated_export.get("watermark_text", ""),
+    )
@@ -0,0 +1,250 @@
+"""草稿生成路由.
+
+端点：
+- POST /generate              触发生成
+- GET  /generation-status     生成进度
+- GET  /generations           生成记录列表
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.core.celery_app import celery_app
+from app.core.storage import OSSStorageService, get_storage_service
+from app.dependencies import (
+    get_asset_library_repository,
+    get_asset_repository,
+    get_db_session,
+)
+from app.schemas.generation_task import GenerationTaskResponse
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.generation_task_repository import (
+    SQLAlchemyGenerationTaskRepository,
+)
+from packages.application.generation_tasks import (
+    CreateGenerationTaskCommand,
+    CreateGenerationTaskUseCase,
+)
+from packages.domain.edit_plan import EditPlanStatus
+
+from ._fallback import (
+    _auto_fallback_assign_assets,
+    _auto_fallback_auto_material_mode,
+    _auto_fallback_copy_template_clips,
+    _auto_fallback_draft_to_editing,
+)
+from .dependencies import _check_queue_limits, get_draft_plan_id, get_editor_services
+from .schemas import (
+    ClipStatusItem,
+    EditPlanGenerateResponse,
+    EditPlanGenerationsResponse,
+    EditPlanGenerationStatusResponse,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.post("/generate", response_model=EditPlanGenerateResponse)
+def generate_editor_draft(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    asset_library_repo: Any = Depends(get_asset_library_repository),
+    asset_repo: Any = Depends(get_asset_repository),
+) -> EditPlanGenerateResponse:
+    """触发模板草稿渲染生成"""
+    _, plan_svc = services
+    plan_check = plan_svc.get_plan_or_raise(plan_id)
+
+    # 自动兜底流程
+    _auto_fallback_draft_to_editing(plan_svc, plan_id, plan_check)
+    _auto_fallback_copy_template_clips(plan_svc, plan_id, plan_check, db)
+    clips_without_asset = _auto_fallback_assign_assets(plan_svc, plan_id, plan_check)
+    _auto_fallback_auto_material_mode(
+        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:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)
+        ) from exc
+    if not can_gen:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail=reason
+        )
+
+    try:
+        clip_count = plan_svc.mark_clips_ready(plan_id)
+
+        gen_task_repo = SQLAlchemyGenerationTaskRepository(db)
+        user_id = current_user.user.id
+        _check_queue_limits(gen_task_repo, user_id)
+
+        gen_task_use_case = CreateGenerationTaskUseCase(gen_task_repo)
+        plan = plan_svc.get_plan_or_raise(plan_id)
+        config_asset_ids = (plan.config or {}).get("asset_ids", [])
+        gen_task = gen_task_use_case.execute(
+            CreateGenerationTaskCommand(
+                project_id=plan.project_id or "",
+                template_id=plan.template_id,
+                created_by_user_id=current_user.user.id,
+                source_edit_plan_id=plan_id,
+                asset_ids=list(config_asset_ids) if config_asset_ids else [],
+            ),
+        )
+
+        plan_svc.update_plan_config(plan_id, {"generation_task_id": gen_task.id})
+        plan_svc.transition_status(plan_id, EditPlanStatus.RENDERING)
+        celery_app.send_task("worker.render_edit_plan", args=[plan_id])
+
+        updated_plan = plan_svc.get_plan_or_raise(plan_id)
+
+        logger.info(
+            "模板编辑器触发生成: template_id=%s plan_id=%s gen_task_id=%s clips=%d by user=%s",
+            template_id,
+            plan_id,
+            gen_task.id,
+            clip_count,
+            current_user.user.id,
+        )
+
+        return EditPlanGenerateResponse(
+            plan_id=plan_id,
+            plan_status=updated_plan.status.value
+            if hasattr(updated_plan.status, "value")
+            else updated_plan.status,
+            generation_task_id=gen_task.id,
+            clip_count=clip_count,
+        )
+    except HTTPException:
+        raise
+    except Exception as _e:
+        logger.exception(
+            "模板编辑器触发生成失败: template_id=%s plan_id=%s",
+            template_id,
+            plan_id,
+        )
+        try:
+            plan_svc.transition_status(plan_id, EditPlanStatus.FAILED)
+        except Exception:
+            pass
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="生成失败，请稍后重试",
+        ) from _e
+
+
+@router.get("/generation-status", response_model=EditPlanGenerationStatusResponse)
+def get_editor_generation_status(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    storage_service: OSSStorageService = Depends(get_storage_service),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> EditPlanGenerationStatusResponse:
+    """查询草稿生成进度"""
+    _, plan_svc = services
+    try:
+        gen_status = plan_svc.get_generation_status(plan_id)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)
+        ) from exc
+
+    plan = gen_status["plan"]
+    clips = gen_status["clips"]
+
+    clip_items = [
+        ClipStatusItem(
+            clip_id=c.id,
+            clip_type=c.clip_type,
+            order=c.order,
+            status=c.status.value if hasattr(c.status, "value") else c.status,
+            asset_id=c.asset_id or "",
+            text_content=c.text_content or "",
+            duration=c.duration,
+        )
+        for c in clips
+    ]
+
+    raw_video_url = (plan.config or {}).get("rendered_url", "")
+    video_url = ""
+    if raw_video_url:
+        try:
+            video_url = storage_service.get_download_url(
+                raw_video_url, expires_seconds=86400
+            )
+        except Exception as e:
+            logger.warning(
+                "生成视频签名URL失败: template_id=%s error=%s", template_id, e
+            )
+            video_url = raw_video_url
+
+    progress = gen_status.get("progress", 0.0)
+    error_message = gen_status.get("error_message", "")
+    gen_task_status = gen_status.get("generation_task_status")
+    plan_status_val = (
+        plan.status.value if hasattr(plan.status, "value") else plan.status
+    )
+    if plan_status_val == "completed" and progress < 100:
+        progress = 100.0
+
+    return EditPlanGenerationStatusResponse(
+        plan_id=plan_id,
+        plan_status=plan_status_val,
+        generation_task_id=gen_status["generation_task_id"],
+        generation_task_status=gen_task_status,
+        progress=progress,
+        video_url=video_url,
+        error_message=error_message,
+        clips=clip_items,
+    )
+
+
+@router.get("/generations", response_model=EditPlanGenerationsResponse)
+def list_editor_generations(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    db: Session = Depends(get_db_session),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> EditPlanGenerationsResponse:
+    """查询草稿关联的生成记录列表"""
+    _, plan_svc = services
+    plan_svc.get_plan_or_raise(plan_id)
+
+    gen_task_repo = SQLAlchemyGenerationTaskRepository(db)
+    tasks = gen_task_repo.list_by_source_edit_plan(plan_id)
+    items = [
+        GenerationTaskResponse(
+            id=t.id,
+            project_id=t.project_id,
+            asset_library_id=t.asset_library_id,
+            strategy_id=t.strategy_id,
+            voice_library_id=t.voice_library_id,
+            template_id=t.template_id,
+            asset_ids=t.asset_ids,
+            title_ids=t.title_ids,
+            voice_ids=t.voice_ids,
+            source_edit_plan_id=t.source_edit_plan_id or "",
+            status=t.status.value if hasattr(t.status, "value") else t.status,
+            progress=t.progress,
+            result_count=t.result_count,
+            error_message=t.error_message,
+        )
+        for t in tasks
+    ]
+    return EditPlanGenerationsResponse(items=items, total=len(items))
@@ -0,0 +1,622 @@
+"""模板编辑器所有 Pydantic Schema 定义.
+
+集中管理，避免在路由文件里散落 40+ 个 model。
+"""
+
+from __future__ import annotations
+
+import re as _re
+from typing import Any, List, Optional
+
+from app.schemas.generation_task import GenerationTaskResponse
+from pydantic import BaseModel, Field, validator
+
+_EXPORT_RESOLUTION_PATTERN = _re.compile(r"^\d+x\d+$")
+_EXPORT_VALID_QUALITY_PRESETS = {"ultra_fast", "fast", "balanced", "high", "best"}
+_EXPORT_VALID_FORMATS = {"mp4", "mov"}
+
+
+# ── 生成状态相关 ────────────────────────────────────────────────────────────
+
+
+class ClipStatusItem(BaseModel):
+    """片段生成状态"""
+
+    clip_id: str
+    clip_type: str
+    order: int
+    status: str
+    asset_id: str
+    text_content: str
+    duration: float
+
+
+class EditPlanGenerationStatusResponse(BaseModel):
+    """剪辑计划生成进度响应体"""
+
+    plan_id: str
+    plan_status: str
+    generation_task_id: Optional[str] = None
+    generation_task_status: Optional[str] = None
+    progress: float = 0.0
+    video_url: str = ""
+    error_message: str = ""
+    clips: List[ClipStatusItem]
+
+
+class EditPlanGenerateResponse(BaseModel):
+    """剪辑计划触发生成响应体"""
+
+    plan_id: str
+    plan_status: str
+    generation_task_id: str
+    clip_count: int
+
+
+class EditPlanGenerationsResponse(BaseModel):
+    """剪辑计划关联的生成记录列表响应体"""
+
+    items: List[GenerationTaskResponse]
+    total: int
+
+
+# ── AI 推荐 ────────────────────────────────────────────────────────────────
+
+
+class AIRecommendRequest(BaseModel):
+    """AI 推荐片段方案请求体"""
+
+    asset_ids: List[str] = Field(default_factory=list, description="素材 ID 列表")
+    editing_mode: str = Field(
+        default="one_take", description="剪辑模式: one_take / pip / voice_over / voice_pip"
+    )
+    target_duration: float = Field(
+        default=30.0, ge=1.0, le=600.0, description="目标时长（秒）"
+    )
+
+
+class AIRecommendClipItem(BaseModel):
+    """AI 推荐的单个片段"""
+
+    clip_type: str = Field(..., description="片段类型: intro / showcase / title / subtitle / cta / outro")
+    order: int = Field(..., ge=0, description="片段顺序")
+    text_content: str = Field(default="", description="文字内容")
+    duration: float = Field(..., ge=0.0, description="片段时长（秒）")
+    transition_effect: str = Field(default="cut", description="转场效果")
+    transition_duration: float = Field(default=0.0, ge=0.0, description="转场时长（秒），0 表示使用默认值")
+    asset_id: str = Field(default="", description="关联素材 ID")
+    start_time: float = Field(default=0.0, ge=0.0, description="素材截取起始时间（秒）")
+    config: dict[str, Any] = Field(default_factory=dict, description="片段额外配置")
+
+
+class AIRecommendResponse(BaseModel):
+    """AI 推荐片段方案响应体"""
+
+    plan_id: str = Field(..., description="剪辑计划 ID")
+    clips: List[AIRecommendClipItem] = Field(..., description="推荐的片段列表")
+    config: dict[str, Any] = Field(..., description="推荐的 plan config（cover/title/subtitle/bgm）")
+    total_duration: float = Field(..., ge=0.0, description="推荐方案总时长（秒）")
+    confidence: float = Field(..., ge=0.0, le=1.0, description="AI 推荐置信度 (0~1)")
+
+
+# ── 封面生成 ────────────────────────────────────────────────────────────────
+
+
+class GenerateCoverRequest(BaseModel):
+    """AI 封面生成请求体"""
+
+    asset_ids: List[str] = Field(default_factory=list, description="素材 ID 列表（确定视频来源）")
+    cover_type: str = Field(
+        default="ai_frame",
+        description="封面类型: ai_frame / manual / upload / ai_regenerate",
+    )
+    frame_time: Optional[float] = Field(
+        default=None,
+        ge=0.0,
+        description="手动选帧时间点（秒），仅 cover_type=manual 时有效",
+    )
+
+
+class GenerateCoverResponse(BaseModel):
+    """AI 封面生成响应体"""
+
+    plan_id: str = Field(..., description="剪辑计划 ID")
+    cover: dict[str, Any] = Field(..., description="封面数据（type / image_url / frame_time 等）")
+
+
+# ── BGM ────────────────────────────────────────────────────────────────────
+
+
+class BGMConfigUpdateRequest(BaseModel):
+    """更新BGM配置请求体"""
+
+    enabled: Optional[bool] = Field(default=None, description="是否启用 BGM")
+    source: Optional[str] = Field(default=None, description="BGM 来源: library/upload/ai_recommend")
+    asset_id: Optional[str] = Field(default=None, max_length=64, description="BGM 素材 ID")
+    preset_id: Optional[str] = Field(default=None, max_length=64, description="预设 BGM ID")
+    audio_url: Optional[str] = Field(default=None, max_length=500, description="BGM 音频 URL")
+    volume: Optional[float] = Field(default=None, ge=0.0, le=1.0, description="音量 (0.0 ~ 1.0)")
+    fade_in: Optional[float] = Field(default=None, ge=0.0, le=30.0, description="淡入时长（秒）")
+    fade_out: Optional[float] = Field(default=None, ge=0.0, le=30.0, description="淡出时长（秒）")
+    loop_enabled: Optional[bool] = Field(default=None, description="是否循环播放")
+    sidechain_enabled: Optional[bool] = Field(default=None, description="是否启用人声闪避")
+    sidechain_ratio: Optional[float] = Field(default=None, ge=0.0, le=1.0, description="闪避音量降低比例")
+
+
+# ── 片段调整 ────────────────────────────────────────────────────────────────
+
+
+class SpeedAdjustRequest(BaseModel):
+    """调速请求"""
+
+    speed: float = Field(..., ge=0.25, le=4.0, description="播放速度 0.25~4.0")
+
+
+class VolumeAdjustRequest(BaseModel):
+    """音量调节请求"""
+
+    volume: float = Field(..., ge=0.0, le=2.0, description="音量倍率 0~2.0（1.0=原音量）")
+
+
+class TrimAdjustRequest(BaseModel):
+    """裁剪请求"""
+
+    trim_start: float = Field(0.0, ge=0.0, description="开头裁剪秒数")
+    trim_end: float = Field(0.0, ge=0.0, description="结尾裁剪秒数")
+
+
+class ClipAdjustmentsRequest(BaseModel):
+    """统一调整请求"""
+
+    speed: Optional[float] = Field(default=None, ge=0.25, le=4.0)
+    volume: Optional[float] = Field(default=None, ge=0.0, le=2.0)
+    trim_start: Optional[float] = Field(default=None, ge=0.0)
+    trim_end: Optional[float] = Field(default=None, ge=0.0)
+
+
+class BatchSpeedRequest(BaseModel):
+    """批量调速请求"""
+
+    speed: float = Field(..., ge=0.25, le=4.0, description="播放速度")
+
+
+class ClipAdjustResponse(BaseModel):
+    """片段调整响应"""
+
+    clip_id: str
+    speed: float
+    volume: float
+    trim_start: float
+    trim_end: float
+    duration: float
+
+
+class BatchSpeedResponse(BaseModel):
+    """批量调速响应"""
+
+    updated_count: int
+    plan_id: str
+
+
+# ── 片段批量操作 ────────────────────────────────────────────────────────────
+
+
+class ClipReorderItem(BaseModel):
+    """重排序条目"""
+
+    clip_id: str
+    new_order: int = Field(..., ge=0, description="新的排序序号")
+
+
+class ClipReorderRequest(BaseModel):
+    """片段重排序请求"""
+
+    items: List[ClipReorderItem] = Field(..., min_length=1, max_length=500, description="重排序条目列表")
+
+
+class ClipReorderResponse(BaseModel):
+    """片段重排序响应"""
+
+    success: bool = True
+    updated_count: int
+    message: str = ""
+
+
+class ClipBatchDeleteRequest(BaseModel):
+    """批量删除片段请求"""
+
+    clip_ids: List[str] = Field(..., min_length=1, max_length=500, description="要删除的片段ID列表")
+
+
+class ClipBatchDeleteResponse(BaseModel):
+    """批量删除片段响应"""
+
+    success: bool = True
+    deleted_count: int
+    message: str = ""
+
+
+class ClipsFromAssetsRequest(BaseModel):
+    """从素材批量创建片段请求"""
+
+    asset_ids: List[str] = Field(
+        ..., min_length=1, max_length=200, description="素材 ID 列表，按顺序追加到时间线末尾"
+    )
+    clip_type: str = Field(default="main", description="片段类型，默认 main")
+
+
+class ClipsFromAssetsResponse(BaseModel):
+    """从素材批量创建片段响应"""
+
+    success: bool = True
+    created_count: int
+    message: str = ""
+    clip_ids: List[str] = Field(default_factory=list, description="创建的片段ID列表")
+
+
+# ── 封面配置 ────────────────────────────────────────────────────────────────
+
+
+class CoverConfigResponse(BaseModel):
+    """封面配置响应"""
+
+    type: str = Field(..., description="封面类型: ai_frame / manual / upload")
+    image_url: str = Field(default="", description="封面图片 URL")
+    frame_time: Optional[float] = Field(default=None, description="抽帧时间点（秒）")
+
+
+class CoverUpdateRequest(BaseModel):
+    """更新封面配置请求"""
+
+    type: Optional[str] = Field(default=None, description="封面类型")
+    image_url: Optional[str] = Field(default=None, description="封面图片 URL")
+    frame_time: Optional[float] = Field(default=None, ge=0.0, description="抽帧时间点（秒）")
+
+
+class CoverExtractRequest(BaseModel):
+    """从片段抽帧生成封面请求"""
+
+    clip_id: str = Field(..., description="片段 ID")
+    frame_time: float = Field(1.0, ge=0.0, description="抽帧时间点（秒）")
+
+
+class CoverSmartRequest(BaseModel):
+    """智能选帧请求"""
+
+    clip_id: Optional[str] = Field(default=None, description="指定片段 ID（不传则用第一个视频片段）")
+
+
+class CoverGenerateResponse(BaseModel):
+    """封面生成响应"""
+
+    type: str = Field(..., description="封面类型")
+    image_url: str = Field(..., description="封面图片 URL")
+    frame_time: Optional[float] = Field(default=None, description="抽帧时间点（秒）")
+
+
+# ── 导出配置 ────────────────────────────────────────────────────────────────
+
+
+class ExportConfigResponse(BaseModel):
+    """导出配置响应"""
+
+    resolution: str
+    fps: int
+    video_bitrate: int
+    audio_bitrate: int
+    format: str
+    quality_preset: str
+    watermark_enabled: bool
+    watermark_text: str
+
+
+class ExportUpdateRequest(BaseModel):
+    """更新导出配置请求"""
+
+    resolution: Optional[str] = None
+    fps: Optional[int] = Field(default=None, ge=15, le=60)
+    video_bitrate: Optional[int] = Field(default=None, ge=1000, le=20000)
+    audio_bitrate: Optional[int] = Field(default=None, ge=64, le=320)
+    format: Optional[str] = None
+    quality_preset: Optional[str] = None
+    watermark_enabled: Optional[bool] = None
+    watermark_text: Optional[str] = None
+
+    @validator("resolution")
+    def validate_resolution(cls, v):
+        if v is None:
+            return v
+        if not _EXPORT_RESOLUTION_PATTERN.match(v):
+            raise ValueError("分辨率格式错误，应为 宽x高，如 1080x1920")
+        w, h = v.split("x")
+        if int(w) < 100 or int(h) < 100:
+            raise ValueError("分辨率数值过小")
+        if int(w) > 4096 or int(h) > 4096:
+            raise ValueError("分辨率数值过大，最大 4096x4096")
+        return v
+
+    @validator("format")
+    def validate_format(cls, v):
+        if v is None:
+            return v
+        if v not in _EXPORT_VALID_FORMATS:
+            raise ValueError(f"无效格式: {v}，支持: {_EXPORT_VALID_FORMATS}")
+        return v
+
+    @validator("quality_preset")
+    def validate_quality_preset(cls, v):
+        if v is None:
+            return v
+        if v not in _EXPORT_VALID_QUALITY_PRESETS:
+            raise ValueError(f"无效质量预设: {v}，支持: {_EXPORT_VALID_QUALITY_PRESETS}")
+        return v
+
+
+class ExportPresetItem(BaseModel):
+    """导出预设条目"""
+
+    id: str
+    name: str
+    resolution: str
+    fps: int
+    video_bitrate: int
+    audio_bitrate: int
+    format: str
+    quality_preset: str
+    description: str
+    size_hint: str
+
+
+class ExportPresetListResponse(BaseModel):
+    """导出预设列表响应"""
+
+    items: List[ExportPresetItem]
+    total: int
+
+
+# ── 滤镜 ────────────────────────────────────────────────────────────────────
+
+
+class FilterPresetResponse(BaseModel):
+    """滤镜预设响应"""
+
+    id: str
+    name: str
+    category: str
+    description: str
+    tags: List[str] = Field(default_factory=list)
+
+
+class FilterConfigResponse(BaseModel):
+    """滤镜配置响应"""
+
+    enabled: bool
+    preset_id: str
+    intensity: int
+    brightness: float
+    contrast: float
+    saturation: float
+    warmth: float
+
+
+class FilterUpdateRequest(BaseModel):
+    """更新滤镜配置请求"""
+
+    enabled: Optional[bool] = None
+    preset_id: Optional[str] = None
+    intensity: Optional[int] = Field(default=None, ge=0, le=100)
+    brightness: Optional[float] = Field(default=None, ge=-1.0, le=1.0)
+    contrast: Optional[float] = Field(default=None, ge=0.0, le=2.0)
+    saturation: Optional[float] = Field(default=None, ge=0.0, le=3.0)
+    warmth: Optional[float] = Field(default=None, ge=-1.0, le=1.0)
+
+
+class FilterPresetListResponse(BaseModel):
+    """滤镜预设列表响应"""
+
+    items: List[FilterPresetResponse]
+    total: int
+
+
+# ── 转场 ────────────────────────────────────────────────────────────────────
+
+
+class TransitionPresetResponse(BaseModel):
+    """转场预设响应"""
+
+    id: str
+    name: str
+    category: str
+    description: str
+    tags: List[str] = Field(default_factory=list)
+    default_duration: float
+    min_duration: float
+    max_duration: float
+
+
+class TransitionUpdateRequest(BaseModel):
+    """更新转场请求"""
+
+    effect: str = Field(..., description="转场效果 ID")
+    duration: Optional[float] = Field(default=None, ge=0.0, description="转场时长（秒）")
+
+
+class BatchTransitionRequest(BaseModel):
+    """批量设置转场请求"""
+
+    effect: str = Field(..., description="转场效果 ID")
+    duration: Optional[float] = Field(default=None, ge=0.0, description="转场时长（秒）")
+    apply_to: str = Field(
+        default="all",
+        description="应用范围: all=所有片段, except_first=除第一个外, except_last=除最后一个, middle=中间片段",
+    )
+
+
+class ClipTransitionResponse(BaseModel):
+    """片段转场信息响应"""
+
+    clip_id: str
+    effect: str
+    duration: float
+
+
+class BatchTransitionResponse(BaseModel):
+    """批量转场响应"""
+
+    updated_count: int
+    plan_id: str
+
+
+class TransitionPresetListResponse(BaseModel):
+    """转场预设列表响应"""
+
+    items: List[TransitionPresetResponse]
+    total: int
+
+
+# ── 编辑器草稿 & 片段 ───────────────────────────────────────────────────────
+
+
+class EditorDraftResponse(BaseModel):
+    """模板编辑器草稿详情响应"""
+
+    plan_id: str
+    template_id: str
+    name: str
+    status: str
+    config: dict[str, Any]
+    total_duration: float
+    clip_count: int
+    is_draft: bool = True
+
+
+class EditorUpdateRequest(BaseModel):
+    """更新草稿请求"""
+
+    name: Optional[str] = Field(default=None, min_length=1, max_length=200)
+    config: Optional[dict[str, Any]] = Field(default=None)
+    total_duration: Optional[float] = Field(default=None, ge=0.0)
+
+
+class EditorClipResponse(BaseModel):
+    """片段响应"""
+
+    id: str
+    plan_id: str
+    clip_type: str
+    order: int
+    duration: float
+    text_content: str = ""
+    transition_effect: str = "cut"
+    playback_speed: float = 1.0
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class EditorClipListResponse(BaseModel):
+    """片段列表响应"""
+
+    items: List[EditorClipResponse]
+    total: int
+
+
+class EditorClipCreateRequest(BaseModel):
+    """创建片段请求"""
+
+    clip_type: str = Field(..., min_length=1, max_length=32)
+    order: int = Field(..., ge=0)
+    duration: float = Field(..., gt=0.0)
+    text_content: str = Field(default="", max_length=2000)
+    transition_effect: str = Field(default="cut", max_length=32)
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class EditorClipUpdateRequest(BaseModel):
+    """更新片段请求"""
+
+    order: Optional[int] = Field(default=None, ge=0)
+    duration: Optional[float] = Field(default=None, gt=0.0)
+    text_content: Optional[str] = Field(default=None, max_length=2000)
+    transition_effect: Optional[str] = Field(default=None, max_length=32)
+    playback_speed: Optional[float] = Field(default=None, gt=0.0)
+    config: Optional[dict[str, Any]] = None
+
+
+class EditorPublishResponse(BaseModel):
+    """发布草稿响应"""
+
+    template_id: str
+    status: str = "published"
+    clip_count: int
+    version: int = 1
+
+
+class EditorTemplateVersionItem(BaseModel):
+    """模板版本历史条目"""
+
+    version: int
+    name: str
+    editing_mode: str
+    clip_count: int
+    change_note: str
+    published_by: str
+    created_at: str
+
+
+class EditorVersionListResponse(BaseModel):
+    """模板版本列表响应"""
+
+    versions: list[EditorTemplateVersionItem]
+    total: int
+
+
+class EditorRollbackRequest(BaseModel):
+    """回滚请求体"""
+
+    version: int
+
+
+class EditorRollbackResponse(BaseModel):
+    """回滚响应"""
+
+    template_id: str
+    status: str = "rolled_back"
+    rollback_to_version: int
+    new_version: int
+    clip_count: int
+
+
+# ── 片段分割与合并 ──────────────────────────────────────────────────────────
+
+
+class SplitClipRequest(BaseModel):
+    """分割片段请求体"""
+
+    split_time: float = Field(..., gt=0, description="分割点（秒，相对于片段起始）")
+
+
+class MergeClipsRequest(BaseModel):
+    """合并片段请求体"""
+
+    clip_ids: list[str] = Field(..., min_length=2, description="要合并的片段 ID 列表")
+
+
+# ── 时间线 ──────────────────────────────────────────────────────────────────
+
+
+class EditorTimelineSceneResponse(BaseModel):
+    """时间线场景"""
+
+    scene: str
+    time: str
+    duration: float
+    color: str
+    clip_id: str = ""
+    clip_type: str = ""
+
+
+class EditorTimelineResponse(BaseModel):
+    """时间线响应"""
+
+    plan_id: str
+    total_duration: float
+    scenes: List[EditorTimelineSceneResponse]
@@ -0,0 +1,173 @@
+"""字幕管理路由.
+
+端点：
+- GET    /clips/{clip_id}/subtitles              字幕列表
+- POST   /clips/{clip_id}/subtitles              新增字幕
+- PUT    /clips/{clip_id}/subtitles/{subtitle_id} 更新字幕
+- DELETE /clips/{clip_id}/subtitles/{subtitle_id} 删除字幕
+- PUT    /clips/{clip_id}/subtitles              批量更新字幕（全量替换）
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from .dependencies import get_draft_plan_id, get_editor_services
+
+router = APIRouter(tags=["Template Editor"])
+
+
+def _get_clip_subtitles(plan_svc: EditPlanService, clip_id: str, plan_id: str) -> list[dict[str, Any]]:
+    """获取片段字幕列表，统一校验"""
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+    if clip.plan_id != plan_id:
+        raise HTTPException(status_code=404, detail="片段不存在")
+    config = clip.config or {}
+    subtitles = config.get("subtitles", [])
+    if not isinstance(subtitles, list):
+        subtitles = []
+    return subtitles
+
+
+@router.get("/clips/{clip_id}/subtitles", response_model=list[dict[str, Any]])
+def get_editor_clip_subtitles(
+    template_id: str,
+    clip_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> list[dict[str, Any]]:
+    """获取片段的字幕列表"""
+    _, plan_svc = services
+    return _get_clip_subtitles(plan_svc, clip_id, plan_id)
+
+
+@router.post("/clips/{clip_id}/subtitles", response_model=dict[str, Any])
+def create_editor_clip_subtitle(
+    template_id: str,
+    clip_id: str,
+    body: dict[str, Any],
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> dict[str, Any]:
+    """新增片段字幕"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    config = dict(clip.config) if clip.config else {}
+    subtitles = config.get("subtitles", [])
+    if not isinstance(subtitles, list):
+        subtitles = []
+
+    new_id = f"sub_{len(subtitles) + 1}"
+    new_subtitle = {
+        "id": body.get("id", new_id),
+        "start_time": body.get("start_time", 0.0),
+        "end_time": body.get("end_time", 0.0),
+        "text": body.get("text", ""),
+        "style": body.get("style", {}),
+    }
+    subtitles.append(new_subtitle)
+    config["subtitles"] = subtitles
+
+    plan_svc.update_clip(clip_id, config=config)
+    return new_subtitle
+
+
+@router.put("/clips/{clip_id}/subtitles/{subtitle_id}", response_model=dict[str, Any])
+def update_editor_clip_subtitle(
+    template_id: str,
+    clip_id: str,
+    subtitle_id: str,
+    body: dict[str, Any],
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> dict[str, Any]:
+    """更新片段字幕"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    config = dict(clip.config) if clip.config else {}
+    subtitles = config.get("subtitles", [])
+    if not isinstance(subtitles, list):
+        subtitles = []
+
+    found = False
+    for i, sub in enumerate(subtitles):
+        if sub.get("id") == subtitle_id:
+            subtitles[i].update(body)
+            found = True
+            break
+
+    if not found:
+        raise HTTPException(status_code=404, detail="字幕不存在")
+
+    config["subtitles"] = subtitles
+    plan_svc.update_clip(clip_id, config=config)
+    return subtitles[i]
+
+
+@router.delete(
+    "/clips/{clip_id}/subtitles/{subtitle_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+def delete_editor_clip_subtitle(
+    template_id: str,
+    clip_id: str,
+    subtitle_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """删除片段字幕"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    config = dict(clip.config) if clip.config else {}
+    subtitles = config.get("subtitles", [])
+    if not isinstance(subtitles, list):
+        subtitles = []
+
+    new_subtitles = [s for s in subtitles if s.get("id") != subtitle_id]
+    if len(new_subtitles) == len(subtitles):
+        raise HTTPException(status_code=404, detail="字幕不存在")
+
+    config["subtitles"] = new_subtitles
+    plan_svc.update_clip(clip_id, config=config)
+    return None
+
+
+@router.put("/clips/{clip_id}/subtitles", response_model=list[dict[str, Any]])
+def batch_update_editor_clip_subtitles(
+    template_id: str,
+    clip_id: str,
+    body: list[dict[str, Any]],
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> list[dict[str, Any]]:
+    """批量更新片段字幕（全量替换）"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    config = dict(clip.config) if clip.config else {}
+    config["subtitles"] = body
+    plan_svc.update_clip(clip_id, config=config)
+    return body
@@ -0,0 +1,61 @@
+"""时间线路由.
+
+端点：
+- GET /timeline       时间线场景数据
+"""
+
+from __future__ import annotations
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends
+
+from ._utils import _CLIP_TYPE_COLORS, _DEFAULT_COLOR, _clip_type_to_scene_label, _format_time
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import EditorTimelineResponse, EditorTimelineSceneResponse
+
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.get("/timeline", response_model=EditorTimelineResponse)
+def get_editor_timeline(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> EditorTimelineResponse:
+    """获取草稿的时间线场景数据"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+    clips = plan_svc.list_clips(plan_id=plan_id, skip=0, limit=200)
+    clips.sort(key=lambda c: c.order)
+
+    scenes = []
+    current_time = 0.0
+
+    for clip in clips:
+        start = current_time
+        end = start + clip.duration
+        color = _CLIP_TYPE_COLORS.get(clip.clip_type, _DEFAULT_COLOR)
+        scene_label = _clip_type_to_scene_label(clip.clip_type, clip.text_content)
+
+        scenes.append(
+            EditorTimelineSceneResponse(
+                scene=scene_label,
+                time=f"{_format_time(start)} - {_format_time(end)}",
+                duration=clip.duration,
+                color=color,
+                clip_id=clip.id,
+                clip_type=clip.clip_type,
+            )
+        )
+        current_time = end
+
+    total_duration = sum(s.duration for s in scenes) or plan.total_duration
+
+    return EditorTimelineResponse(
+        plan_id=plan_id,
+        total_duration=total_duration,
+        scenes=scenes,
+    )
@@ -0,0 +1,128 @@
+import React from "react"
+import {
+  PlayCircleOutlined,
+  CheckOutlined,
+  DeleteOutlined,
+  ExperimentOutlined,
+  LoadingOutlined,
+  CloseCircleOutlined,
+} from "@ant-design/icons"
+import { Popconfirm } from "antd"
+import type { AssetItem } from "@/pages/assets/types"
+import { thumbGradient } from "@/pages/assets/utils/asset"
+import { kindIcon } from "@/pages/assets/utils/kindIcon"
+import { StatusPill } from "./AssetSkeleton"
+
+/* ============================================================
+ * AssetCard — 素材卡片（网格视图）
+ * ============================================================ */
+export interface AssetCardProps {
+  asset: AssetItem
+  selected: boolean
+  diagnosing?: boolean
+  onToggle: () => void
+  onDiagnose: () => void
+  onPlay: () => void
+  onDelete: () => void
+}
+
+const AssetCard: React.FC<AssetCardProps> = ({
+  asset,
+  selected,
+  diagnosing,
+  onToggle,
+  onDiagnose,
+  onPlay,
+  onDelete,
+}) => (
+  <div className={`xx-asset-card${selected ? " xx-asset-card-selected" : ""}`} onClick={onToggle}>
+    {/* 缩略图区 */}
+    <div className="xx-asset-thumb" style={{ background: thumbGradient(asset.kind) }}>
+      {asset.thumbUrl ? (
+        <img src={asset.thumbUrl} alt={asset.name} />
+      ) : (
+        <span className="xx-asset-thumb-placeholder">
+          {asset.loading ? <LoadingOutlined /> : kindIcon(asset.kind)}
+        </span>
+      )}
+
+      {/* 处理中遮罩 */}
+      {asset.loading && (
+        <div className="xx-asset-thumb-overlay xx-asset-thumb-processing">
+          <LoadingOutlined />
+          <span>处理中</span>
+        </div>
+      )}
+
+      {/* 失败状态标识 */}
+      {asset.status === "bad" && asset.statusLabel === "处理失败" && (
+        <div className="xx-asset-thumb-overlay xx-asset-thumb-failed">
+          <CloseCircleOutlined />
+          <span>处理失败</span>
+        </div>
+      )}
+
+      {/* 视频/配音类显示播放按钮（处理中/失败不显示） */}
+      {asset.kind === "video" && !asset.loading && asset.status !== "bad" && (
+        <span
+          className="xx-asset-play"
+          onClick={(e) => {
+            e.stopPropagation()
+            onPlay()
+          }}
+        >
+          <PlayCircleOutlined />
+        </span>
+      )}
+
+      {/* 删除按钮 */}
+      <Popconfirm
+        title="确认删除"
+        description="删除后不可恢复，确定要删除这个素材吗？"
+        onConfirm={(e) => {
+          e?.stopPropagation()
+          onDelete()
+        }}
+        onCancel={(e) => e?.stopPropagation()}
+        okText="删除"
+        cancelText="取消"
+        okButtonProps={{ danger: true }}
+      >
+        <span className="xx-asset-delete" onClick={(e) => e.stopPropagation()}>
+          <DeleteOutlined />
+        </span>
+      </Popconfirm>
+
+      {/* 选中态勾选 */}
+      {selected && (
+        <span className="xx-asset-check">
+          <CheckOutlined />
+        </span>
+      )}
+    </div>
+
+    {/* 信息区 */}
+    <div className="xx-asset-info">
+      <p className="xx-asset-name" title={asset.name}>
+        {asset.name}
+      </p>
+      <div className="xx-asset-meta">
+        <StatusPill status={asset.status} label={asset.statusLabel} />
+        {asset.duration && <span>{asset.duration}</span>}
+      </div>
+      <button
+        className={`xx-asset-diagnose-btn${diagnosing ? " xx-asset-diagnose-btn-loading" : ""}`}
+        disabled={diagnosing || asset.loading || asset.status === "bad"}
+        onClick={(e) => {
+          e.stopPropagation()
+          onDiagnose()
+        }}
+      >
+        {diagnosing ? <LoadingOutlined /> : <ExperimentOutlined />}
+        {diagnosing ? "诊断中..." : "诊断"}
+      </button>
+    </div>
+  </div>
+)
+
+export default AssetCard
@@ -0,0 +1,62 @@
+import React from "react"
+import { SearchOutlined } from "@ant-design/icons"
+import { Button, Input, Select } from "@/components/ui"
+import { TYPE_FILTER_OPTIONS, TIME_FILTER_OPTIONS } from "@/pages/assets/constants"
+
+/* ============================================================
+ * AssetFilterBar — 筛选栏（搜索/类型/时间 + 全选/计数）
+ * ============================================================ */
+export interface AssetFilterBarProps {
+  searchText: string
+  onSearchChange: (value: string) => void
+  filterType: string
+  onFilterTypeChange: (value: string) => void
+  filterTime: string
+  onFilterTimeChange: (value: string) => void
+  onSelectAll: () => void
+  totalCount: number
+}
+
+const AssetFilterBar: React.FC<AssetFilterBarProps> = ({
+  searchText,
+  onSearchChange,
+  filterType,
+  onFilterTypeChange,
+  filterTime,
+  onFilterTimeChange,
+  onSelectAll,
+  totalCount,
+}) => (
+  <div className="xx-assets-filters">
+    <div className="xx-assets-filters-left">
+      <Input
+        placeholder="搜索素材名称..."
+        prefix={<SearchOutlined />}
+        value={searchText}
+        onChange={(e) => onSearchChange(e.target.value)}
+        allowClear
+        style={{ width: 220 }}
+      />
+      <Select
+        value={filterType}
+        onChange={onFilterTypeChange}
+        style={{ width: 120 }}
+        options={TYPE_FILTER_OPTIONS}
+      />
+      <Select
+        value={filterTime}
+        onChange={onFilterTimeChange}
+        style={{ width: 120 }}
+        options={TIME_FILTER_OPTIONS}
+      />
+    </div>
+    <div className="xx-assets-filters-right">
+      <Button buttonType="ghost" buttonSize="sm" onClick={onSelectAll}>
+        全选
+      </Button>
+      <span className="xx-assets-filter-count">共 {totalCount} 个素材</span>
+    </div>
+  </div>
+)
+
+export default AssetFilterBar
@@ -0,0 +1,36 @@
+import React from "react"
+import type { StatusType } from "@/pages/assets/types"
+
+/* ============================================================
+ * StatusPill — 状态标签
+ * ============================================================ */
+export interface StatusPillProps {
+  status: StatusType
+  label: string
+}
+
+export const StatusPill: React.FC<StatusPillProps> = ({ status, label }) => (
+  <span className={`xx-status-pill xx-status-pill-${status}`}>{label}</span>
+)
+
+/* ============================================================
+ * SkeletonCard — 骨架屏卡片（素材列表加载时占位）
+ * ============================================================ */
+export const SkeletonCard: React.FC = () => (
+  <div className="xx-asset-card xx-asset-skeleton">
+    <div className="xx-asset-thumb xx-skeleton-pulse" />
+    <div className="xx-asset-info">
+      <div className="xx-skeleton-line xx-skeleton-pulse" style={{ width: "70%" }} />
+      <div className="xx-skeleton-line xx-skeleton-pulse" style={{ width: "40%", marginTop: 8 }} />
+      <div
+        className="xx-skeleton-line xx-skeleton-pulse"
+        style={{
+          width: "100%",
+          height: 28,
+          marginTop: 8,
+          borderRadius: "var(--radius-xs)",
+        }}
+      />
+    </div>
+  </div>
+)
@@ -0,0 +1,49 @@
+import React from "react"
+import { Modal as AntModal, Select as AntSelect } from "antd"
+import { CATEGORY_OPTIONS } from "@/pages/assets/constants"
+
+/* ============================================================
+ * BatchClassifyModal — 批量改分类弹窗
+ * ============================================================ */
+export interface BatchClassifyModalProps {
+  open: boolean
+  selectedCount: number
+  onCancel: () => void
+  onOk: () => void
+  category: string
+  onCategoryChange: (value: string) => void
+  confirmLoading?: boolean
+}
+
+const BatchClassifyModal: React.FC<BatchClassifyModalProps> = ({
+  open,
+  selectedCount,
+  onCancel,
+  onOk,
+  category,
+  onCategoryChange,
+  confirmLoading,
+}) => (
+  <AntModal
+    title={`批量改分类（${selectedCount} 个素材）`}
+    open={open}
+    onCancel={onCancel}
+    onOk={onOk}
+    confirmLoading={confirmLoading}
+    okText="确认修改"
+    cancelText="取消"
+  >
+    <div className="xx-batch-classify-modal">
+      <p className="xx-batch-classify-hint">将选中的 {selectedCount} 个素材统一修改为以下分类：</p>
+      <AntSelect
+        value={category || undefined}
+        onChange={(v) => onCategoryChange(v)}
+        placeholder="请选择分类"
+        style={{ width: "100%" }}
+        options={CATEGORY_OPTIONS}
+      />
+    </div>
+  </AntModal>
+)
+
+export default BatchClassifyModal
@@ -0,0 +1,67 @@
+import React from "react"
+import { Modal as AntModal, Tag, Radio } from "antd"
+
+/* ============================================================
+ * BatchMarkModal — 批量智能标记弹窗
+ * ============================================================ */
+export type SmartViewType = "recommended" | "caution" | "high_risk"
+
+export interface BatchMarkModalProps {
+  open: boolean
+  selectedCount: number
+  onCancel: () => void
+  onOk: () => void
+  smartView: SmartViewType
+  onSmartViewChange: (value: SmartViewType) => void
+  confirmLoading?: boolean
+}
+
+const BatchMarkModal: React.FC<BatchMarkModalProps> = ({
+  open,
+  selectedCount,
+  onCancel,
+  onOk,
+  smartView,
+  onSmartViewChange,
+  confirmLoading,
+}) => (
+  <AntModal
+    title={`批量智能标记（${selectedCount} 个素材）`}
+    open={open}
+    onCancel={onCancel}
+    onOk={onOk}
+    confirmLoading={confirmLoading}
+    okText="确认标记"
+    cancelText="取消"
+  >
+    <div className="xx-batch-mark-modal">
+      <p className="xx-batch-mark-hint">将选中的 {selectedCount} 个素材标记为：</p>
+      <Radio.Group
+        value={smartView}
+        onChange={(e) => onSmartViewChange(e.target.value)}
+        className="xx-batch-mark-options"
+      >
+        <div className="xx-batch-mark-option">
+          <Radio value="recommended">
+            <Tag color="success">推荐</Tag>
+            <span className="xx-batch-mark-desc">质量优良，可直接用于生产</span>
+          </Radio>
+        </div>
+        <div className="xx-batch-mark-option">
+          <Radio value="caution">
+            <Tag color="warning">慎用</Tag>
+            <span className="xx-batch-mark-desc">存在一定问题，需人工审核后再使用</span>
+          </Radio>
+        </div>
+        <div className="xx-batch-mark-option">
+          <Radio value="high_risk">
+            <Tag color="error">高风险</Tag>
+            <span className="xx-batch-mark-desc">存在严重问题，不建议使用</span>
+          </Radio>
+        </div>
+      </Radio.Group>
+    </div>
+  </AntModal>
+)
+
+export default BatchMarkModal
@@ -0,0 +1,58 @@
+import React from "react"
+import {
+  TagsOutlined,
+  FolderOutlined,
+  ThunderboltOutlined,
+  DeleteOutlined,
+} from "@ant-design/icons"
+import { Popconfirm } from "antd"
+import { Button } from "@/components/ui"
+
+/* ============================================================
+ * BatchOperationBar — 批量操作栏
+ * ============================================================ */
+export interface BatchOperationBarProps {
+  selectedCount: number
+  onDeselectAll: () => void
+  onTagClick: () => void
+  onClassifyClick: () => void
+  onMarkClick: () => void
+  onBatchDelete: () => void
+}
+
+const BatchOperationBar: React.FC<BatchOperationBarProps> = ({
+  selectedCount,
+  onDeselectAll,
+  onTagClick,
+  onClassifyClick,
+  onMarkClick,
+  onBatchDelete,
+}) => (
+  <div className="xx-assets-batch-bar">
+    <span className="xx-assets-batch-count">已选 {selectedCount} 项</span>
+    <Button buttonType="ghost" buttonSize="sm" onClick={onDeselectAll}>
+      取消选择
+    </Button>
+    <Button buttonType="ghost" buttonSize="sm" icon={<TagsOutlined />} onClick={onTagClick}>
+      打标签
+    </Button>
+    <Button buttonType="ghost" buttonSize="sm" icon={<FolderOutlined />} onClick={onClassifyClick}>
+      改分类
+    </Button>
+    <Button buttonType="ghost" buttonSize="sm" icon={<ThunderboltOutlined />} onClick={onMarkClick}>
+      智能标记
+    </Button>
+    <Popconfirm
+      title={`确定删除 ${selectedCount} 个素材？`}
+      onConfirm={onBatchDelete}
+      okText="删除"
+      cancelText="取消"
+    >
+      <Button buttonType="danger" buttonSize="sm" icon={<DeleteOutlined />}>
+        批量删除
+      </Button>
+    </Popconfirm>
+  </div>
+)
+
+export default BatchOperationBar
@@ -0,0 +1,81 @@
+import React from "react"
+import { Modal as AntModal, Tag, Radio, Input as AntInput } from "antd"
+import { ExclamationCircleOutlined } from "@ant-design/icons"
+
+/* ============================================================
+ * BatchTagModal — 批量打标签弹窗
+ * ============================================================ */
+export interface BatchTagModalProps {
+  open: boolean
+  selectedCount: number
+  onCancel: () => void
+  onOk: () => void
+  tags: string[]
+  onTagInputChange: (value: string) => void
+  onTagInputKeyDown: (e: React.KeyboardEvent) => void
+  onRemoveTag: (tag: string) => void
+  tagInput: string
+  tagMode: "add" | "replace"
+  onTagModeChange: (mode: "add" | "replace") => void
+  confirmLoading?: boolean
+}
+
+const BatchTagModal: React.FC<BatchTagModalProps> = ({
+  open,
+  selectedCount,
+  onCancel,
+  onOk,
+  tags,
+  onTagInputChange,
+  onTagInputKeyDown,
+  onRemoveTag,
+  tagInput,
+  tagMode,
+  onTagModeChange,
+  confirmLoading,
+}) => (
+  <AntModal
+    title={`批量打标签（${selectedCount} 个素材）`}
+    open={open}
+    onCancel={onCancel}
+    onOk={onOk}
+    confirmLoading={confirmLoading}
+    okText="确认打标签"
+    cancelText="取消"
+  >
+    <div className="xx-batch-tag-modal">
+      <div className="xx-batch-tag-mode">
+        <span className="xx-batch-tag-mode-label">模式：</span>
+        <Radio.Group value={tagMode} onChange={(e) => onTagModeChange(e.target.value)}>
+          <Radio value="add">追加标签</Radio>
+          <Radio value="replace">替换全部标签</Radio>
+        </Radio.Group>
+      </div>
+      <div className="xx-batch-tag-input-row">
+        <AntInput
+          placeholder="输入标签后按 Enter 添加"
+          value={tagInput}
+          onChange={(e) => onTagInputChange(e.target.value)}
+          onKeyDown={onTagInputKeyDown}
+          style={{ flex: 1 }}
+        />
+      </div>
+      {tags.length > 0 && (
+        <div className="xx-batch-tag-list">
+          {tags.map((tag) => (
+            <Tag key={tag} closable onClose={() => onRemoveTag(tag)} color="blue">
+              {tag}
+            </Tag>
+          ))}
+        </div>
+      )}
+      {tagMode === "replace" && tags.length > 0 && (
+        <div className="xx-batch-tag-warning">
+          <ExclamationCircleOutlined /> 替换模式将清除素材原有全部标签
+        </div>
+      )}
+    </div>
+  </AntModal>
+)
+
+export default BatchTagModal
@@ -0,0 +1,64 @@
+import React from "react"
+import { Modal as AntModal } from "antd"
+import { Input, Select } from "@/components/ui"
+import type { AssetKind } from "@/pages/assets/types"
+import { LIBRARY_KIND_OPTIONS } from "@/pages/assets/constants"
+
+/* ============================================================
+ * CreateLibraryModal — 新建视频库弹窗
+ * ============================================================ */
+export interface CreateLibraryModalProps {
+  open: boolean
+  onCancel: () => void
+  onOk: () => void
+  name: string
+  onNameChange: (value: string) => void
+  kind: AssetKind
+  onKindChange: (value: AssetKind) => void
+  confirmLoading?: boolean
+}
+
+const CreateLibraryModal: React.FC<CreateLibraryModalProps> = ({
+  open,
+  onCancel,
+  onOk,
+  name,
+  onNameChange,
+  kind,
+  onKindChange,
+  confirmLoading,
+}) => (
+  <AntModal
+    title="新建视频库"
+    open={open}
+    onCancel={onCancel}
+    onOk={onOk}
+    okText="创建"
+    cancelText="取消"
+    destroyOnClose
+    confirmLoading={confirmLoading}
+  >
+    <div className="xx-asset-form-body">
+      <div>
+        <div className="xx-asset-form-label">名称</div>
+        <Input
+          placeholder="请输入视频库名称"
+          value={name}
+          onChange={(e) => onNameChange(e.target.value)}
+          maxLength={50}
+        />
+      </div>
+      <div>
+        <div className="xx-asset-form-label">类型</div>
+        <Select
+          value={kind}
+          onChange={(v) => onKindChange(v)}
+          style={{ width: "100%" }}
+          options={LIBRARY_KIND_OPTIONS}
+        />
+      </div>
+    </div>
+  </AntModal>
+)
+
+export default CreateLibraryModal
@@ -0,0 +1,70 @@
+import React from "react"
+import { PlusOutlined, DeleteOutlined } from "@ant-design/icons"
+import { Popconfirm } from "antd"
+import type { LibraryItem } from "@/pages/assets/types"
+import { kindLabel } from "@/pages/assets/utils/asset"
+import { kindIcon } from "@/pages/assets/utils/kindIcon"
+
+/* ============================================================
+ * LibrarySidebar — 左侧素材库列表
+ * ============================================================ */
+export interface LibrarySidebarProps {
+  libraries: LibraryItem[]
+  activeLibId: string
+  onSelect: (id: string) => void
+  onDelete: (id: string) => void
+  onCreateClick: () => void
+}
+
+const LibrarySidebar: React.FC<LibrarySidebarProps> = ({
+  libraries,
+  activeLibId,
+  onSelect,
+  onDelete,
+  onCreateClick,
+}) => (
+  <div className="xx-asset-library-list">
+    {libraries.map((lib) => (
+      <div
+        key={lib.id}
+        className={`xx-asset-library-item${lib.id === activeLibId ? " active" : ""}`}
+        onClick={() => onSelect(lib.id)}
+      >
+        <div className="xx-asset-library-header">
+          <h4>
+            {kindIcon(lib.kind)} {lib.name}
+          </h4>
+          <Popconfirm
+            title={`确定删除视频库 "${lib.name}"？`}
+            onConfirm={(e) => {
+              e?.stopPropagation()
+              onDelete(lib.id)
+            }}
+            onCancel={(e) => e?.stopPropagation()}
+            okText="删除"
+            cancelText="取消"
+          >
+            <button
+              className="xx-asset-library-delete"
+              onClick={(e) => e.stopPropagation()}
+              title="删除视频库"
+            >
+              <DeleteOutlined />
+            </button>
+          </Popconfirm>
+        </div>
+        <span>
+          {kindLabel(lib.kind)} · {lib.count} 个素材
+        </span>
+      </div>
+    ))}
+
+    {/* 新建视频库 */}
+    <div className="xx-asset-library-add" onClick={onCreateClick}>
+      <PlusOutlined />
+      新建视频库
+    </div>
+  </div>
+)
+
+export default LibrarySidebar
@@ -0,0 +1,34 @@
+import React from "react"
+import { Modal as AntModal } from "antd"
+import type { AssetItem } from "@/pages/assets/types"
+
+/* ============================================================
+ * PlayModal — 视频/音频播放弹窗
+ * ============================================================ */
+export interface PlayModalProps {
+  open: boolean
+  asset: AssetItem | null
+  onClose: () => void
+}
+
+const PlayModal: React.FC<PlayModalProps> = ({ open, asset, onClose }) => (
+  <AntModal
+    title={asset?.name ?? "播放"}
+    open={open}
+    onCancel={onClose}
+    footer={null}
+    width={640}
+    destroyOnClose
+  >
+    {asset?.fileUrl ? (
+      <video src={asset.fileUrl} controls autoPlay className="xx-asset-video-player" />
+    ) : (
+      <div className="xx-asset-empty-fallback">
+        <p>暂无可播放的文件地址</p>
+        <p className="xx-asset-empty-fallback-id">素材 ID: {asset?.id}</p>
+      </div>
+    )}
+  </AntModal>
+)
+
+export default PlayModal
@@ -0,0 +1,70 @@
+import React from "react"
+import { Drawer } from "antd"
+import { CheckCircleOutlined, CloseCircleOutlined } from "@ant-design/icons"
+import type { BatchOperationResult } from "@/api/assets"
+
+/* ============================================================
+ * ResultDrawer — 操作结果抽屉
+ * ============================================================ */
+export interface ResultDrawerProps {
+  open: boolean
+  title: string
+  result: BatchOperationResult | null
+  onClose: () => void
+}
+
+const ResultDrawer: React.FC<ResultDrawerProps> = ({ open, title, result, onClose }) => (
+  <Drawer title={`${title} — 操作结果`} open={open} onClose={onClose} width={420}>
+    {result && (
+      <div className="xx-batch-result">
+        <div className="xx-batch-result-summary">
+          <div className="xx-batch-result-stat">
+            <span className="xx-batch-result-total">总计 {result.total} 个</span>
+          </div>
+          <div className="xx-batch-result-stat success">
+            <CheckCircleOutlined />
+            <span>成功 {result.success_count} 个</span>
+          </div>
+          {result.failure_count > 0 && (
+            <div className="xx-batch-result-stat fail">
+              <CloseCircleOutlined />
+              <span>失败 {result.failure_count} 个</span>
+            </div>
+          )}
+        </div>
+
+        {(result?.succeeded?.length ?? 0) > 0 && (
+          <div className="xx-batch-result-section">
+            <h4 className="xx-batch-result-section-title success">
+              <CheckCircleOutlined /> 成功列表
+            </h4>
+            <div className="xx-batch-result-ids">
+              {result?.succeeded?.map((id) => (
+                <div key={id} className="xx-batch-result-id">
+                  {id}
+                </div>
+              ))}
+            </div>
+          </div>
+        )}
+
+        {(result?.failed?.length ?? 0) > 0 && (
+          <div className="xx-batch-result-section">
+            <h4 className="xx-batch-result-section-title fail">
+              <CloseCircleOutlined /> 失败列表
+            </h4>
+            <div className="xx-batch-result-ids">
+              {result?.failed?.map((id) => (
+                <div key={id} className="xx-batch-result-id fail">
+                  {id}
+                </div>
+              ))}
+            </div>
+          </div>
+        )}
+      </div>
+    )}
+  </Drawer>
+)
+
+export default ResultDrawer
@@ -0,0 +1,56 @@
+import React from "react"
+import { Modal as AntModal } from "antd"
+
+/* ============================================================
+ * UploadProgressModal — 上传进度弹窗（圆形动画 + 百分比）
+ * ============================================================ */
+export interface UploadProgressModalProps {
+  open: boolean
+  progress: number
+}
+
+const UploadProgressModal: React.FC<UploadProgressModalProps> = ({ open, progress }) => (
+  <AntModal
+    open={open}
+    footer={null}
+    closable={false}
+    centered
+    width={260}
+    maskClosable={false}
+    className="xx-upload-progress-modal"
+  >
+    <div className="xx-upload-progress-body">
+      <svg className="xx-upload-progress-ring" viewBox="0 0 120 120" width={120} height={120}>
+        {/* 背景圆环 */}
+        <circle
+          cx="60"
+          cy="60"
+          r="52"
+          fill="none"
+          stroke="var(--border-primary, #e5e7eb)"
+          strokeWidth="8"
+        />
+        {/* 进度圆弧 */}
+        <circle
+          cx="60"
+          cy="60"
+          r="52"
+          fill="none"
+          stroke="var(--primary-color, #6366f1)"
+          strokeWidth="8"
+          strokeLinecap="round"
+          strokeDasharray={`${2 * Math.PI * 52}`}
+          strokeDashoffset={`${2 * Math.PI * 52 * (1 - progress / 100)}`}
+          transform="rotate(-90 60 60)"
+          style={{ transition: "stroke-dashoffset 0.3s ease" }}
+        />
+      </svg>
+      <div className="xx-upload-progress-text">
+        <span className="xx-upload-progress-pct">{progress}%</span>
+        <span className="xx-upload-progress-label">上传中…</span>
+      </div>
+    </div>
+  </AntModal>
+)
+
+export default UploadProgressModal
@@ -0,0 +1,66 @@
+/**
+ * 素材库常量
+ */
+import type { AssetKind } from "./types"
+
+/** 文件大小限制 */
+export const MAX_FILE_SIZE = 2048 * 1024 * 1024
+export const LARGE_FILE_THRESHOLD = 100 * 1024 * 1024
+
+/** 素材类型标签 */
+export const KIND_LABELS: Record<AssetKind, string> = {
+  video: "视频",
+  image: "图片",
+  voice: "配音",
+}
+
+/** 类型筛选选项 */
+export const TYPE_FILTER_OPTIONS: { value: string; label: string }[] = [
+  { value: "all", label: "全部类型" },
+  { value: "video", label: "视频" },
+  { value: "image", label: "图片" },
+]
+
+/** 时间筛选选项 */
+export const TIME_FILTER_OPTIONS: { value: string; label: string }[] = [
+  { value: "all", label: "全部时间" },
+  { value: "today", label: "今天" },
+  { value: "week", label: "近一周" },
+  { value: "month", label: "近一月" },
+]
+
+/** 新建库类型选项（当前仅支持视频和图片） */
+export const LIBRARY_KIND_OPTIONS: { value: AssetKind; label: string }[] = [
+  { value: "video", label: "视频" },
+  { value: "image", label: "图片" },
+]
+
+/** 分类选项 */
+export const CATEGORY_OPTIONS: { value: string; label: string }[] = [
+  { value: "person", label: "人物" },
+  { value: "scenic", label: "风景" },
+  { value: "product", label: "产品" },
+  { value: "food", label: "美食" },
+  { value: "animal", label: "动物" },
+  { value: "architecture", label: "建筑" },
+  { value: "other", label: "其他" },
+]
+
+/** 智能标记视图 */
+export const SMART_VIEW_OPTIONS: {
+  value: "recommended" | "caution" | "high_risk"
+  label: string
+  color: string
+}[] = [
+  { value: "recommended", label: "推荐", color: "success" },
+  { value: "caution", label: "慎用", color: "warning" },
+  { value: "high_risk", label: "高风险", color: "error" },
+]
+
+/** 状态配置 */
+export const STATUS_CONFIG: Record<string, { label: string; className: string }> = {
+  ok: { label: "合格", className: "xx-status-pill xx-status-pill-ok" },
+  warn: { label: "待优化", className: "xx-status-pill xx-status-pill-warn" },
+  bad: { label: "不合格", className: "xx-status-pill xx-status-pill-bad" },
+  info: { label: "待诊断", className: "xx-status-pill xx-status-pill-info" },
+}
@@ -0,0 +1,301 @@
+import { useState, useCallback } from "react"
+import { useQueryClient } from "@tanstack/react-query"
+import { message } from "antd"
+import {
+  deleteAsset,
+  getAssetDiagnosis,
+  batchDeleteAssets,
+  batchTagAssets,
+  batchClassifyAssets,
+  batchMarkAssets,
+  type BatchOperationResult,
+} from "@/api/assets"
+import type { AssetItem } from "../types"
+import type { SmartViewType } from "../components/BatchMarkModal"
+
+/**
+ * 素材操作 Hook
+ * 封装素材的诊断、删除、批量打标签、批量改分类、批量智能标记等操作，
+ * 以及相关弹窗和结果展示的状态管理
+ */
+interface UseAssetOperationsProps {
+  selectedIds: Set<string>
+  setSelectedIds: (ids: Set<string>) => void
+}
+
+export function useAssetOperations({ selectedIds, setSelectedIds }: UseAssetOperationsProps) {
+  const queryClient = useQueryClient()
+
+  /* ── 诊断状态 ── */
+  const [diagnosingId, setDiagnosingId] = useState<string | null>(null)
+
+  /* ── 批量操作弹窗状态 ── */
+  const [tagModalOpen, setTagModalOpen] = useState(false)
+  const [classifyModalOpen, setClassifyModalOpen] = useState(false)
+  const [markModalOpen, setMarkModalOpen] = useState(false)
+  const [resultDrawerOpen, setResultDrawerOpen] = useState(false)
+
+  /* ── 批量打标签表单 ── */
+  const [batchTagInput, setBatchTagInput] = useState("")
+  const [batchTags, setBatchTags] = useState<string[]>([])
+  const [tagMode, setTagMode] = useState<"add" | "replace">("add")
+
+  /* ── 批量改分类表单 ── */
+  const [batchCategory, setBatchCategory] = useState("")
+
+  /* ── 批量智能标记表单 ── */
+  const [batchSmartView, setBatchSmartView] = useState<SmartViewType>("recommended")
+
+  /* ── 操作结果 ── */
+  const [operationResult, setOperationResult] = useState<BatchOperationResult | null>(null)
+  const [operationTitle, setOperationTitle] = useState("")
+
+  /* ── 批量操作 loading ── */
+  const [batchLoading, setBatchLoading] = useState(false)
+
+  /* ── 刷新数据辅助函数 ── */
+  const invalidateAssets = useCallback(() => {
+    queryClient.invalidateQueries({ queryKey: ["assets"] })
+    queryClient.invalidateQueries({ queryKey: ["asset-libraries"] })
+  }, [queryClient])
+
+  /* ── 诊断 ── */
+  const handleDiagnose = useCallback(
+    async (asset: AssetItem) => {
+      setDiagnosingId(asset.id)
+      try {
+        const result = await getAssetDiagnosis(asset.id)
+        const score = result.readiness_score ?? "-"
+        message.success(`"${asset.name}" 诊断完成，就绪分：${score}`)
+        queryClient.invalidateQueries({ queryKey: ["assets"] })
+      } catch {
+        message.error(`"${asset.name}" 诊断失败`)
+      } finally {
+        setDiagnosingId(null)
+      }
+    },
+    [queryClient],
+  )
+
+  /* ── 单个素材删除 ── */
+  const handleSingleDelete = useCallback(
+    async (assetId: string) => {
+      try {
+        await deleteAsset(assetId)
+        invalidateAssets()
+        // 从选中集合中移除
+        setSelectedIds(
+          (() => {
+            const next = new Set(selectedIds)
+            next.delete(assetId)
+            return next
+          })(),
+        )
+        message.success("素材已删除")
+      } catch {
+        message.error("删除失败，请重试")
+      }
+    },
+    [invalidateAssets, selectedIds, setSelectedIds],
+  )
+
+  /* ── 显示操作结果 ── */
+  const showOperationResult = useCallback(
+    (result: BatchOperationResult, title: string, clearSelection = true) => {
+      setOperationResult(result)
+      setOperationTitle(title)
+      setResultDrawerOpen(true)
+      if (clearSelection) setSelectedIds(new Set())
+    },
+    [setSelectedIds],
+  )
+
+  /* ── 批量删除 ── */
+  const handleBatchDelete = useCallback(async () => {
+    const ids = Array.from(selectedIds)
+    setBatchLoading(true)
+    try {
+      const result = await batchDeleteAssets(ids)
+      invalidateAssets()
+      showOperationResult(result, "批量删除")
+      if (result.failure_count === 0) {
+        message.success(`成功删除 ${result.success_count} 个素材`)
+      } else {
+        message.warning(
+          `删除完成：成功 ${result.success_count} 个，失败 ${result.failure_count} 个`,
+        )
+      }
+    } catch {
+      message.error("批量删除失败，请重试")
+    } finally {
+      setBatchLoading(false)
+    }
+  }, [selectedIds, invalidateAssets, showOperationResult])
+
+  /* ── 批量打标签 ── */
+  const handleBatchTag = useCallback(async () => {
+    if (batchTags.length === 0) {
+      message.warning("请至少输入一个标签")
+      return
+    }
+    const ids = Array.from(selectedIds)
+    setBatchLoading(true)
+    try {
+      const result = await batchTagAssets({
+        asset_ids: ids,
+        tags: batchTags,
+        mode: tagMode,
+      })
+      queryClient.invalidateQueries({ queryKey: ["assets"] })
+      showOperationResult(result, "批量打标签")
+      setTagModalOpen(false)
+      setBatchTags([])
+      setBatchTagInput("")
+      setTagMode("add")
+      if (result.failure_count === 0) {
+        message.success(`成功为 ${result.success_count} 个素材打标签`)
+      } else {
+        message.warning(
+          `打标签完成：成功 ${result.success_count} 个，失败 ${result.failure_count} 个`,
+        )
+      }
+    } catch {
+      message.error("批量打标签失败，请重试")
+    } finally {
+      setBatchLoading(false)
+    }
+  }, [batchTags, selectedIds, tagMode, queryClient, showOperationResult])
+
+  /* ── 标签输入处理 ── */
+  const handleTagInputKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Enter" && batchTagInput.trim()) {
+        e.preventDefault()
+        const tag = batchTagInput.trim()
+        if (!batchTags.includes(tag)) {
+          setBatchTags([...batchTags, tag])
+        }
+        setBatchTagInput("")
+      }
+    },
+    [batchTagInput, batchTags],
+  )
+
+  const removeBatchTag = useCallback(
+    (tag: string) => {
+      setBatchTags(batchTags.filter((t) => t !== tag))
+    },
+    [batchTags],
+  )
+
+  /* ── 批量改分类 ── */
+  const handleBatchClassify = useCallback(async () => {
+    if (!batchCategory) {
+      message.warning("请选择分类")
+      return
+    }
+    const ids = Array.from(selectedIds)
+    setBatchLoading(true)
+    try {
+      const result = await batchClassifyAssets({
+        asset_ids: ids,
+        category: batchCategory,
+      })
+      queryClient.invalidateQueries({ queryKey: ["assets"] })
+      showOperationResult(result, "批量改分类")
+      setClassifyModalOpen(false)
+      setBatchCategory("")
+      if (result.failure_count === 0) {
+        message.success(`成功将 ${result.success_count} 个素材改为「${batchCategory}」`)
+      } else {
+        message.warning(
+          `改分类完成：成功 ${result.success_count} 个，失败 ${result.failure_count} 个`,
+        )
+      }
+    } catch {
+      message.error("批量改分类失败，请重试")
+    } finally {
+      setBatchLoading(false)
+    }
+  }, [batchCategory, selectedIds, queryClient, showOperationResult])
+
+  /* ── 批量智能标记 ── */
+  const handleBatchMark = useCallback(async () => {
+    const ids = Array.from(selectedIds)
+    setBatchLoading(true)
+    try {
+      const result = await batchMarkAssets({
+        asset_ids: ids,
+        smart_view: batchSmartView,
+      })
+      queryClient.invalidateQueries({ queryKey: ["assets"] })
+      showOperationResult(result, "批量智能标记")
+      setMarkModalOpen(false)
+      const labelMap: Record<SmartViewType, string> = {
+        recommended: "推荐",
+        caution: "慎用",
+        high_risk: "高风险",
+      }
+      if (result.failure_count === 0) {
+        message.success(
+          `成功将 ${result.success_count} 个素材标记为「${labelMap[batchSmartView]}」`,
+        )
+      } else {
+        message.warning(
+          `智能标记完成：成功 ${result.success_count} 个，失败 ${result.failure_count} 个`,
+        )
+      }
+    } catch {
+      message.error("批量智能标记失败，请重试")
+    } finally {
+      setBatchLoading(false)
+    }
+  }, [batchSmartView, selectedIds, queryClient, showOperationResult])
+
+  /* ── 关闭结果 Drawer ── */
+  const handleResultDrawerClose = useCallback(() => {
+    setResultDrawerOpen(false)
+    setOperationResult(null)
+  }, [])
+
+  return {
+    // 诊断
+    diagnosingId,
+    handleDiagnose,
+    // 单个操作
+    handleSingleDelete,
+    // 批量操作 loading
+    batchLoading,
+    // 批量打标签
+    tagModalOpen,
+    setTagModalOpen,
+    batchTagInput,
+    setBatchTagInput,
+    batchTags,
+    setBatchTags,
+    tagMode,
+    setTagMode,
+    handleBatchTag,
+    handleTagInputKeyDown,
+    removeBatchTag,
+    // 批量改分类
+    classifyModalOpen,
+    setClassifyModalOpen,
+    batchCategory,
+    setBatchCategory,
+    handleBatchClassify,
+    // 批量智能标记
+    markModalOpen,
+    setMarkModalOpen,
+    batchSmartView,
+    setBatchSmartView,
+    handleBatchMark,
+    // 批量删除
+    handleBatchDelete,
+    // 操作结果
+    resultDrawerOpen,
+    operationResult,
+    operationTitle,
+    handleResultDrawerClose,
+  }
+}
@@ -0,0 +1,40 @@
+import { useState, useCallback } from "react"
+import type { AssetItem } from "../types"
+
+/**
+ * 素材选中态管理 Hook
+ * 封装单选、全选、取消全选等选中逻辑
+ */
+interface UseAssetSelectionProps {
+  filteredAssets: AssetItem[]
+}
+
+export function useAssetSelection({ filteredAssets }: UseAssetSelectionProps) {
+  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set())
+
+  const toggleSelect = useCallback((id: string) => {
+    setSelectedIds((prev) => {
+      const next = new Set(prev)
+      if (next.has(id)) next.delete(id)
+      else next.add(id)
+      return next
+    })
+  }, [])
+
+  const selectAll = useCallback(() => {
+    setSelectedIds(new Set(filteredAssets.map((a) => a.id)))
+  }, [filteredAssets])
+
+  const deselectAll = useCallback(() => {
+    setSelectedIds(new Set())
+  }, [])
+
+  return {
+    selectedIds,
+    setSelectedIds,
+    toggleSelect,
+    selectAll,
+    deselectAll,
+    selectedCount: selectedIds.size,
+  }
+}
@@ -0,0 +1,65 @@
+import { useState, useCallback } from "react"
+import { useQueryClient } from "@tanstack/react-query"
+import { message } from "antd"
+import { uploadAssetDirect } from "@/api/assets"
+import { MAX_FILE_SIZE, LARGE_FILE_THRESHOLD } from "../constants"
+
+/**
+ * 素材上传 Hook
+ * 封装上传状态、进度管理和上传逻辑
+ */
+interface UseAssetUploadProps {
+  effectiveLibId: string
+}
+
+export function useAssetUpload({ effectiveLibId }: UseAssetUploadProps) {
+  const queryClient = useQueryClient()
+
+  const [uploading, setUploading] = useState(false)
+  const [uploadProgress, setUploadProgress] = useState(0)
+
+  const handleUpload = useCallback(
+    async (file: File) => {
+      if (file.size > MAX_FILE_SIZE) {
+        message.error(`文件 "${file.name}" 超过 2GB 限制`)
+        return
+      }
+      if (!effectiveLibId) {
+        message.warning("请先选择或创建一个视频库")
+        return
+      }
+
+      setUploading(true)
+      setUploadProgress(0)
+      try {
+        if (file.size > LARGE_FILE_THRESHOLD) {
+          message.info(`大文件 "${file.name}" 将使用直传上传`)
+        }
+        await uploadAssetDirect({
+          file,
+          library_id: effectiveLibId,
+          onProgress: (pct) => setUploadProgress(pct),
+        })
+        message.success(`"${file.name}" 上传成功`)
+        queryClient.invalidateQueries({ queryKey: ["assets"] })
+        queryClient.invalidateQueries({ queryKey: ["asset-libraries"] })
+      } catch (err: unknown) {
+        const detail = err instanceof Error ? err.message : ""
+        console.error("[handleUpload] 上传失败:", err)
+        message.error(`"${file.name}" 上传失败${detail ? `：${detail}` : ""}`)
+        // 错误时延迟关闭弹窗，让用户能看到错误提示
+        await new Promise((r) => setTimeout(r, 1500))
+      } finally {
+        setUploading(false)
+        setUploadProgress(0)
+      }
+    },
+    [effectiveLibId, queryClient],
+  )
+
+  return {
+    uploading,
+    uploadProgress,
+    handleUpload,
+  }
+}
@@ -0,0 +1,118 @@
+import { useState, useMemo } from "react"
+import { useQuery } from "@tanstack/react-query"
+import {
+  getAssetLibraries,
+  getAssets,
+  type AssetLibraryItem,
+  type AssetItem as ApiAssetItem,
+} from "@/api/assets"
+import { mapLibrary, mapAsset, type AssetItem, type LibraryItem } from "../types"
+
+/**
+ * 素材库数据 Hook
+ * 封装视频库列表、素材列表的数据查询，以及筛选、搜索状态管理
+ */
+export function useAssetsData() {
+  /* ── 视频库列表查询 ── */
+  const { data: apiLibraries = [], isLoading: libLoading } = useQuery<AssetLibraryItem[], Error>({
+    queryKey: ["asset-libraries"],
+    queryFn: getAssetLibraries,
+    staleTime: 60_000,
+  })
+
+  const libraries: LibraryItem[] = useMemo(
+    () =>
+      (Array.isArray(apiLibraries) ? apiLibraries : [])
+        .map(mapLibrary)
+        .filter((lib) => lib.kind === "video"),
+    [apiLibraries],
+  )
+
+  /* ── 当前选中的视频库 ── */
+  const [activeLibId, setActiveLibId] = useState<string>("")
+
+  // 当库列表加载完成后，自动选中第一个
+  const effectiveLibId = activeLibId || libraries[0]?.id || ""
+
+  /* ── 当前库的素材列表查询 ── */
+  const {
+    data: apiAssets = { items: [], total: 0 },
+    isLoading: assetsLoading,
+    isError: assetsError,
+    error: assetsErrorObj,
+    refetch: refetchAssets,
+  } = useQuery<{ items: ApiAssetItem[]; total: number }, Error>({
+    queryKey: ["assets", effectiveLibId],
+    queryFn: () =>
+      getAssets(effectiveLibId, {
+        // 拉取所有非删除状态的素材，让用户上传后立刻能看到"处理中"的素材
+        status: "ready,uploading,ingesting,processing,pending,error,failed",
+      }),
+    enabled: !!effectiveLibId,
+    staleTime: 30_000,
+  })
+
+  const assets: AssetItem[] = useMemo(
+    () => (Array.isArray(apiAssets?.items) ? apiAssets.items : []).map(mapAsset),
+    [apiAssets],
+  )
+
+  /* ── 筛选状态 ── */
+  const [searchText, setSearchText] = useState("")
+  const [filterType, setFilterType] = useState<string>("all")
+  const [filterTime, setFilterTime] = useState<string>("all")
+
+  /* ── 筛选后的素材列表 ── */
+  const filteredAssets = useMemo(() => {
+    let list = assets
+
+    /* 按素材类型过滤 */
+    if (filterType !== "all") {
+      list = list.filter((a) => a.kind === filterType)
+    }
+
+    /* 按时间筛选 */
+    if (filterTime !== "all") {
+      const now = new Date()
+      list = list.filter((a) => {
+        const d = new Date(a.createdAt)
+        const diffDays = (now.getTime() - d.getTime()) / (1000 * 60 * 60 * 24)
+        if (filterTime === "today") return diffDays < 1
+        if (filterTime === "week") return diffDays < 7
+        if (filterTime === "month") return diffDays < 30
+        return true
+      })
+    }
+
+    /* 搜索 */
+    if (searchText.trim()) {
+      const q = searchText.trim().toLowerCase()
+      list = list.filter((a) => a.name.toLowerCase().includes(q))
+    }
+
+    return list
+  }, [assets, filterType, filterTime, searchText])
+
+  return {
+    // 视频库
+    libraries,
+    libLoading,
+    activeLibId,
+    setActiveLibId,
+    effectiveLibId,
+    // 素材列表
+    assets,
+    assetsLoading,
+    assetsError,
+    assetsErrorObj,
+    refetchAssets,
+    // 筛选
+    searchText,
+    setSearchText,
+    filterType,
+    setFilterType,
+    filterTime,
+    setFilterTime,
+    filteredAssets,
+  }
+}
@@ -0,0 +1,106 @@
+import { useState, useCallback } from "react"
+import { useMutation, useQueryClient } from "@tanstack/react-query"
+import { message } from "antd"
+import { createAssetLibrary, deleteAssetLibrary } from "@/api/assets"
+import type { AssetKind, LibraryItem } from "../types"
+
+/**
+ * 视频库管理 Hook
+ * 封装视频库的创建、删除操作，以及新建弹窗的表单状态
+ */
+interface UseLibraryManagementProps {
+  libraries: LibraryItem[]
+  activeLibId: string
+  setActiveLibId: (id: string) => void
+  effectiveLibId: string
+}
+
+export function useLibraryManagement({
+  libraries,
+  setActiveLibId,
+  effectiveLibId,
+}: UseLibraryManagementProps) {
+  const queryClient = useQueryClient()
+
+  /* ── 状态 ── */
+  const [createModalOpen, setCreateModalOpen] = useState(false)
+  const [newLibName, setNewLibName] = useState("")
+  const [newLibKind, setNewLibKind] = useState<AssetKind>("video")
+
+  /* ── Mutations ── */
+  const createLibMutation = useMutation({
+    mutationFn: createAssetLibrary,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["asset-libraries"] })
+      message.success("视频库创建成功")
+    },
+    onError: () => {
+      message.error("创建视频库失败")
+    },
+  })
+
+  const deleteLibMutation = useMutation({
+    mutationFn: deleteAssetLibrary,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["asset-libraries"] })
+      message.success("视频库已删除")
+    },
+    onError: () => {
+      message.error("删除视频库失败")
+    },
+  })
+
+  /* ── 新建视频库 ── */
+  const handleCreateLibrary = useCallback(async () => {
+    if (!newLibName.trim()) {
+      message.warning("请输入视频库名称")
+      return
+    }
+    try {
+      const newLib = await createLibMutation.mutateAsync({
+        name: newLibName.trim(),
+        kind: newLibKind,
+      })
+      setActiveLibId(newLib.id)
+      setCreateModalOpen(false)
+      setNewLibName("")
+      setNewLibKind("video")
+    } catch {
+      // error handled in mutation
+    }
+  }, [newLibName, newLibKind, createLibMutation, setActiveLibId])
+
+  /* ── 删除视频库 ── */
+  const handleDeleteLibrary = useCallback(
+    async (id: string) => {
+      try {
+        await deleteLibMutation.mutateAsync(id)
+        if (effectiveLibId === id) {
+          const remaining = libraries.filter((l) => l.id !== id)
+          if (remaining.length > 0) setActiveLibId(remaining[0].id)
+          else setActiveLibId("")
+        }
+      } catch {
+        // error handled in mutation
+      }
+    },
+    [deleteLibMutation, effectiveLibId, libraries, setActiveLibId],
+  )
+
+  return {
+    // 弹窗状态
+    createModalOpen,
+    setCreateModalOpen,
+    // 表单状态
+    newLibName,
+    setNewLibName,
+    newLibKind,
+    setNewLibKind,
+    // Mutations
+    isCreating: createLibMutation.isPending,
+    isDeleting: deleteLibMutation.isPending,
+    // Handlers
+    handleCreateLibrary,
+    handleDeleteLibrary,
+  }
+}
@@ -0,0 +1,115 @@
+/**
+ * 素材库类型定义
+ */
+import type { AssetLibraryItem, AssetItem as ApiAssetItem } from "@/api/assets"
+import { formatDuration } from "./utils/format"
+
+export type AssetKind = "video" | "image" | "voice"
+export type StatusType = "ok" | "warn" | "bad" | "info"
+
+export interface LibraryItem {
+  id: string
+  name: string
+  kind: AssetKind
+  count: number
+}
+
+export interface AssetItem {
+  id: string
+  name: string
+  kind: AssetKind
+  thumbUrl?: string
+  fileUrl?: string
+  status: StatusType
+  statusLabel: string
+  /** 是否处于处理中状态（上传中/入库中/诊断中） */
+  loading?: boolean
+  duration?: string
+  size: number
+  createdAt: string
+}
+
+/** 根据 mime_type 推断前端 AssetKind */
+export const inferKind = (mimeType: string): AssetKind => {
+  if (mimeType.startsWith("video/")) return "video"
+  if (mimeType.startsWith("audio/")) return "voice"
+  return "image"
+}
+
+/** 根据 quality_score / classification_status / asset status 推断前端状态 */
+export const inferStatus = (
+  score?: number,
+  classificationStatus?: string,
+  assetStatus?: string,
+): { status: StatusType; label: string; loading?: boolean } => {
+  // 已删除素材（正常情况列表已过滤，这里是防御性处理）
+  if (assetStatus === "deleted") {
+    return { status: "bad", label: "已删除" }
+  }
+  // 处理中状态：上传中 / 入库中 / 处理中
+  if (
+    assetStatus === "uploading" ||
+    assetStatus === "ingesting" ||
+    assetStatus === "processing" ||
+    assetStatus === "pending"
+  ) {
+    return { status: "info", label: "处理中", loading: true }
+  }
+  // 失败状态
+  if (assetStatus === "error" || assetStatus === "failed") {
+    return { status: "bad", label: "处理失败" }
+  }
+  // 素材已就绪（status=ready）时，不应因 classification 未执行而显示"处理中"
+  if (assetStatus === "ready") {
+    if (score == null) return { status: "info", label: "待诊断" }
+    if (score >= 70) return { status: "ok", label: "合格" }
+    if (score >= 40) return { status: "warn", label: "待优化" }
+    return { status: "bad", label: "不合格" }
+  }
+  // 素材未就绪：classification 正在处理中
+  if (classificationStatus === "processing" || classificationStatus === "pending") {
+    return { status: "info", label: "处理中", loading: true }
+  }
+  if (score == null) return { status: "info", label: "待诊断" }
+  if (score >= 70) return { status: "ok", label: "合格" }
+  if (score >= 40) return { status: "warn", label: "待优化" }
+  return { status: "bad", label: "不合格" }
+}
+
+/** 将后端 AssetLibraryItem 映射为前端 LibraryItem */
+export const mapLibrary = (item: AssetLibraryItem): LibraryItem => ({
+  id: item.id,
+  name: item.name,
+  kind: item.kind || inferKind("video"),
+  count: item.asset_count ?? 0,
+})
+
+/** 将后端 ApiAssetItem 映射为前端 AssetItem */
+export const mapAsset = (item: ApiAssetItem): AssetItem => {
+  const { status, label, loading } = inferStatus(
+    item.quality_score ?? undefined,
+    item.classification_status ?? undefined,
+    item.status ?? undefined,
+  )
+  const metadata = item.metadata || {}
+  const kind = inferKind(item.mime_type || "")
+  return {
+    id: item.id,
+    name: item.name,
+    kind,
+    // 视频类型不能用 file_url 做缩略图（是视频文件，<img> 无法渲染）
+    // 处理中的素材没有缩略图，显示占位符
+    thumbUrl: loading
+      ? undefined
+      : (item.thumbnail_url as string | undefined) ||
+        (metadata.thumbnail_url as string | undefined) ||
+        (kind !== "video" ? (item.file_url as string | undefined) : undefined),
+    fileUrl: (item.file_url as string | undefined) || (metadata.file_url as string | undefined),
+    status,
+    statusLabel: label,
+    loading,
+    duration: metadata.duration != null ? formatDuration(metadata.duration as number) : undefined,
+    size: item.file_size ? +(item.file_size / (1024 * 1024)).toFixed(1) : 0,
+    createdAt: item.created_at ? new Date(item.created_at).toISOString().slice(0, 10) : "—",
+  }
+}
@@ -0,0 +1,19 @@
+/**
+ * 素材相关工具函数
+ */
+import type { AssetKind } from "../types"
+import { KIND_LABELS } from "../constants"
+
+export const kindLabel = (kind: AssetKind): string => KIND_LABELS[kind] ?? kind
+
+/** 根据素材类型返回渐变背景 */
+export const thumbGradient = (kind: AssetKind): string => {
+  switch (kind) {
+    case "video":
+      return "linear-gradient(135deg, #312e81 0%, #4f46e5 50%, #6366f1 100%)"
+    case "image":
+      return "linear-gradient(135deg, #78350f 0%, #d97706 50%, #f59e0b 100%)"
+    case "voice":
+      return "linear-gradient(135deg, #064e3b 0%, #059669 50%, #10b981 100%)"
+  }
+}
@@ -0,0 +1,22 @@
+/**
+ * 格式化工具函数
+ */
+
+export const formatDuration = (seconds: number): string => {
+  const m = Math.floor(seconds / 60)
+  const s = Math.floor(seconds % 60)
+  return `${m.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}`
+}
+
+export const formatFileSize = (bytes: number): string => {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+export const formatDate = (iso: string): string =>
+  new Date(iso).toLocaleDateString("zh-CN", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  })
@@ -0,0 +1,15 @@
+import React from "react"
+import { VideoCameraOutlined, PictureOutlined, AudioOutlined } from "@ant-design/icons"
+import type { AssetKind } from "../types"
+
+/** 根据素材类型返回对应图标 */
+export const kindIcon = (kind: AssetKind): React.ReactNode => {
+  switch (kind) {
+    case "video":
+      return <VideoCameraOutlined />
+    case "image":
+      return <PictureOutlined />
+    case "voice":
+      return <AudioOutlined />
+  }
+}
@@ -0,0 +1,304 @@
+/**
+ * 所有弹窗和 Drawer 组件的集合
+ * 纯渲染层，业务逻辑和 state 留在父组件
+ */
+import React from "react"
+import type { TemplateCategory } from "@/api/editing-planner"
+import type {
+  ClipData,
+  TransitionConfig,
+  SpeedConfig,
+  TtsConfig,
+  WatermarkConfig,
+  IntroOutroConfig,
+  PipConfig,
+  FilterConfig,
+  ChromaKeyConfig,
+  StickerConfig,
+} from "../types"
+import { DEFAULT_TRANSITION, DEFAULT_SPEED, DEFAULT_TTS_CONFIG } from "../types"
+import type { SubtitleStyleConfig } from "../types/subtitle"
+import type { BgmMixConfig } from "@/api/bgm"
+import SaveModal from "./SaveModal"
+import BgmSelector from "./BgmSelector"
+import SubtitleStylePanel from "./SubtitleStylePanel"
+import TransitionSelector from "./TransitionSelector"
+import SpeedPanel from "./SpeedPanel"
+import TtsPanel from "./TtsPanel"
+import WatermarkPanel from "./WatermarkPanel"
+import IntroOutroPanel from "./IntroOutroPanel"
+import PipConfigPanel from "./PipConfigPanel"
+import FilterPanel from "./FilterPanel"
+import GreenScreenPanel from "./GreenScreenPanel"
+import StickerPanel from "./StickerPanel"
+
+interface EditingDrawersProps {
+  /* 保存弹窗 */
+  saveModalOpen: boolean
+  saveLoading: boolean
+  isUpdate: boolean
+  draftName: string
+  draftCategory: string
+  draftTags: string
+  categories: TemplateCategory[]
+  estimatedDuration: number
+  onNameChange: (name: string) => void
+  onCategoryChange: (cat: string) => void
+  onTagsChange: (tags: string) => void
+  onSave: () => Promise<void>
+  onCancelSave: () => void
+  /* BGM */
+  bgmDrawerOpen: boolean
+  bgmSettings: BgmMixConfig
+  onCloseBgmDrawer: () => void
+  onChangeBgmSettings: (config: BgmMixConfig) => void
+  /* 字幕 */
+  subtitleDrawerOpen: boolean
+  subtitleSettings: SubtitleStyleConfig
+  onCloseSubtitleDrawer: () => void
+  onChangeSubtitleSettings: (config: SubtitleStyleConfig) => void
+  /* 转场 */
+  transitionDrawerOpen: boolean
+  transitionTargetClipId: string | null
+  onCloseTransitionDrawer: () => void
+  onTransitionChange: (config: TransitionConfig) => void
+  /* 调速 */
+  speedDrawerOpen: boolean
+  speedTargetClipId: string | null
+  onCloseSpeedDrawer: () => void
+  onSpeedChange: (config: SpeedConfig) => void
+  onApplySpeedAll: (config: SpeedConfig) => void
+  /* TTS 配音 */
+  ttsDrawerOpen: boolean
+  ttsTargetClipId: string | null
+  onCloseTtsDrawer: () => void
+  onTtsChange: (config: TtsConfig) => void
+  /* 水印 */
+  watermarkDrawerOpen: boolean
+  watermarkSettings: WatermarkConfig
+  onCloseWatermarkDrawer: () => void
+  onWatermarkChange: (config: WatermarkConfig) => void
+  /* 片头片尾 */
+  introOutroDrawerOpen: boolean
+  introOutroSettings: IntroOutroConfig
+  onCloseIntroOutroDrawer: () => void
+  onIntroOutroChange: (config: IntroOutroConfig) => void
+  /* 混剪 */
+  pipDrawerOpen: boolean
+  pipSettings: PipConfig
+  onClosePipDrawer: () => void
+  onPipChange: (config: PipConfig) => void
+  /* 滤镜调色 */
+  filterDrawerOpen: boolean
+  filterSettings: FilterConfig
+  onCloseFilterDrawer: () => void
+  onFilterChange: (config: FilterConfig) => void
+  /* 绿幕抠像 */
+  chromaKeyDrawerOpen: boolean
+  chromaKeySettings: ChromaKeyConfig
+  onCloseChromaKeyDrawer: () => void
+  onChromaKeyChange: (config: ChromaKeyConfig) => void
+  /* 贴纸 */
+  stickerDrawerOpen: boolean
+  stickerSettings: StickerConfig
+  onCloseStickerDrawer: () => void
+  onStickerChange: (config: StickerConfig) => void
+  /* 共享数据 */
+  clips: ClipData[]
+  totalDuration: number
+}
+
+const EditingDrawers: React.FC<EditingDrawersProps> = ({
+  saveModalOpen,
+  saveLoading,
+  isUpdate,
+  draftName,
+  draftCategory,
+  draftTags,
+  categories,
+  estimatedDuration,
+  onNameChange,
+  onCategoryChange,
+  onTagsChange,
+  onSave,
+  onCancelSave,
+  bgmDrawerOpen,
+  bgmSettings,
+  onCloseBgmDrawer,
+  onChangeBgmSettings,
+  subtitleDrawerOpen,
+  subtitleSettings,
+  onCloseSubtitleDrawer,
+  onChangeSubtitleSettings,
+  transitionDrawerOpen,
+  transitionTargetClipId,
+  onCloseTransitionDrawer,
+  onTransitionChange,
+  speedDrawerOpen,
+  speedTargetClipId,
+  onCloseSpeedDrawer,
+  onSpeedChange,
+  onApplySpeedAll,
+  ttsDrawerOpen,
+  ttsTargetClipId,
+  onCloseTtsDrawer,
+  onTtsChange,
+  watermarkDrawerOpen,
+  watermarkSettings,
+  onCloseWatermarkDrawer,
+  onWatermarkChange,
+  introOutroDrawerOpen,
+  introOutroSettings,
+  onCloseIntroOutroDrawer,
+  onIntroOutroChange,
+  pipDrawerOpen,
+  pipSettings,
+  onClosePipDrawer,
+  onPipChange,
+  filterDrawerOpen,
+  filterSettings,
+  onCloseFilterDrawer,
+  onFilterChange,
+  chromaKeyDrawerOpen,
+  chromaKeySettings,
+  onCloseChromaKeyDrawer,
+  onChromaKeyChange,
+  stickerDrawerOpen,
+  stickerSettings,
+  onCloseStickerDrawer,
+  onStickerChange,
+  clips,
+  totalDuration,
+}) => {
+  const transitionConfig = transitionTargetClipId
+    ? (clips.find((c) => c.id === transitionTargetClipId)?.transition ?? DEFAULT_TRANSITION)
+    : DEFAULT_TRANSITION
+  const transitionTitle = transitionTargetClipId ? "片段转场设置" : "全局默认转场"
+
+  const speedConfig = speedTargetClipId
+    ? (clips.find((c) => c.id === speedTargetClipId)?.speed ?? DEFAULT_SPEED)
+    : DEFAULT_SPEED
+
+  const ttsConfig = ttsTargetClipId
+    ? (clips.find((c) => c.id === ttsTargetClipId)?.tts_config ?? DEFAULT_TTS_CONFIG)
+    : DEFAULT_TTS_CONFIG
+
+  return (
+    <>
+      {/* ═══ 保存弹窗 ═══ */}
+      <SaveModal
+        open={saveModalOpen}
+        loading={saveLoading}
+        isUpdate={isUpdate}
+        draftName={draftName}
+        draftCategory={draftCategory}
+        draftTags={draftTags}
+        categories={categories}
+        estimatedDuration={estimatedDuration}
+        onNameChange={onNameChange}
+        onCategoryChange={onCategoryChange}
+        onTagsChange={onTagsChange}
+        onSave={onSave}
+        onCancel={onCancelSave}
+      />
+
+      {/* ═══ BGM 选择器 Drawer ═══ */}
+      <BgmSelector
+        open={bgmDrawerOpen}
+        onClose={onCloseBgmDrawer}
+        config={bgmSettings}
+        onChange={onChangeBgmSettings}
+      />
+
+      {/* ═══ 字幕样式配置 Drawer ═══ */}
+      <SubtitleStylePanel
+        open={subtitleDrawerOpen}
+        onClose={onCloseSubtitleDrawer}
+        config={subtitleSettings}
+        onChange={onChangeSubtitleSettings}
+      />
+
+      {/* ═══ 转场特效选择器 Drawer ═══ */}
+      <TransitionSelector
+        open={transitionDrawerOpen}
+        onClose={onCloseTransitionDrawer}
+        config={transitionConfig}
+        onChange={onTransitionChange}
+        title={transitionTitle}
+      />
+
+      {/* ═══ 片段调速面板 Drawer ═══ */}
+      {speedTargetClipId && (
+        <SpeedPanel
+          open={speedDrawerOpen}
+          onClose={onCloseSpeedDrawer}
+          config={speedConfig}
+          onChange={onSpeedChange}
+          onApplyAll={onApplySpeedAll}
+        />
+      )}
+
+      {/* ═══ TTS 配音面板 Drawer ═══ */}
+      {ttsTargetClipId && (
+        <TtsPanel
+          open={ttsDrawerOpen}
+          onClose={onCloseTtsDrawer}
+          config={ttsConfig}
+          onChange={onTtsChange}
+        />
+      )}
+
+      {/* ═══ 水印配置面板 ═══ */}
+      <WatermarkPanel
+        open={watermarkDrawerOpen}
+        onClose={onCloseWatermarkDrawer}
+        config={watermarkSettings}
+        onChange={onWatermarkChange}
+      />
+
+      {/* ═══ 片头片尾配置面板 ═══ */}
+      <IntroOutroPanel
+        open={introOutroDrawerOpen}
+        onClose={onCloseIntroOutroDrawer}
+        config={introOutroSettings}
+        onChange={onIntroOutroChange}
+      />
+
+      {/* ═══ 混剪配置面板 ═══ */}
+      <PipConfigPanel
+        open={pipDrawerOpen}
+        onClose={onClosePipDrawer}
+        config={pipSettings}
+        onChange={onPipChange}
+        totalDuration={totalDuration}
+      />
+
+      {/* ═══ 滤镜调色面板 ═══ */}
+      <FilterPanel
+        open={filterDrawerOpen}
+        onClose={onCloseFilterDrawer}
+        config={filterSettings}
+        onChange={onFilterChange}
+      />
+
+      {/* ═══ 绿幕抠像面板 ═══ */}
+      <GreenScreenPanel
+        open={chromaKeyDrawerOpen}
+        onClose={onCloseChromaKeyDrawer}
+        config={chromaKeySettings}
+        onChange={onChromaKeyChange}
+      />
+
+      {/* ═══ 贴纸面板 ═══ */}
+      <StickerPanel
+        open={stickerDrawerOpen}
+        onClose={onCloseStickerDrawer}
+        config={stickerSettings}
+        onChange={onStickerChange}
+        totalDuration={totalDuration}
+      />
+    </>
+  )
+}
+
+export default EditingDrawers
@@ -0,0 +1,246 @@
+import React from "react"
+import BgmSelector from "./BgmSelector"
+import SubtitleStylePanel from "./SubtitleStylePanel"
+import TransitionSelector from "./TransitionSelector"
+import SpeedPanel from "./SpeedPanel"
+import TtsPanel from "./TtsPanel"
+import WatermarkPanel from "./WatermarkPanel"
+import IntroOutroPanel from "./IntroOutroPanel"
+import PipConfigPanel from "./PipConfigPanel"
+import FilterPanel from "./FilterPanel"
+import GreenScreenPanel from "./GreenScreenPanel"
+import StickerPanel from "./StickerPanel"
+import type {
+  ClipData,
+  TransitionConfig,
+  SpeedConfig,
+  TtsConfig,
+  WatermarkConfig,
+  IntroOutroConfig,
+  PipConfig,
+  FilterConfig,
+  ChromaKeyConfig,
+  StickerConfig,
+} from "../types"
+import type { SubtitleStyleConfig } from "../types/subtitle"
+import type { BgmMixConfig } from "@/api/bgm"
+import { DEFAULT_TRANSITION, DEFAULT_SPEED, DEFAULT_TTS_CONFIG } from "../types"
+
+interface EditorDrawersProps {
+  // BGM
+  bgmDrawerOpen: boolean
+  bgmSettings: BgmMixConfig
+  onBgmSettingsChange: (config: BgmMixConfig) => void
+  onCloseBgmDrawer: () => void
+  // 字幕
+  subtitleDrawerOpen: boolean
+  subtitleSettings: SubtitleStyleConfig
+  onSubtitleSettingsChange: (config: SubtitleStyleConfig) => void
+  onCloseSubtitleDrawer: () => void
+  // 转场
+  transitionDrawerOpen: boolean
+  transitionTargetClipId: string | null
+  clips: ClipData[]
+  onTransitionChange: (config: TransitionConfig) => void
+  onCloseTransitionDrawer: () => void
+  // 调速
+  speedDrawerOpen: boolean
+  speedTargetClipId: string | null
+  onSpeedChange: (config: SpeedConfig) => void
+  onApplySpeedAll: (config: SpeedConfig) => void
+  onCloseSpeedDrawer: () => void
+  // TTS
+  ttsDrawerOpen: boolean
+  ttsTargetClipId: string | null
+  onTtsChange: (config: TtsConfig) => void
+  onCloseTtsDrawer: () => void
+  // 水印
+  watermarkDrawerOpen: boolean
+  watermarkSettings: WatermarkConfig
+  onWatermarkChange: (config: WatermarkConfig) => void
+  onCloseWatermarkDrawer: () => void
+  // 片头片尾
+  introOutroDrawerOpen: boolean
+  introOutroSettings: IntroOutroConfig
+  onIntroOutroChange: (config: IntroOutroConfig) => void
+  onCloseIntroOutroDrawer: () => void
+  // 混剪
+  pipDrawerOpen: boolean
+  pipSettings: PipConfig
+  totalDuration: number
+  onPipChange: (config: PipConfig) => void
+  onClosePipDrawer: () => void
+  // 滤镜
+  filterDrawerOpen: boolean
+  filterSettings: FilterConfig
+  onFilterChange: (config: FilterConfig) => void
+  onCloseFilterDrawer: () => void
+  // 绿幕
+  chromaKeyDrawerOpen: boolean
+  chromaKeySettings: ChromaKeyConfig
+  onChromaKeyChange: (config: ChromaKeyConfig) => void
+  onCloseChromaKeyDrawer: () => void
+  // 贴纸
+  stickerDrawerOpen: boolean
+  stickerSettings: StickerConfig
+  onStickerChange: (config: StickerConfig) => void
+  onCloseStickerDrawer: () => void
+}
+
+const EditorDrawers: React.FC<EditorDrawersProps> = ({
+  bgmDrawerOpen,
+  bgmSettings,
+  onBgmSettingsChange,
+  onCloseBgmDrawer,
+  subtitleDrawerOpen,
+  subtitleSettings,
+  onSubtitleSettingsChange,
+  onCloseSubtitleDrawer,
+  transitionDrawerOpen,
+  transitionTargetClipId,
+  clips,
+  onTransitionChange,
+  onCloseTransitionDrawer,
+  speedDrawerOpen,
+  speedTargetClipId,
+  onSpeedChange,
+  onApplySpeedAll,
+  onCloseSpeedDrawer,
+  ttsDrawerOpen,
+  ttsTargetClipId,
+  onTtsChange,
+  onCloseTtsDrawer,
+  watermarkDrawerOpen,
+  watermarkSettings,
+  onWatermarkChange,
+  onCloseWatermarkDrawer,
+  introOutroDrawerOpen,
+  introOutroSettings,
+  onIntroOutroChange,
+  onCloseIntroOutroDrawer,
+  pipDrawerOpen,
+  pipSettings,
+  totalDuration,
+  onPipChange,
+  onClosePipDrawer,
+  filterDrawerOpen,
+  filterSettings,
+  onFilterChange,
+  onCloseFilterDrawer,
+  chromaKeyDrawerOpen,
+  chromaKeySettings,
+  onChromaKeyChange,
+  onCloseChromaKeyDrawer,
+  stickerDrawerOpen,
+  stickerSettings,
+  onStickerChange,
+  onCloseStickerDrawer,
+}) => {
+  const transitionConfig = transitionTargetClipId
+    ? (clips.find((c) => c.id === transitionTargetClipId)?.transition ?? DEFAULT_TRANSITION)
+    : DEFAULT_TRANSITION
+
+  const transitionTitle = transitionTargetClipId ? "片段转场设置" : "全局默认转场"
+
+  return (
+    <>
+      {/* BGM 选择器 Drawer */}
+      <BgmSelector
+        open={bgmDrawerOpen}
+        onClose={onCloseBgmDrawer}
+        config={bgmSettings}
+        onChange={onBgmSettingsChange}
+      />
+
+      {/* 字幕样式配置 Drawer */}
+      <SubtitleStylePanel
+        open={subtitleDrawerOpen}
+        onClose={onCloseSubtitleDrawer}
+        config={subtitleSettings}
+        onChange={onSubtitleSettingsChange}
+      />
+
+      {/* 转场特效选择器 Drawer */}
+      <TransitionSelector
+        open={transitionDrawerOpen}
+        onClose={onCloseTransitionDrawer}
+        config={transitionConfig}
+        onChange={onTransitionChange}
+        title={transitionTitle}
+      />
+
+      {/* 片段调速面板 Drawer */}
+      {speedTargetClipId && (
+        <SpeedPanel
+          open={speedDrawerOpen}
+          onClose={onCloseSpeedDrawer}
+          config={clips.find((c) => c.id === speedTargetClipId)?.speed ?? DEFAULT_SPEED}
+          onChange={onSpeedChange}
+          onApplyAll={onApplySpeedAll}
+        />
+      )}
+
+      {/* TTS 配音面板 Drawer */}
+      {ttsTargetClipId && (
+        <TtsPanel
+          open={ttsDrawerOpen}
+          onClose={onCloseTtsDrawer}
+          config={clips.find((c) => c.id === ttsTargetClipId)?.tts_config ?? DEFAULT_TTS_CONFIG}
+          onChange={onTtsChange}
+        />
+      )}
+
+      {/* 水印配置面板 */}
+      <WatermarkPanel
+        open={watermarkDrawerOpen}
+        onClose={onCloseWatermarkDrawer}
+        config={watermarkSettings}
+        onChange={onWatermarkChange}
+      />
+
+      {/* 片头片尾配置面板 */}
+      <IntroOutroPanel
+        open={introOutroDrawerOpen}
+        onClose={onCloseIntroOutroDrawer}
+        config={introOutroSettings}
+        onChange={onIntroOutroChange}
+      />
+
+      {/* 混剪配置面板 */}
+      <PipConfigPanel
+        open={pipDrawerOpen}
+        onClose={onClosePipDrawer}
+        config={pipSettings}
+        onChange={onPipChange}
+        totalDuration={totalDuration}
+      />
+
+      {/* 滤镜调色面板 */}
+      <FilterPanel
+        open={filterDrawerOpen}
+        onClose={onCloseFilterDrawer}
+        config={filterSettings}
+        onChange={onFilterChange}
+      />
+
+      {/* 绿幕抠像面板 */}
+      <GreenScreenPanel
+        open={chromaKeyDrawerOpen}
+        onClose={onCloseChromaKeyDrawer}
+        config={chromaKeySettings}
+        onChange={onChromaKeyChange}
+      />
+
+      {/* 贴纸面板 */}
+      <StickerPanel
+        open={stickerDrawerOpen}
+        onClose={onCloseStickerDrawer}
+        config={stickerSettings}
+        onChange={onStickerChange}
+        totalDuration={totalDuration}
+      />
+    </>
+  )
+}
+
+export default EditorDrawers
@@ -0,0 +1,28 @@
+import React from "react"
+import type { TemplateMode } from "@/api/editing-planner"
+
+interface ModeBarProps {
+  modeList: { key: TemplateMode; label: string; icon: string }[]
+  currentMode: TemplateMode
+  onModeChange: (mode: TemplateMode) => void
+}
+
+const ModeBar: React.FC<ModeBarProps> = ({ modeList, currentMode, onModeChange }) => {
+  return (
+    <div className="ep-mode-bar">
+      <span className="ep-mode-bar-label">剪辑模式：</span>
+      {modeList.map((m) => (
+        <button
+          key={m.key}
+          className={`ep-mode-btn ${currentMode === m.key ? "active" : ""}`}
+          onClick={() => onModeChange(m.key)}
+        >
+          <span className="ep-mode-icon">{m.icon}</span>
+          <span className="ep-mode-label">{m.label}</span>
+        </button>
+      ))}
+    </div>
+  )
+}
+
+export default ModeBar
@@ -0,0 +1,169 @@
+import React from "react"
+import ClipPropertiesPanel from "./ClipPropertiesPanel"
+import EditorClipList from "./EditorClipList"
+import type { ClipData } from "../types"
+import type { SubtitleStyleConfig } from "../types/subtitle"
+import type { BgmMixConfig } from "@/api/bgm"
+import type { TemplateMode } from "@/api/editing-planner"
+import type { AssetItem } from "@/api/assets"
+
+interface RightPanelProps {
+  rightTab: "properties" | "clips"
+  onTabChange: (tab: "properties" | "clips") => void
+  // 属性 tab
+  selectedClip: ClipData | null
+  subtitleSettings: SubtitleStyleConfig
+  bgmSettings: BgmMixConfig
+  clipsCount: number
+  totalDuration: number
+  currentMode: TemplateMode
+  onSubtitleSettingsChange: (partial: Partial<SubtitleStyleConfig>) => void
+  onBgmSettingsChange: (partial: Partial<BgmMixConfig>) => void
+  onClipUpdate: (clipId: string, updates: Partial<ClipData>) => void
+  onOpenBgmDrawer: () => void
+  onOpenSubtitleDrawer: () => void
+  voiceMaterials: AssetItem[]
+  voiceMaterialsLoading: boolean
+  onRefreshVoiceMaterials: () => void
+  onClipVoiceSelect: (clipId: string, asset: AssetItem | null) => void
+  onOpenTransitionDrawer: (clipId?: string) => void
+  onOpenSpeedDrawer: (clipId: string) => void
+  onOpenTtsDrawer: (clipId: string) => void
+  onOpenWatermarkDrawer: () => void
+  onOpenIntroOutroDrawer: () => void
+  onOpenPipDrawer: () => void
+  onOpenFilterDrawer: () => void
+  onOpenGreenScreenDrawer: () => void
+  onOpenStickerDrawer: () => void
+  // 片段 tab
+  clips: ClipData[]
+  selectedClipId: string | null
+  onClipSelect: (clipId: string) => void
+  onClipMoveUp: (clipId: string) => void
+  onClipMoveDown: (clipId: string) => void
+  onClipRemove: (clipId: string) => void
+  onClipAdd: () => void
+}
+
+const RightPanel: React.FC<RightPanelProps> = ({
+  rightTab,
+  onTabChange,
+  selectedClip,
+  subtitleSettings,
+  bgmSettings,
+  clipsCount,
+  totalDuration,
+  currentMode,
+  onSubtitleSettingsChange,
+  onBgmSettingsChange,
+  onClipUpdate,
+  onOpenBgmDrawer,
+  onOpenSubtitleDrawer,
+  voiceMaterials,
+  voiceMaterialsLoading,
+  onRefreshVoiceMaterials,
+  onClipVoiceSelect,
+  onOpenTransitionDrawer,
+  onOpenSpeedDrawer,
+  onOpenTtsDrawer,
+  onOpenWatermarkDrawer,
+  onOpenIntroOutroDrawer,
+  onOpenPipDrawer,
+  onOpenFilterDrawer,
+  onOpenGreenScreenDrawer,
+  onOpenStickerDrawer,
+  clips,
+  selectedClipId,
+  onClipSelect,
+  onClipMoveUp,
+  onClipMoveDown,
+  onClipRemove,
+  onClipAdd,
+}) => {
+  return (
+    <div className="ep-right-panel">
+      {/* Tab 切换 */}
+      <div className="ep-right-tabs">
+        <button
+          className={`ep-right-tab${rightTab === "properties" ? " active" : ""}`}
+          onClick={() => onTabChange("properties")}
+        >
+          属性
+        </button>
+        <button
+          className={`ep-right-tab${rightTab === "clips" ? " active" : ""}`}
+          onClick={() => onTabChange("clips")}
+        >
+          片段
+        </button>
+      </div>
+
+      {/* 属性 Tab */}
+      {rightTab === "properties" && (
+        <div className="ep-right-tab-content">
+          {(() => {
+            // ClipPropertiesPanel 内部类型与主文件类型结构一致但字段细节不同
+            // 使用 unknown 作为中间类型避免 any 警告
+            const sub = subtitleSettings as unknown as React.ComponentProps<
+              typeof ClipPropertiesPanel
+            >["subtitleSettings"]
+            const bgm = bgmSettings as unknown as React.ComponentProps<
+              typeof ClipPropertiesPanel
+            >["bgmSettings"]
+            const onSubChange = onSubtitleSettingsChange as unknown as React.ComponentProps<
+              typeof ClipPropertiesPanel
+            >["onSubtitleSettingsChange"]
+            const onBgmChange = onBgmSettingsChange as unknown as React.ComponentProps<
+              typeof ClipPropertiesPanel
+            >["onBgmSettingsChange"]
+            return (
+              <ClipPropertiesPanel
+                selectedClip={selectedClip}
+                subtitleSettings={sub}
+                bgmSettings={bgm}
+                clipsCount={clipsCount}
+                totalDuration={totalDuration}
+                currentMode={currentMode}
+                onSubtitleSettingsChange={onSubChange}
+                onBgmSettingsChange={onBgmChange}
+                onClipUpdate={onClipUpdate}
+                onOpenBgmDrawer={onOpenBgmDrawer}
+                onOpenSubtitleDrawer={onOpenSubtitleDrawer}
+                voiceMaterials={voiceMaterials}
+                voiceMaterialsLoading={voiceMaterialsLoading}
+                onRefreshVoiceMaterials={onRefreshVoiceMaterials}
+                onClipVoiceSelect={onClipVoiceSelect}
+                onOpenTransitionDrawer={onOpenTransitionDrawer}
+                onOpenSpeedDrawer={onOpenSpeedDrawer}
+                onOpenTtsDrawer={onOpenTtsDrawer}
+                onOpenWatermarkDrawer={onOpenWatermarkDrawer}
+                onOpenIntroOutroDrawer={onOpenIntroOutroDrawer}
+                onOpenPipDrawer={onOpenPipDrawer}
+                onOpenFilterDrawer={onOpenFilterDrawer}
+                onOpenGreenScreenDrawer={onOpenGreenScreenDrawer}
+                onOpenStickerDrawer={onOpenStickerDrawer}
+              />
+            )
+          })()}
+        </div>
+      )}
+
+      {/* 片段 Tab */}
+      {rightTab === "clips" && (
+        <div className="ep-right-tab-content">
+          <EditorClipList
+            clips={clips}
+            selectedClipId={selectedClipId}
+            onSelect={onClipSelect}
+            onMoveUp={onClipMoveUp}
+            onMoveDown={onClipMoveDown}
+            onRemove={onClipRemove}
+            onAdd={onClipAdd}
+          />
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default RightPanel
@@ -0,0 +1,32 @@
+import React from "react"
+
+interface StatusBarProps {
+  clipsCount: number
+  totalDuration: number
+  currentModeLabel: string
+  templateSegments: number
+}
+
+const StatusBar: React.FC<StatusBarProps> = ({
+  clipsCount,
+  totalDuration,
+  currentModeLabel,
+  templateSegments,
+}) => {
+  return (
+    <div className="ep-status-bar">
+      <div className="ep-status-left">
+        <span>📋 片段: {clipsCount}</span>
+        <span className="ep-status-sep">|</span>
+        <span>⏱️ 总时长: {totalDuration.toFixed(1)}s</span>
+      </div>
+      <div className="ep-status-right">
+        <span>🎬 {currentModeLabel}</span>
+        <span className="ep-status-sep">|</span>
+        <span>📐 模板片段: {templateSegments}</span>
+      </div>
+    </div>
+  )
+}
+
+export default StatusBar
@@ -0,0 +1,54 @@
+import React from "react"
+import type { EditingTemplate } from "@/api/editing-planner"
+
+interface TopBarProps {
+  currentTemplate: EditingTemplate | null
+  canUndo: boolean
+  canRedo: boolean
+  onUndo: () => void
+  onRedo: () => void
+  onOpenSaveModal: () => void
+}
+
+const TopBar: React.FC<TopBarProps> = ({
+  currentTemplate,
+  canUndo,
+  canRedo,
+  onUndo,
+  onRedo,
+  onOpenSaveModal,
+}) => {
+  return (
+    <div className="ep-top-bar">
+      <div className="ep-top-bar-left">
+        <span className="ep-logo">✂️</span>
+        <span className="ep-app-title">模板制作</span>
+        <span className="ep-divider">|</span>
+        <span className="ep-template-name">{currentTemplate?.name || "未选择模板"}</span>
+      </div>
+      <div className="ep-top-bar-right">
+        <button
+          className="ep-btn ep-btn-secondary"
+          onClick={onUndo}
+          disabled={!canUndo}
+          title="撤销 (Ctrl+Z)"
+        >
+          ⬅️ 撤销
+        </button>
+        <button
+          className="ep-btn ep-btn-secondary"
+          onClick={onRedo}
+          disabled={!canRedo}
+          title="重做 (Ctrl+Shift+Z)"
+        >
+          ➡️ 重做
+        </button>
+        <button className="ep-btn ep-btn-secondary" onClick={onOpenSaveModal}>
+          💾 保存模板
+        </button>
+      </div>
+    </div>
+  )
+}
+
+export default TopBar
@@ -0,0 +1,12 @@
+import type { TemplateMode } from "@/api/editing-planner"
+
+/* ──────────── 常量 ──────────── */
+
+export const MODE_LIST: { key: TemplateMode; label: string; icon: string }[] = [
+  { key: "pip", label: "混剪", icon: "🖼️" },
+  { key: "voice_over", label: "人物口播", icon: "🎙️" },
+  { key: "one_take", label: "一镜到底", icon: "🎥" },
+  { key: "voice_pip", label: "口播+混剪", icon: "🎭" },
+]
+
+export const FILTER_CATEGORIES = ["全部", "种草", "知识", "日常", "推荐"]
@@ -0,0 +1,238 @@
+import { useState, useCallback, useMemo } from "react"
+import { Modal, message } from "antd"
+import type {
+  ClipData,
+  ClipType,
+  TransitionConfig,
+  SpeedConfig,
+  TtsConfig,
+  TrimConfig,
+} from "../types"
+import type { AssetItem } from "@/api/assets"
+
+interface UseClipOperationsParams {
+  clips: ClipData[]
+  setClips: (updater: (prev: ClipData[]) => ClipData[]) => void
+}
+
+/**
+ * 片段操作 Hook
+ * 片段增删改查、排序、裁剪、分割、转场、调速、TTS、配音选择
+ */
+export const useClipOperations = ({ clips, setClips }: UseClipOperationsParams) => {
+  const [selectedClipId, setSelectedClipId] = useState<string | null>(null)
+
+  const selectedClip = useMemo(
+    () => clips.find((c) => c.id === selectedClipId) || null,
+    [clips, selectedClipId],
+  )
+
+  /* ── 选中 / 重排 / 删除 ── */
+
+  const handleClipSelect = useCallback((clipId: string) => {
+    setSelectedClipId(clipId)
+  }, [])
+
+  const handleClipReorder = useCallback(
+    (fromIdx: number, toIdx: number) => {
+      setClips((prev) => {
+        const updated = [...prev]
+        const [moved] = updated.splice(fromIdx, 1)
+        updated.splice(toIdx, 0, moved)
+        return updated.map((c, i) => ({ ...c, order: i }))
+      })
+    },
+    [setClips],
+  )
+
+  const handleClipRemove = useCallback(
+    (clipId: string) => {
+      Modal.confirm({
+        title: "删除片段",
+        content: "确定要删除这个片段吗？此操作可通过撤销恢复。",
+        okText: "删除",
+        okType: "danger",
+        cancelText: "取消",
+        onOk: () => {
+          setClips((prev) => prev.filter((c) => c.id !== clipId))
+          if (selectedClipId === clipId) setSelectedClipId(null)
+        },
+      })
+    },
+    [setClips, selectedClipId],
+  )
+
+  const handleClipUpdate = useCallback(
+    (clipId: string, data: Partial<ClipData>) => {
+      setClips((prev) => prev.map((c) => (c.id === clipId ? { ...c, ...data } : c)))
+    },
+    [setClips],
+  )
+
+  /**
+   * 添加片段（不绑定任何素材）
+   * 片段 = 时间规划 + 类型标记
+   */
+  const handleAddClip = useCallback(
+    (type: ClipType, duration: number) => {
+      const newClip: ClipData = {
+        id: `clip-${Date.now()}`,
+        type,
+        duration,
+        startOffset: 0,
+        order: clips.length,
+      }
+      setClips((prev) => [...prev, newClip])
+    },
+    [clips.length, setClips],
+  )
+
+  /* ── 裁剪 / 分割 / 重置 ── */
+
+  const handleClipTrim = useCallback(
+    (clipId: string, trimConfig: TrimConfig, newDuration: number) => {
+      setClips((prev) =>
+        prev.map((c) =>
+          c.id === clipId ? { ...c, trim_config: trimConfig, duration: newDuration } : c,
+        ),
+      )
+    },
+    [setClips],
+  )
+
+  const handleClipSplit = useCallback(
+    (clipId: string, splitRatio: number) => {
+      setClips((prev) => {
+        const idx = prev.findIndex((c) => c.id === clipId)
+        if (idx === -1) return prev
+        const clip = prev[idx]
+        const splitPoint = Math.round(clip.duration * splitRatio * 10) / 10
+        if (splitPoint < 0.5 || splitPoint >= clip.duration - 0.5) return prev
+
+        // 前半段
+        const firstHalf: ClipData = {
+          ...clip,
+          duration: splitPoint,
+          trim_config: clip.trim_config
+            ? {
+                ...clip.trim_config,
+                end_time: clip.trim_config.start_time + splitPoint,
+              }
+            : undefined,
+        }
+
+        // 后半段
+        const secondHalf: ClipData = {
+          ...clip,
+          id: `clip-${Date.now()}`,
+          duration: clip.duration - splitPoint,
+          startOffset: clip.startOffset + splitPoint,
+          trim_config: clip.trim_config
+            ? {
+                ...clip.trim_config,
+                start_time: clip.trim_config.start_time + splitPoint,
+              }
+            : undefined,
+          order: (clip.order ?? idx) + 1,
+        }
+
+        const updated = [...prev]
+        updated[idx] = firstHalf
+        updated.splice(idx + 1, 0, secondHalf)
+        return updated.map((c, i) => ({ ...c, order: i }))
+      })
+    },
+    [setClips],
+  )
+
+  const handleClipResetTrim = useCallback(
+    (clipId: string) => {
+      setClips((prev) =>
+        prev.map((c) => {
+          if (c.id !== clipId || !c.trim_config) return c
+          const originalDuration = c.trim_config.original_duration ?? c.duration
+          return {
+            ...c,
+            duration: originalDuration,
+            trim_config: undefined,
+          }
+        }),
+      )
+    },
+    [setClips],
+  )
+
+  /* ── 转场 / 调速 / TTS ── */
+
+  const handleTransitionChange = useCallback(
+    (targetClipId: string | null, config: TransitionConfig) => {
+      if (targetClipId) {
+        handleClipUpdate(targetClipId, { transition: config })
+      }
+      // 同时更新全局默认转场（供新片段使用）—— 暂未实现全局默认
+    },
+    [handleClipUpdate],
+  )
+
+  const handleSpeedChange = useCallback(
+    (targetClipId: string | null, config: SpeedConfig) => {
+      if (targetClipId) {
+        handleClipUpdate(targetClipId, { speed: config })
+      }
+    },
+    [handleClipUpdate],
+  )
+
+  const handleApplySpeedAll = useCallback(
+    (config: SpeedConfig) => {
+      setClips((prev) => prev.map((c) => ({ ...c, speed: { ...config } })))
+      message.success("已应用到所有片段")
+    },
+    [setClips],
+  )
+
+  const handleTtsChange = useCallback(
+    (targetClipId: string | null, ttsConfig: TtsConfig) => {
+      if (!targetClipId) return
+      handleClipUpdate(targetClipId, { tts_config: ttsConfig })
+    },
+    [handleClipUpdate],
+  )
+
+  /** 为片段选择配音素材 */
+  const handleClipVoiceSelect = useCallback(
+    (clipId: string, asset: AssetItem | null) => {
+      setClips((prev) =>
+        prev.map((c) =>
+          c.id === clipId
+            ? {
+                ...c,
+                voice_asset_id: asset?.id ?? undefined,
+                voice_file_url: asset?.file_url ?? undefined,
+              }
+            : c,
+        ),
+      )
+    },
+    [setClips],
+  )
+
+  return {
+    selectedClipId,
+    setSelectedClipId,
+    selectedClip,
+    handleClipSelect,
+    handleClipReorder,
+    handleClipRemove,
+    handleClipUpdate,
+    handleAddClip,
+    handleClipTrim,
+    handleClipSplit,
+    handleClipResetTrim,
+    handleTransitionChange,
+    handleSpeedChange,
+    handleApplySpeedAll,
+    handleTtsChange,
+    handleClipVoiceSelect,
+  }
+}
@@ -0,0 +1,78 @@
+import { useState, useCallback } from "react"
+
+/**
+ * 编辑器 Drawer 开关管理
+ * 集中管理 11 个抽屉的开关状态 + 3 个目标片段 ID + 快捷打开方法
+ */
+export const useEditorDrawers = () => {
+  /* ── 抽屉开关 ── */
+  const [bgmDrawerOpen, setBgmDrawerOpen] = useState(false)
+  const [subtitleDrawerOpen, setSubtitleDrawerOpen] = useState(false)
+  const [transitionDrawerOpen, setTransitionDrawerOpen] = useState(false)
+  const [speedDrawerOpen, setSpeedDrawerOpen] = useState(false)
+  const [ttsDrawerOpen, setTtsDrawerOpen] = useState(false)
+  const [watermarkDrawerOpen, setWatermarkDrawerOpen] = useState(false)
+  const [introOutroDrawerOpen, setIntroOutroDrawerOpen] = useState(false)
+  const [pipDrawerOpen, setPipDrawerOpen] = useState(false)
+  const [filterDrawerOpen, setFilterDrawerOpen] = useState(false)
+  const [chromaKeyDrawerOpen, setChromaKeyDrawerOpen] = useState(false)
+  const [stickerDrawerOpen, setStickerDrawerOpen] = useState(false)
+
+  /* ── 目标片段 ID ── */
+  /** 当前正在编辑转场的片段 ID（null = 全局默认转场） */
+  const [transitionTargetClipId, setTransitionTargetClipId] = useState<string | null>(null)
+  /** 当前正在调速的片段 ID */
+  const [speedTargetClipId, setSpeedTargetClipId] = useState<string | null>(null)
+  /** 当前正在配置 TTS 的片段 ID */
+  const [ttsTargetClipId, setTtsTargetClipId] = useState<string | null>(null)
+
+  /* ── 快捷打开 ── */
+  const openTransitionDrawer = useCallback((clipId?: string) => {
+    setTransitionTargetClipId(clipId ?? null)
+    setTransitionDrawerOpen(true)
+  }, [])
+
+  const openSpeedDrawer = useCallback((clipId: string) => {
+    setSpeedTargetClipId(clipId)
+    setSpeedDrawerOpen(true)
+  }, [])
+
+  const openTtsDrawer = useCallback((clipId: string) => {
+    setTtsTargetClipId(clipId)
+    setTtsDrawerOpen(true)
+  }, [])
+
+  return {
+    // 开关 state
+    bgmDrawerOpen,
+    setBgmDrawerOpen,
+    subtitleDrawerOpen,
+    setSubtitleDrawerOpen,
+    transitionDrawerOpen,
+    setTransitionDrawerOpen,
+    speedDrawerOpen,
+    setSpeedDrawerOpen,
+    ttsDrawerOpen,
+    setTtsDrawerOpen,
+    watermarkDrawerOpen,
+    setWatermarkDrawerOpen,
+    introOutroDrawerOpen,
+    setIntroOutroDrawerOpen,
+    pipDrawerOpen,
+    setPipDrawerOpen,
+    filterDrawerOpen,
+    setFilterDrawerOpen,
+    chromaKeyDrawerOpen,
+    setChromaKeyDrawerOpen,
+    stickerDrawerOpen,
+    setStickerDrawerOpen,
+    // 目标 ID
+    transitionTargetClipId,
+    speedTargetClipId,
+    ttsTargetClipId,
+    // 快捷方法
+    openTransitionDrawer,
+    openSpeedDrawer,
+    openTtsDrawer,
+  }
+}
@@ -0,0 +1,56 @@
+import { useState, useCallback, useEffect, useRef } from "react"
+
+/**
+ * 播放控制 Hook
+ * 播放/暂停、rAF 帧推进、时间线缩放、seek
+ */
+export const usePlaybackControl = (totalDuration: number) => {
+  const [isPlaying, setIsPlaying] = useState(false)
+  const [currentTime, setCurrentTime] = useState(0)
+  const [pixelsPerSecond, setPixelsPerSecond] = useState(40)
+  const prevFrameTimeRef = useRef<number | null>(null)
+
+  /** 播放头跳转 */
+  const handleSeek = useCallback((time: number) => {
+    setCurrentTime(Math.max(0, time))
+  }, [])
+
+  /** 轨道缩放 */
+  const handleZoomChange = useCallback((pps: number) => {
+    setPixelsPerSecond(pps)
+  }, [])
+
+  /** rAF 帧推进 — 播放时平滑更新播放头位置 */
+  useEffect(() => {
+    if (!isPlaying) {
+      prevFrameTimeRef.current = null
+      return
+    }
+    let rafId: number
+    const tick = (timestamp: number) => {
+      if (prevFrameTimeRef.current !== null) {
+        const delta = (timestamp - prevFrameTimeRef.current) / 1000
+        setCurrentTime((prev) => {
+          const next = prev + delta
+          return next >= totalDuration ? totalDuration : next
+        })
+      }
+      prevFrameTimeRef.current = timestamp
+      rafId = requestAnimationFrame(tick)
+    }
+    rafId = requestAnimationFrame(tick)
+    return () => {
+      cancelAnimationFrame(rafId)
+      prevFrameTimeRef.current = null
+    }
+  }, [isPlaying, totalDuration])
+
+  return {
+    isPlaying,
+    setIsPlaying,
+    currentTime,
+    pixelsPerSecond,
+    handleSeek,
+    handleZoomChange,
+  }
+}
@@ -0,0 +1,466 @@
+import { useState, useCallback, useEffect, type Dispatch, type SetStateAction } from "react"
+import { FILTER_CATEGORIES } from "../constants"
+import { message } from "antd"
+import type {
+  EditingTemplate,
+  TemplateCategory,
+  TemplateMode,
+  SaveTemplatePayload,
+} from "@/api/editing-planner"
+import {
+  getEditingTemplates,
+  getEditingTemplate,
+  createEditingTemplate,
+  updateEditingTemplate,
+  getTemplateCategories,
+} from "@/api/editing-planner"
+import type { MediaAsset, TitleConfig, TransitionEffect } from "@/api/template-editor"
+import { getMediaAssets, getEditPlan, getEditPlanClips } from "@/api/template-editor"
+import type {
+  ClipData,
+  ClipType,
+  TtsConfig,
+  TtsMode,
+  TrimConfig,
+  WatermarkConfig,
+  IntroOutroConfig,
+  PipConfig,
+  FilterConfig,
+  ChromaKeyConfig,
+  StickerConfig,
+  CoverConfig,
+} from "../types"
+import type { SubtitleStyleConfig } from "../types/subtitle"
+import type { BgmMixConfig } from "@/api/bgm"
+
+interface UseTemplateManagementParams {
+  urlTemplateId: string
+  urlPlanId: string
+  resetClips: (clips: ClipData[]) => void
+  setClips: (updater: (prev: ClipData[]) => ClipData[]) => void
+  setSelectedClipId: (id: string | null) => void
+  setMediaAssets: (assets: MediaAsset[]) => void
+  setTitleConfig: Dispatch<SetStateAction<TitleConfig>>
+  setSubtitleSettings: Dispatch<SetStateAction<SubtitleStyleConfig>>
+  setBgmSettings: Dispatch<SetStateAction<BgmMixConfig>>
+  setCoverConfig: Dispatch<SetStateAction<CoverConfig>>
+  // 保存时需要的配置
+  clips: ClipData[]
+  totalDuration: number
+  titleConfig: TitleConfig
+  subtitleSettings: SubtitleStyleConfig
+  bgmSettings: BgmMixConfig
+  watermarkSettings: WatermarkConfig
+  introOutroSettings: IntroOutroConfig
+  pipSettings: PipConfig
+  filterSettings: FilterConfig
+  chromaKeySettings: ChromaKeyConfig
+  stickerSettings: StickerConfig
+  coverConfig: CoverConfig
+}
+
+/**
+ * 模板管理 Hook
+ * 模板列表/分类/加载/保存/模式切换/筛选搜索 + 3 个 useEffect
+ */
+export const useTemplateManagement = (params: UseTemplateManagementParams) => {
+  const {
+    urlTemplateId,
+    urlPlanId,
+    resetClips,
+    setClips,
+    setSelectedClipId,
+    setMediaAssets,
+    setTitleConfig,
+    setSubtitleSettings,
+    setBgmSettings,
+    setCoverConfig,
+    clips,
+    totalDuration,
+    titleConfig,
+    subtitleSettings,
+    bgmSettings,
+    watermarkSettings,
+    introOutroSettings,
+    pipSettings,
+    filterSettings,
+    chromaKeySettings,
+    stickerSettings,
+    coverConfig,
+  } = params
+
+  /* ── 模板列表 ── */
+  const [templates, setTemplates] = useState<EditingTemplate[]>([])
+  const [categories, setCategories] = useState<TemplateCategory[]>([])
+  const [loadingTemplates, setLoadingTemplates] = useState(false)
+  const [loadedTemplateId, setLoadedTemplateId] = useState<string | null>(urlTemplateId || null)
+  const [currentMode, setCurrentMode] = useState<TemplateMode>("pip")
+
+  /* ── 左栏筛选 ── */
+  const [currentFilter, setCurrentFilter] = useState("全部")
+  const [searchQuery, setSearchQuery] = useState("")
+
+  /* ── 保存弹窗 ── */
+  const [saveModalOpen, setSaveModalOpen] = useState(false)
+  const [draftName, setDraftName] = useState("")
+  const [draftCategory, setDraftCategory] = useState("")
+  const [draftTags, setDraftTags] = useState("")
+  const [saveLoading, setSaveLoading] = useState(false)
+
+  /* ── 计划 ID（从 URL 传入，不变） ── */
+  const [loadedPlanId] = useState<string | null>(urlPlanId || null)
+
+  /* ── 计算 ── */
+  const filteredTemplates = templates.filter((t) => {
+    if (currentFilter !== "全部" && t.category !== currentFilter) return false
+    if (searchQuery && !t.name.toLowerCase().includes(searchQuery.toLowerCase())) return false
+    return true
+  })
+
+  const currentTemplate = templates.find((t) => t.id === loadedTemplateId) || null
+
+  /* ──────────── 加载 ──────────── */
+
+  /**
+   * 并行加载模板列表、分类、素材库
+   * 首次挂载时调用，三个接口无依赖关系，用 Promise.all 并发
+   */
+  const loadTemplates = useCallback(async () => {
+    setLoadingTemplates(true)
+    try {
+      const [tpls, cats, assets] = await Promise.all([
+        getEditingTemplates(),
+        getTemplateCategories(),
+        getMediaAssets(),
+      ])
+      setTemplates(tpls)
+      setCategories(cats)
+      setMediaAssets(assets)
+    } catch {
+      message.error("加载模板失败")
+    } finally {
+      setLoadingTemplates(false)
+    }
+  }, [setMediaAssets])
+
+  useEffect(() => {
+    loadTemplates()
+  }, [loadTemplates])
+
+  /**
+   * 加载模板详情并初始化片段列表
+   * 将后端 segments 映射为前端 ClipData，取 duration_min/max 均值作为默认时长
+   * 同时还原标题/字幕/BGM 配置
+   */
+  useEffect(() => {
+    if (!loadedTemplateId) return
+    getEditingTemplate(loadedTemplateId)
+      .then((tpl) => {
+        if (!tpl) return
+        setCurrentMode(tpl.mode)
+        const mapped: ClipData[] = tpl.segments.map((seg, idx) => ({
+          id: seg.id || `seg-${idx}`,
+          template_segment_id: seg.id || `seg-${idx}`,
+          type: (seg.material_type === "voiceover" ? "voice" : "pip") as ClipType,
+          duration: (seg.duration_min + seg.duration_max) / 2,
+          startOffset: 0,
+          script_text: "",
+          order: seg.segment_order,
+        }))
+        resetClips(mapped)
+
+        setTitleConfig({
+          ai_auto_select: tpl.title_config.ai_auto_select,
+          content: tpl.title_config.content,
+          position: tpl.title_config.position,
+          font_preset: tpl.title_config.font_preset,
+          font_size: tpl.title_config.font_size,
+          font_color: tpl.title_config.font_color || "#ffffff",
+        })
+        setSubtitleSettings((prev) => ({
+          ...prev,
+          enabled: tpl.subtitle_config.enabled,
+          position: (tpl.subtitle_config.position || "bottom") as SubtitleStyleConfig["position"],
+          font: tpl.subtitle_config.font,
+          fontSize: tpl.subtitle_config.size,
+          fontColor: tpl.subtitle_config.color || "#ffffff",
+          animation: tpl.subtitle_config.animation,
+        }))
+        setBgmSettings((prev) => ({
+          ...prev,
+          enabled: tpl.bgm_config.enabled,
+          music_id: tpl.bgm_config.music_id || "",
+        }))
+        setDraftName(tpl.name)
+        setDraftCategory(tpl.category)
+        setDraftTags(tpl.tags.join(", "))
+      })
+      .catch(() => message.error("加载模板详情失败"))
+  }, [loadedTemplateId, resetClips, setTitleConfig, setSubtitleSettings, setBgmSettings])
+
+  /**
+   * 加载已有模板草稿数据到编辑器
+   * 从列表页"编辑"按钮进入时，URL 带 planId，需要还原计划配置
+   */
+  useEffect(() => {
+    if (!loadedPlanId) return
+
+    // 并行加载计划基本信息 + 片段列表
+    Promise.all([
+      getEditPlan(loadedPlanId),
+      getEditPlanClips(loadedPlanId, { limit: 500 }).catch(() => ({
+        items: [],
+        total: 0,
+      })),
+    ])
+      .then(([plan, clipsRes]) => {
+        // 设置关联的模板（触发模板加载 effect）
+        setLoadedTemplateId(plan.template_id)
+
+        // 还原基本信息
+        setDraftName(plan.name)
+
+        // 还原 config 中的编辑器状态
+        const cfg = plan.config
+        if (cfg.title_config) {
+          setTitleConfig({
+            ai_auto_select: cfg.title_config!.ai_auto_select,
+            content: cfg.title_config!.content,
+            position: cfg.title_config!.position,
+            font_preset: cfg.title_config!.font_preset,
+            font_size: cfg.title_config!.font_size,
+            font_color: cfg.title_config!.font_color || "#ffffff",
+          })
+        }
+        if (cfg.subtitle_config) {
+          setSubtitleSettings((prev) => ({
+            ...prev,
+            enabled: cfg.subtitle_config!.enabled,
+            position: (cfg.subtitle_config!.position ||
+              "bottom") as SubtitleStyleConfig["position"],
+            font: cfg.subtitle_config!.font,
+            fontSize: cfg.subtitle_config!.size,
+            fontColor: cfg.subtitle_config!.color || "#ffffff",
+            animation: cfg.subtitle_config!.animation,
+          }))
+        }
+        if (cfg.bgm_config) {
+          setBgmSettings((prev) => ({
+            ...prev,
+            enabled: cfg.bgm_config!.enabled,
+            music_id: cfg.bgm_config!.music_id || "",
+          }))
+        }
+        // 还原封面配置
+        if (cfg.cover_config) {
+          setCoverConfig((prev) => ({
+            ...prev,
+            enabled: cfg.cover_config!.enabled ?? prev.enabled,
+            mode: (cfg.cover_config!.mode as CoverConfig["mode"]) || prev.mode,
+            frame_time: cfg.cover_config!.frame_time ?? prev.frame_time,
+            upload_url: cfg.cover_config!.upload_url || prev.upload_url,
+            thumbnail_url: cfg.cover_config!.thumbnail_url || prev.thumbnail_url,
+            ai_suggested_time: cfg.cover_config!.ai_suggested_time ?? prev.ai_suggested_time,
+          }))
+        }
+
+        // 还原片段：优先从后端 clips 表，其次从 config.segments 兜底
+        const backendClips = clipsRes?.items || []
+        if (backendClips.length > 0) {
+          // 从后端 clips 表还原
+          const sorted = [...backendClips].sort((a, b) => a.order - b.order)
+          const mapped: ClipData[] = sorted.map((clip) => ({
+            id: clip.id,
+            template_segment_id: (clip.config?.template_segment_id as string) || "",
+            type: (clip.clip_type === "voiceover" ? "voice" : "pip") as ClipType,
+            duration: clip.duration || 3,
+            startOffset: 0,
+            script_text: clip.text_content || "",
+            order: clip.order,
+            media_asset_id: clip.asset_id || undefined,
+            transition:
+              clip.transition_effect && clip.transition_effect !== "none"
+                ? {
+                    type: clip.transition_effect as TransitionEffect["type"],
+                    duration: clip.transition_duration || 0.3,
+                  }
+                : undefined,
+            speed: clip.playback_speed
+              ? { rate: clip.playback_speed, pitchCorrection: true }
+              : undefined,
+            tts_config: (clip.config?.tts_config as TtsConfig) || undefined,
+            trim_config: (clip.config?.trim_config as TrimConfig) || undefined,
+          }))
+          setTimeout(() => resetClips(mapped), 100)
+        } else if (cfg.segments && cfg.segments.length > 0) {
+          // 兜底：从 config.segments 还原（老数据兼容）
+          const mapped: ClipData[] = cfg.segments.map((seg, idx) => ({
+            id: `seg-${idx}`,
+            template_segment_id: `seg-${idx}`,
+            type: (seg.material_type === "voiceover" ? "voice" : "pip") as ClipType,
+            duration: (seg.duration_min + seg.duration_max) / 2,
+            startOffset: 0,
+            script_text: "",
+            order: seg.segment_order,
+            transition: seg.transition
+              ? {
+                  type: seg.transition.type as TransitionEffect["type"],
+                  duration: seg.transition.duration,
+                }
+              : undefined,
+            speed: seg.playback_speed
+              ? { rate: seg.playback_speed, pitchCorrection: true }
+              : undefined,
+            tts_config: seg.tts_config
+              ? { ...seg.tts_config, mode: seg.tts_config.mode as TtsMode }
+              : undefined,
+            trim_config: seg.trim_config || undefined,
+          }))
+          setTimeout(() => resetClips(mapped), 100)
+        }
+      })
+      .catch(() => message.error("加载模板草稿失败"))
+  }, [
+    loadedPlanId,
+    resetClips,
+    setTitleConfig,
+    setSubtitleSettings,
+    setBgmSettings,
+    setCoverConfig,
+  ])
+
+  /* ──────────── 事件 ──────────── */
+
+  const handleLoadTemplate = (templateId: string) => {
+    setLoadedTemplateId(templateId)
+    setSelectedClipId(null)
+  }
+
+  const handleModeChange = (mode: TemplateMode) => {
+    setCurrentMode(mode)
+    // 切换纯单类型模式时，自动转换所有已有片段的类型
+    if (mode === "voice_over") {
+      setClips((prev) => prev.map((c) => ({ ...c, type: "voice" as const })))
+    } else if (mode === "pip") {
+      setClips((prev) => prev.map((c) => ({ ...c, type: "pip" as const })))
+    }
+    // 混合模式(voice_pip)和一镜到底(one_take)不自动转换，保留原有类型
+  }
+
+  const handleOpenSaveModal = () => {
+    setSaveModalOpen(true)
+  }
+
+  const handleSave = async () => {
+    if (!draftName.trim()) {
+      message.warning("请输入模板名称")
+      return
+    }
+    setSaveLoading(true)
+    try {
+      const payload: SaveTemplatePayload = {
+        name: draftName,
+        mode: currentMode,
+        category: draftCategory,
+        tags: draftTags
+          .split(",")
+          .map((t) => t.trim())
+          .filter(Boolean),
+        title_config: titleConfig,
+        subtitle_config: {
+          enabled: subtitleSettings.enabled,
+          position: subtitleSettings.position,
+          font: subtitleSettings.font,
+          color: subtitleSettings.fontColor,
+          size: subtitleSettings.fontSize,
+          animation: subtitleSettings.animation,
+        },
+        bgm_config: {
+          enabled: bgmSettings.enabled,
+          music_id: bgmSettings.music_id,
+        },
+        estimated_duration: totalDuration,
+        segments: clips.map((c, i) => ({
+          segment_order: i,
+          duration_min: Math.max(1, c.duration - 2),
+          duration_max: c.duration + 2,
+          material_type: c.type === "voice" ? "voiceover" : "video",
+          transition: c.transition
+            ? { type: c.transition.type, duration: c.transition.duration }
+            : undefined,
+          playback_speed: c.speed ? c.speed.rate : undefined,
+          tts_config: c.tts_config
+            ? {
+                mode: c.tts_config.mode,
+                text: c.tts_config.text,
+                voice_id: c.tts_config.voice_id,
+                speed: c.tts_config.speed,
+                pitch: c.tts_config.pitch,
+                volume: c.tts_config.volume,
+                subtitle_sync: c.tts_config.subtitle_sync,
+              }
+            : undefined,
+          trim_config: c.trim_config
+            ? {
+                start_time: c.trim_config.start_time,
+                end_time: c.trim_config.end_time,
+              }
+            : undefined,
+        })),
+        watermark_config: { ...watermarkSettings },
+        intro_outro_config: { ...introOutroSettings },
+        pip_config: { ...pipSettings },
+        filter_config: { ...filterSettings },
+        green_screen_config: { ...chromaKeySettings },
+        sticker_config: { ...stickerSettings },
+        cover_config: { ...coverConfig },
+      }
+      if (loadedTemplateId) {
+        await updateEditingTemplate(loadedTemplateId, payload)
+      } else {
+        await createEditingTemplate(payload)
+      }
+      message.success(loadedTemplateId ? "模板保存成功" : "模板创建成功")
+      setSaveModalOpen(false)
+      loadTemplates()
+    } catch {
+      message.error("保存失败")
+    } finally {
+      setSaveLoading(false)
+    }
+  }
+
+  return {
+    // state
+    templates,
+    categories,
+    loadingTemplates,
+    loadedTemplateId,
+    setLoadedTemplateId,
+    currentMode,
+    setCurrentMode,
+    currentFilter,
+    setCurrentFilter,
+    searchQuery,
+    setSearchQuery,
+    saveModalOpen,
+    setSaveModalOpen,
+    draftName,
+    setDraftName,
+    draftCategory,
+    setDraftCategory,
+    draftTags,
+    setDraftTags,
+    saveLoading,
+    filteredTemplates,
+    currentTemplate,
+    // methods
+    loadTemplates,
+    handleLoadTemplate,
+    handleModeChange,
+    handleOpenSaveModal,
+    handleSave,
+  }
+}
+
+export { FILTER_CATEGORIES }
@@ -0,0 +1,41 @@
+import type { EditingTemplate } from "@/api/editing-planner"
+import type { ClipData } from "../types"
+
+/**
+ * 计算所有片段的总时长
+ */
+export function calculateTotalDuration(clips: ClipData[]): number {
+  return clips.reduce((sum, c) => sum + c.duration, 0)
+}
+
+/**
+ * 获取当前选中的模板
+ */
+export function getCurrentTemplate(
+  templates: EditingTemplate[],
+  loadedTemplateId: string | null,
+): EditingTemplate | undefined {
+  return templates.find((t) => t.id === loadedTemplateId)
+}
+
+/**
+ * 根据分类和搜索词筛选模板
+ */
+export function getFilteredTemplates(
+  templates: EditingTemplate[],
+  currentFilter: string,
+  searchQuery: string,
+): EditingTemplate[] {
+  return templates.filter((t) => {
+    if (currentFilter !== "全部" && t.category !== currentFilter) return false
+    if (searchQuery && !t.name.toLowerCase().includes(searchQuery.toLowerCase())) return false
+    return true
+  })
+}
+
+/**
+ * 获取当前选中的片段
+ */
+export function getSelectedClip(clips: ClipData[], selectedClipId: string | null): ClipData | null {
+  return clips.find((c) => c.id === selectedClipId) || null
+}
@@ -0,0 +1,40 @@
+/**
+ * 智能剪辑页头组件
+ */
+import React from "react"
+import { ThunderboltOutlined } from "@ant-design/icons"
+
+interface GenerateHeaderProps {
+  /** 是否来自模板草稿（URL 带 edit_plan_id） */
+  fromEditPlan?: boolean
+}
+
+const GenerateHeader: React.FC<GenerateHeaderProps> = ({ fromEditPlan }) => {
+  return (
+    <div className="xx-generate-head">
+      <div>
+        <h2>
+          <ThunderboltOutlined style={{ marginRight: 8 }} />
+          智能剪辑
+        </h2>
+        <p>快速生成短视频，支持多种风格和素材组合</p>
+      </div>
+      {fromEditPlan && (
+        <span
+          style={{
+            background: "#dbeafe",
+            color: "#1d4ed8",
+            fontSize: 12,
+            padding: "4px 10px",
+            borderRadius: 999,
+            fontWeight: 600,
+          }}
+        >
+          🎬 来自模板草稿
+        </span>
+      )}
+    </div>
+  )
+}
+
+export default GenerateHeader
@@ -0,0 +1,187 @@
+/**
+ * 智能剪辑右侧生成结果面板
+ */
+import React from "react"
+import { Typography } from "antd"
+import {
+  PlayCircleOutlined,
+  CloseCircleOutlined,
+  DownloadOutlined,
+  ShareAltOutlined,
+} from "@ant-design/icons"
+import type { GeneratedVideo } from "@/api/template-editor"
+import { formatDuration } from "@/api/voice-clone"
+
+const { Text } = Typography
+
+interface GenerateResultPanelProps {
+  /** 是否已生成完成 */
+  generated: boolean
+  /** 是否正在生成中 */
+  generating: boolean
+  /** 生成进度（0-100） */
+  progress: number
+  /** 生成错误信息 */
+  generateError: string | null
+  /** 生成的视频列表 */
+  generatedVideos: GeneratedVideo[]
+  /** 点击视频卡片预览回调 */
+  onVideoPreview: (video: GeneratedVideo) => void
+  /** 下载回调 */
+  onDownload: () => void
+  /** 分享回调 */
+  onShare: () => void
+  /** 前往成片库回调 */
+  onGoToLibrary: () => void
+}
+
+const GenerateResultPanel: React.FC<GenerateResultPanelProps> = ({
+  generated,
+  generating,
+  progress,
+  generateError,
+  generatedVideos,
+  onVideoPreview,
+  onDownload,
+  onShare,
+  onGoToLibrary,
+}) => {
+  return (
+    <div className="xx-generate-result">
+      <div className="xx-result-header">
+        <h3>生成结果</h3>
+        {generated && generatedVideos.length > 0 && (
+          <span className="xx-result-count">{generatedVideos.length} 个视频</span>
+        )}
+      </div>
+
+      {/* 生成中进度 */}
+      {generating && (
+        <div className="xx-result-progress">
+          <div className="xx-progress-circle">
+            <svg viewBox="0 0 80 80">
+              <circle
+                cx="40"
+                cy="40"
+                r="36"
+                fill="none"
+                stroke="var(--border-color)"
+                strokeWidth="6"
+              />
+              <circle
+                cx="40"
+                cy="40"
+                r="36"
+                fill="none"
+                stroke="var(--primary-color)"
+                strokeWidth="6"
+                strokeDasharray={`${Math.round(progress) * 2.26} 226`}
+                strokeLinecap="round"
+                transform="rotate(-90 40 40)"
+              />
+            </svg>
+            <span className="xx-progress-percent">{Math.round(progress)}%</span>
+          </div>
+          <div className="xx-progress-text">
+            <Text strong style={{ fontSize: 14, display: "block", marginBottom: 4 }}>
+              正在生成视频
+            </Text>
+            <Text style={{ fontSize: 12, color: "var(--text-secondary)" }}>
+              AI 正在处理素材，请稍候…
+            </Text>
+          </div>
+        </div>
+      )}
+
+      {/* 生成失败 */}
+      {generateError && !generating && (
+        <div className="xx-result-empty">
+          <CloseCircleOutlined style={{ fontSize: 40, color: "#ff4d4f", marginBottom: 12 }} />
+          <Text strong style={{ display: "block", marginBottom: 4 }}>
+            生成失败
+          </Text>
+          <Text style={{ fontSize: 12, color: "var(--text-secondary)" }}>
+            {typeof generateError === "string" ? generateError : "请重试"}
+          </Text>
+        </div>
+      )}
+
+      {/* 空状态 */}
+      {!generated && !generating && !generateError && (
+        <div className="xx-result-empty">
+          <PlayCircleOutlined
+            style={{ fontSize: 48, color: "var(--text-tertiary)", marginBottom: 12 }}
+          />
+          <Text style={{ color: "var(--text-secondary)", fontSize: 13 }}>
+            完成配置后点击「确认生成」
+          </Text>
+          <Text style={{ color: "var(--text-tertiary)", fontSize: 12, marginTop: 4 }}>
+            生成的视频将在这里展示
+          </Text>
+        </div>
+      )}
+
+      {/* 生成结果卡片列表 */}
+      {generated && generatedVideos.length > 0 && (
+        <div className="xx-video-grid">
+          {generatedVideos.map((video, idx) => (
+            <div
+              key={video.id || idx}
+              className="xx-video-card"
+              onClick={() => onVideoPreview(video)}
+            >
+              <div className="xx-video-thumb">
+                {video.thumbnail_url ? (
+                  <img src={video.thumbnail_url} alt="" />
+                ) : (
+                  <div className="xx-video-thumb-placeholder">
+                    <PlayCircleOutlined style={{ fontSize: 32, opacity: 0.5 }} />
+                  </div>
+                )}
+                <div className="xx-video-play-overlay">
+                  <PlayCircleOutlined style={{ fontSize: 36, color: "#fff" }} />
+                </div>
+                {video.duration && (
+                  <span className="xx-video-duration">{formatDuration(video.duration)}</span>
+                )}
+              </div>
+              <div className="xx-video-info">
+                <div className="xx-video-title">视频 {idx + 1}</div>
+                <div className="xx-video-actions">
+                  <button
+                    className="xx-video-action-btn"
+                    onClick={(e) => {
+                      e.stopPropagation()
+                      onDownload()
+                    }}
+                  >
+                    <DownloadOutlined />
+                  </button>
+                  <button
+                    className="xx-video-action-btn"
+                    onClick={(e) => {
+                      e.stopPropagation()
+                      onShare()
+                    }}
+                  >
+                    <ShareAltOutlined />
+                  </button>
+                </div>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {generated && (
+        <div className="xx-result-footer">
+          <button className="xx-btn xx-btn-ghost xx-btn-block" onClick={onGoToLibrary}>
+            前往成片库 →
+          </button>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default GenerateResultPanel
@@ -0,0 +1,47 @@
+/**
+ * 智能剪辑步骤条组件
+ */
+import React from "react"
+import { STEPS } from "../constants"
+
+interface GenerateStepsBarProps {
+  /** 当前步骤（1-based） */
+  currentStep: number
+  /** 点击已完成步骤的回调（用于回退） */
+  onStepClick?: (step: number) => void
+}
+
+const GenerateStepsBar: React.FC<GenerateStepsBarProps> = ({ currentStep, onStepClick }) => {
+  return (
+    <div className="xx-steps-bar">
+      {STEPS.map((step, idx) => {
+        const isActive = currentStep === step.key
+        const isDone = currentStep > step.key
+        const cls = ["xx-step-item", isActive ? "active" : "", isDone ? "done" : ""]
+          .filter(Boolean)
+          .join(" ")
+        return (
+          <React.Fragment key={step.key}>
+            {idx > 0 && <span className="xx-step-arrow">→</span>}
+            <div
+              className={cls}
+              onClick={() => {
+                // 允许点击已完成的步骤回退
+                if (isDone && onStepClick) {
+                  onStepClick(step.key)
+                }
+              }}
+              role="button"
+              tabIndex={0}
+            >
+              <div className="xx-step-num">{isDone ? "✓" : step.key}</div>
+              <span className="xx-step-label">{step.label}</span>
+            </div>
+          </React.Fragment>
+        )
+      })}
+    </div>
+  )
+}
+
+export default GenerateStepsBar
@@ -0,0 +1,86 @@
+/**
+ * Step 1 模板选择组件
+ */
+import React from "react"
+import type { EditingTemplate } from "@/api/editing-planner"
+import { MODE_GRADIENTS } from "../constants"
+import { useStep1Template } from "../hooks/useStep1Template"
+
+interface Step1TemplateSelectProps {
+  templates: EditingTemplate[]
+  selectedTemplate: string
+  onSelectTemplate: (id: string) => void
+}
+
+const Step1TemplateSelect: React.FC<Step1TemplateSelectProps> = (props) => {
+  const { templates, selectedTemplate, handleSelect, handleKeySelect } = useStep1Template(props)
+
+  return (
+    <div className="xx-form-section">
+      <h3>🎨 选择模板</h3>
+      {templates.length === 0 ? (
+        <div className="xx-empty-state">
+          <p>暂无可用模板</p>
+          <p style={{ fontSize: 13, color: "var(--text-tertiary)" }}>
+            请先在「模板编辑器」中创建模板
+          </p>
+        </div>
+      ) : (
+        <div className="xx-choice-list">
+          {templates.map((tpl) => (
+            <div
+              key={tpl.id}
+              className={`xx-choice-item ${selectedTemplate === tpl.id ? "selected" : ""}`}
+              onClick={() => handleSelect(tpl.id)}
+              role="button"
+              tabIndex={0}
+              aria-pressed={selectedTemplate === tpl.id}
+              onKeyDown={(e) => handleKeySelect(e, tpl.id)}
+            >
+              <span className="xx-choice-check">✓</span>
+              <div
+                className="xx-choice-thumb"
+                style={{
+                  background: MODE_GRADIENTS[tpl.mode] || MODE_GRADIENTS.pip,
+                }}
+              >
+                🎬
+              </div>
+              <h4>{tpl.name}</h4>
+              <p>
+                {tpl.estimated_duration}s · {tpl.segments.length}片段
+              </p>
+              {tpl.tags.length > 0 && (
+                <div
+                  style={{
+                    display: "flex",
+                    gap: 4,
+                    flexWrap: "wrap",
+                    marginTop: 4,
+                  }}
+                >
+                  {tpl.tags.map((tag) => (
+                    <span
+                      key={tag}
+                      style={{
+                        fontSize: 11,
+                        padding: "1px 6px",
+                        borderRadius: 6,
+                        background: "var(--bg-secondary)",
+                        color: "var(--text-secondary)",
+                      }}
+                    >
+                      {tag}
+                    </span>
+                  ))}
+                </div>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default Step1TemplateSelect
@@ -0,0 +1,95 @@
+/**
+ * Step 2 素材选择组件
+ */
+import React from "react"
+import { useStep2Materials } from "../hooks/useStep2Materials"
+import MaterialModeTabs from "./material/MaterialModeTabs"
+import ManualMaterialList from "./material/ManualMaterialList"
+import SmartMatchInput from "./material/SmartMatchInput"
+import SmartMatchResults from "./material/SmartMatchResults"
+
+interface Step2MaterialSelectProps {
+  materialMode: "manual" | "auto"
+  onMaterialModeChange: (mode: "manual" | "auto") => void
+  selectedMaterials: string[]
+  onSelectedMaterialsChange: (ids: string[]) => void
+  smartSelectedIds: string[]
+  onSmartSelectedIdsChange: (ids: string[]) => void
+}
+
+const Step2MaterialSelect: React.FC<Step2MaterialSelectProps> = (props) => {
+  const m = useStep2Materials(props)
+
+  return (
+    <div className="xx-form-section">
+      <h3>📦 选择素材</h3>
+
+      <MaterialModeTabs mode={m.materialMode} onModeChange={m.onMaterialModeChange} />
+
+      <div className="xx-form-field" style={{ marginTop: 12 }}>
+        <label>选择视频库</label>
+        <select
+          value={m.selectedLibraryId}
+          onChange={(e) => m.setSelectedLibraryId(e.target.value)}
+        >
+          {m.libraries.map((lib) => (
+            <option key={lib.id} value={lib.id}>
+              {lib.name}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      {m.materialMode === "manual" && (
+        <>
+          <div
+            style={{
+              marginTop: 14,
+              display: "flex",
+              alignItems: "center",
+              gap: 10,
+            }}
+          >
+            <span className="xx-pill xx-pill-ok">已选 {m.selectedMaterials.length} 个素材</span>
+          </div>
+
+          <ManualMaterialList
+            materials={m.materials}
+            materialsLoading={m.materialsLoading}
+            selectedMaterials={m.selectedMaterials}
+            onToggle={m.handleToggleMaterial}
+          />
+        </>
+      )}
+
+      {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}
+            onRefresh={m.handleRefreshMatch}
+            materialsCount={m.materials.items.length}
+            loading={m.materialsLoading}
+          />
+
+          <SmartMatchResults
+            results={m.smartMatchedResults}
+            selectedIds={m.smartSelectedIds}
+            matching={m.smartMatching}
+            hasMatched={m.hasMatched}
+            onToggle={m.handleToggleSmartSelect}
+            onSelectAll={m.handleSelectAllMatched}
+            onClear={m.handleClearSmartSelect}
+            formatDuration={m.formatDuration}
+            selectedTotalDuration={m.smartSelectedTotalDuration}
+          />
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default Step2MaterialSelect
@@ -0,0 +1,57 @@
+/**
+ * Step 3 生成预览组件
+ */
+import React from "react"
+import { CheckCircleFilled } from "@ant-design/icons"
+import type { EditingTemplate } from "@/api/editing-planner"
+import { useStep3Preview } from "../hooks/useStep3Preview"
+
+interface Step3GeneratePreviewProps {
+  templates: EditingTemplate[]
+  selectedTemplate: string
+  materialMode: "manual" | "auto"
+  selectedMaterials: string[]
+  smartSelectedIds: string[]
+  duration: number
+  videoRatio: string
+}
+
+const Step3GeneratePreview: React.FC<Step3GeneratePreviewProps> = (props) => {
+  const { templateName, materialCount, duration, videoRatio } = useStep3Preview(props)
+
+  return (
+    <div className="xx-form-section">
+      <h3>🎬 生成预览</h3>
+      <div className="xx-preview-tip">
+        <CheckCircleFilled style={{ color: "#52c41a", marginRight: 8 }} />
+        <span>素材已选好，AI 将为您智能匹配剪辑方案</span>
+      </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">{duration} 秒</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">
+          💡 点击「下一步」进入标题设置，AI 将根据素材内容为您推荐标题
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default Step3GeneratePreview
@@ -0,0 +1,108 @@
+/**
+ * Step 4 标题设置组件
+ */
+import React from "react"
+import { Select } from "antd"
+import { POSITION_OPTIONS, FONT_OPTIONS } from "../constants"
+import type { TitleSettings } from "../types"
+import { useStep4Title } from "../hooks/useStep4Title"
+import AiTitleGenerator from "./title/AiTitleGenerator"
+import TitleStylePanel from "./title/TitleStylePanel"
+
+interface Step4TitleSettingsProps {
+  titleSettings: TitleSettings
+  onTitleSettingsChange: (settings: TitleSettings) => void
+}
+
+const Step4TitleSettings: React.FC<Step4TitleSettingsProps> = (props) => {
+  const t = useStep4Title(props)
+
+  return (
+    <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}
+      />
+
+      <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>
+
+      {!t.titleSettings.aiAutoSelect && (
+        <>
+          <div className="xx-form-field">
+            <label>从标题库选择</label>
+            <Select
+              placeholder="请选择标题…"
+              allowClear
+              showSearch
+              style={{ width: "100%" }}
+              value={t.titleSettings.title || undefined}
+              onChange={(val) => t.updateTitle(val || "")}
+              options={t.userTitles.map((ut) => ({
+                label: ut.content,
+                value: ut.content,
+              }))}
+              filterOption={(input, option) =>
+                ((option?.label as string) || "").toLowerCase().includes(input.toLowerCase())
+              }
+              notFoundContent={
+                t.userTitles.length === 0 ? (
+                  <span style={{ color: "var(--text-tertiary)", fontSize: 13 }}>
+                    标题库为空，请前往「标题管理」添加
+                  </span>
+                ) : null
+              }
+            />
+          </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}
+          />
+        </>
+      )}
+    </div>
+  )
+}
+
+export default Step4TitleSettings
@@ -0,0 +1,137 @@
+/**
+ * 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"
+
+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
+}
+
+const Step5VoiceSelect: React.FC<Step5VoiceSelectProps> = (props) => {
+  const v = useStep5Voice(props)
+
+  return (
+    <div className="xx-form-section">
+      <h3>🎙️ 选择配音</h3>
+
+      <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}
+      />
+
+      <div className="xx-divider">
+        <span>全部音色</span>
+      </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}
+          CLONE_STATUS_CONFIG={v.CLONE_STATUS_CONFIG}
+          formatDuration={v.formatDuration}
+        />
+      )}
+    </div>
+  )
+}
+
+export default Step5VoiceSelect
@@ -0,0 +1,187 @@
+/**
+ * Step 6 封面设置组件
+ */
+import React from "react"
+import type { CoverConfig } from "../../editing-planner/types"
+import { useStep6Cover } from "../hooks/useStep6Cover"
+
+interface Step6CoverSettingsProps {
+  coverSettings: CoverConfig
+  onCoverSettingsChange: (settings: CoverConfig) => void
+  duration: number
+}
+
+const Step6CoverSettings: React.FC<Step6CoverSettingsProps> = (props) => {
+  const {
+    coverSettings,
+    formatTime,
+    toggleEnabled,
+    setMode,
+    setFrameTime,
+    handleUpload,
+    totalDuration,
+    COVER_MODE_LABELS,
+    COVER_MODE_ICONS,
+  } = useStep6Cover(props)
+
+  return (
+    <div className="xx-form-section">
+      <h3>🖼️ 选择封面</h3>
+
+      {/* 启用开关 */}
+      <div className="xx-cover-header">
+        <span className="xx-cover-header-label">启用自定义封面</span>
+        <label className="xx-switch">
+          <input
+            type="checkbox"
+            checked={coverSettings.enabled}
+            onChange={(e) => toggleEnabled(e.target.checked)}
+          />
+          <span className="xx-switch-slider" />
+        </label>
+      </div>
+
+      {coverSettings.enabled && (
+        <>
+          {/* 模式选择 */}
+          <div className="xx-section-title">封面来源</div>
+          <div className="xx-cover-mode-tabs">
+            {(["auto", "frame", "upload"] as const).map((m) => (
+              <button
+                key={m}
+                className={`xx-cover-mode-tab${coverSettings.mode === m ? " active" : ""}`}
+                onClick={() => setMode(m)}
+              >
+                <span className="xx-cover-mode-icon">{COVER_MODE_ICONS[m]}</span>
+                <span className="xx-cover-mode-label">{COVER_MODE_LABELS[m]}</span>
+              </button>
+            ))}
+          </div>
+
+          {/* 智能封面 */}
+          {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>
+              </div>
+            </div>
+          )}
+
+          {/* 抽帧选封面 */}
+          {coverSettings.mode === "frame" && (
+            <div className="xx-cover-frame">
+              <div className="xx-cover-frame-preview">
+                <div className="xx-cover-frame-placeholder">
+                  <span className="xx-cover-frame-icon">🎞️</span>
+                  <span className="xx-cover-frame-time">
+                    {formatTime(coverSettings.frame_time)}
+                  </span>
+                </div>
+              </div>
+              <div className="xx-cover-frame-slider">
+                <div className="xx-cover-frame-slider-header">
+                  <span>拖动选择封面帧</span>
+                  <span className="xx-cover-frame-value">
+                    {formatTime(coverSettings.frame_time)}
+                  </span>
+                </div>
+                <input
+                  type="range"
+                  min={0}
+                  max={Math.max(totalDuration, 1)}
+                  step={0.1}
+                  value={coverSettings.frame_time}
+                  onChange={(e) => setFrameTime(Number(e.target.value))}
+                  className="xx-cover-range"
+                />
+                <div className="xx-cover-frame-range">
+                  <span>00:00</span>
+                  <span>{formatTime(totalDuration)}</span>
+                </div>
+              </div>
+              <div className="xx-cover-frame-quick">
+                <span className="xx-cover-quick-label">快捷选帧：</span>
+                {[0, 0.25, 0.5, 0.75].map((ratio) => {
+                  const t = totalDuration * ratio
+                  return (
+                    <button
+                      key={ratio}
+                      className="xx-cover-quick-btn"
+                      onClick={() => setFrameTime(t)}
+                    >
+                      {formatTime(t)}
+                    </button>
+                  )
+                })}
+              </div>
+            </div>
+          )}
+
+          {/* 上传封面 */}
+          {coverSettings.mode === "upload" && (
+            <div className="xx-cover-upload">
+              <div
+                className="xx-cover-upload-area"
+                onClick={() => {
+                  const input = document.getElementById("cover-upload-input")
+                  input?.click()
+                }}
+              >
+                {coverSettings.upload_url ? (
+                  <div className="xx-cover-upload-preview">
+                    <img src={coverSettings.upload_url} alt="封面预览" />
+                    <div className="xx-cover-upload-overlay">点击更换</div>
+                  </div>
+                ) : (
+                  <div className="xx-cover-upload-placeholder">
+                    <span style={{ fontSize: 32 }}>📤</span>
+                    <span className="xx-cover-upload-text">点击上传封面图片</span>
+                    <span className="xx-cover-upload-hint">支持 JPG / PNG，建议 16:9 比例</span>
+                  </div>
+                )}
+                <input
+                  id="cover-upload-input"
+                  type="file"
+                  accept="image/*"
+                  style={{ display: "none" }}
+                  onChange={(e) => {
+                    const file = e.target.files?.[0]
+                    if (file) {
+                      handleUpload(file)
+                    }
+                  }}
+                />
+              </div>
+            </div>
+          )}
+
+          {/* 封面预览 */}
+          <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" />
+            ) : (
+              <div className="xx-cover-preview-placeholder">
+                <span style={{ fontSize: 28 }}>🖼️</span>
+                <span>
+                  {coverSettings.mode === "auto"
+                    ? "AI 智能选择"
+                    : coverSettings.mode === "frame"
+                      ? `帧 ${formatTime(coverSettings.frame_time)}`
+                      : "未上传封面"}
+                </span>
+              </div>
+            )}
+            <div className="xx-cover-preview-ratio">16:9</div>
+          </div>
+        </>
+      )}
+    </div>
+  )
+}
+
+export default Step6CoverSettings
@@ -0,0 +1,194 @@
+/**
+ * Step 7 确认生成组件
+ */
+import React from "react"
+import {
+  LoadingOutlined,
+  CheckCircleFilled,
+  CloseCircleOutlined,
+  MinusOutlined,
+  PlusOutlined,
+} from "@ant-design/icons"
+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 { useStep7Generate } from "../hooks/useStep7Generate"
+
+interface Step7ConfirmGenerateProps {
+  templates: EditingTemplate[]
+  selectedTemplate: string
+  materialMode: "manual" | "auto"
+  selectedMaterials: string[]
+  smartSelectedIds: string[]
+  title: string
+  voiceMode: "preset" | "custom" | "clone"
+  selectedVoice: string
+  selectedClonedVoice: string
+  presetVoices: PresetVoiceItem[]
+  clonedVoices: VoiceClone[]
+  coverSettings: CoverConfig
+  generateCount: number
+  onGenerateCountChange: (count: number) => void
+  generating: boolean
+  generated: boolean
+  generateError: string | null
+  progress: number
+  generatedVideos: GeneratedVideo[]
+  onRetry: () => void
+  onDismissError: () => void
+}
+
+const Step7ConfirmGenerate: React.FC<Step7ConfirmGenerateProps> = (props) => {
+  const {
+    templateName,
+    materialSummary,
+    title,
+    voiceName,
+    coverSummary,
+    generateCount,
+    handleDecrement,
+    handleIncrement,
+    generating,
+    generated,
+    generateError,
+    progress,
+    generatedVideos,
+    getGenerationPhase,
+    handleScrollToPreview,
+  } = useStep7Generate(props)
+
+  const { onRetry, onDismissError } = props
+
+  return (
+    <div className="xx-form-section">
+      <h3>✨ 确认生成</h3>
+      <div className="xx-summary-card">
+        <div className="xx-summary-row">
+          <span className="xx-summary-label">模板</span>
+          <span className="xx-summary-value">{templateName}</span>
+        </div>
+        <div className="xx-summary-row">
+          <span className="xx-summary-label">素材</span>
+          <span className="xx-summary-value">{materialSummary}</span>
+        </div>
+        <div className="xx-summary-row">
+          <span className="xx-summary-label">标题</span>
+          <span className="xx-summary-value">{title || "未选择"}</span>
+        </div>
+        <div className="xx-summary-row">
+          <span className="xx-summary-label">配音</span>
+          <span className="xx-summary-value">{voiceName}</span>
+        </div>
+        <div className="xx-summary-row">
+          <span className="xx-summary-label">封面</span>
+          <span className="xx-summary-value">{coverSummary}</span>
+        </div>
+        <div className="xx-summary-row">
+          <span className="xx-summary-label">生成数量</span>
+          <span className="xx-summary-value">
+            <div className="xx-count-stepper">
+              <button
+                className="xx-count-stepper-btn"
+                disabled={generateCount <= 1 || generating}
+                onClick={handleDecrement}
+              >
+                <MinusOutlined />
+              </button>
+              <span className="xx-count-stepper-value">{generateCount}</span>
+              <button
+                className="xx-count-stepper-btn"
+                disabled={generateCount >= 10 || generating}
+                onClick={handleIncrement}
+              >
+                <PlusOutlined />
+              </button>
+              <span className="xx-count-stepper-hint">条视频</span>
+            </div>
+          </span>
+        </div>
+      </div>
+
+      {/* 生成进度 / 结果反馈 */}
+      {(generating || generated || generateError) && (
+        <div style={{ marginTop: 16 }}>
+          {generating && (
+            <div className="xx-gen-progress-card">
+              <div className="xx-gen-progress-header">
+                <div className="xx-gen-progress-icon">
+                  <LoadingOutlined />
+                </div>
+                <div className="xx-gen-progress-info">
+                  <div className="xx-gen-progress-phase">
+                    {getGenerationPhase(progress).icon} {getGenerationPhase(progress).label}
+                  </div>
+                  <div className="xx-gen-progress-sub">预计还需 1-2 分钟，请稍候…</div>
+                </div>
+                <div className="xx-gen-progress-percent">{Math.round(progress)}%</div>
+              </div>
+              <div className="xx-gen-progress-bar">
+                <div
+                  className="xx-gen-progress-bar-fill"
+                  style={{ width: `${Math.min(Math.round(progress), 100)}%` }}
+                />
+              </div>
+              <div className="xx-gen-progress-tip">
+                💡 生成过程中可以切换到其他页面操作，完成后会自动通知
+              </div>
+            </div>
+          )}
+          {generated && !generating && (
+            <div className="xx-gen-success-card">
+              <div className="xx-gen-success-icon">
+                <CheckCircleFilled style={{ fontSize: 32, color: "#52c41a" }} />
+              </div>
+              <div className="xx-gen-success-info">
+                <div className="xx-gen-success-title">视频生成完成！</div>
+                <div className="xx-gen-success-sub">
+                  共生成 {generatedVideos.length} 条视频，可在右侧预览或前往成片库查看
+                </div>
+              </div>
+              <button
+                type="button"
+                className="xx-btn xx-btn-primary xx-btn-sm"
+                onClick={handleScrollToPreview}
+              >
+                查看结果
+              </button>
+            </div>
+          )}
+          {generateError && !generating && (
+            <div className="xx-gen-error-card">
+              <div className="xx-gen-error-icon">
+                <CloseCircleOutlined style={{ fontSize: 28, color: "#ef4444" }} />
+              </div>
+              <div className="xx-gen-error-info">
+                <div className="xx-gen-error-title">生成失败</div>
+                <div className="xx-gen-error-msg">
+                  {typeof generateError === "string"
+                    ? generateError
+                    : JSON.stringify(generateError)}
+                </div>
+              </div>
+              <div style={{ display: "flex", gap: 8 }}>
+                <button type="button" className="xx-btn xx-btn-primary xx-btn-sm" onClick={onRetry}>
+                  🔄 重试
+                </button>
+                <button
+                  type="button"
+                  className="xx-btn xx-btn-ghost xx-btn-sm"
+                  onClick={onDismissError}
+                >
+                  知道了
+                </button>
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default Step7ConfirmGenerate
@@ -0,0 +1,84 @@
+/**
+ * 手动选择素材列表
+ */
+import React from "react"
+import { Typography } from "antd"
+import type { AssetItem } from "@/api/assets"
+
+const { Text } = Typography
+
+interface ManualMaterialListProps {
+  materials: { items: AssetItem[]; total: number }
+  materialsLoading: boolean
+  selectedMaterials: string[]
+  onToggle: (materialId: string) => void
+}
+
+const ManualMaterialList: React.FC<ManualMaterialListProps> = ({
+  materials,
+  materialsLoading,
+  selectedMaterials,
+  onToggle,
+}) => {
+  return (
+    <div style={{ marginTop: 14 }}>
+      {materialsLoading ? (
+        <Text style={{ color: "var(--text-secondary)", padding: "16px 0" }}>加载素材中…</Text>
+      ) : materials.items.length === 0 ? (
+        <Text style={{ color: "var(--text-secondary)", padding: "16px 0" }}>
+          暂无素材，请先在视频库中上传
+        </Text>
+      ) : (
+        <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
+          {materials.items.map((m) => {
+            const checked = selectedMaterials.includes(m.id)
+            return (
+              <label
+                key={m.id}
+                style={{
+                  display: "flex",
+                  alignItems: "center",
+                  gap: 10,
+                  padding: "8px 12px",
+                  background: checked ? "var(--primary-soft, #eef2ff)" : "#f8fafc",
+                  borderRadius: 10,
+                  cursor: "pointer",
+                  border: checked
+                    ? "1px solid var(--primary-color, #4f46e5)"
+                    : "1px solid transparent",
+                  transition: "all 0.15s ease",
+                }}
+              >
+                <input
+                  type="checkbox"
+                  checked={checked}
+                  onChange={() => onToggle(m.id)}
+                  style={{ accentColor: "var(--primary-color, #4f46e5)" }}
+                />
+                <span
+                  style={{
+                    fontSize: 13,
+                    color: "var(--text-primary)",
+                    flex: 1,
+                  }}
+                >
+                  {m.name}
+                </span>
+                <span
+                  style={{
+                    fontSize: 11,
+                    color: "var(--text-tertiary, #94a3b8)",
+                  }}
+                >
+                  {m.mime_type.split("/")[1].toUpperCase()}
+                </span>
+              </label>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default ManualMaterialList
@@ -0,0 +1,32 @@
+/**
+ * 素材模式切换 Tab
+ */
+import React from "react"
+
+interface MaterialModeTabsProps {
+  mode: "manual" | "auto"
+  onModeChange: (mode: "manual" | "auto") => void
+}
+
+const MaterialModeTabs: React.FC<MaterialModeTabsProps> = ({ mode, onModeChange }) => {
+  return (
+    <div className="xx-material-mode-tabs">
+      <button
+        className={`xx-material-mode-tab ${mode === "manual" ? "active" : ""}`}
+        onClick={() => onModeChange("manual")}
+        type="button"
+      >
+        手动选择素材
+      </button>
+      <button
+        className={`xx-material-mode-tab ${mode === "auto" ? "active" : ""}`}
+        onClick={() => onModeChange("auto")}
+        type="button"
+      >
+        选择视频库自动匹配
+      </button>
+    </div>
+  )
+}
+
+export default MaterialModeTabs
@@ -0,0 +1,60 @@
+/**
+ * 单个智能匹配卡片
+ */
+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
+  selected: boolean
+  onClick: () => void
+  formatDuration: (seconds: number) => string
+}
+
+const SmartMatchCard: React.FC<SmartMatchCardProps> = ({
+  result,
+  selected,
+  onClick,
+  formatDuration,
+}) => {
+  const { asset, matchScore, matchReason } = result
+  return (
+    <div className={`xx-smart-match-card ${selected ? "selected" : ""}`} onClick={onClick}>
+      {/* 缩略图 */}
+      <div className="xx-smart-match-thumb">
+        {asset.thumbnail_url ? (
+          <img src={asset.thumbnail_url} alt={asset.name} />
+        ) : (
+          <div className="xx-smart-match-thumb-placeholder">
+            <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" }} />
+          </div>
+        )}
+        {asset.duration && (
+          <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>
+  )
+}
+
+export default SmartMatchCard
@@ -0,0 +1,80 @@
+/**
+ * 智能匹配输入区
+ * textarea + 提示 + 按钮组
+ */
+import React from "react"
+import { LoadingOutlined } from "@ant-design/icons"
+
+interface SmartMatchInputProps {
+  inputValue: string
+  onInputChange: (value: string) => void
+  matching: boolean
+  onMatch: () => void
+  hasMatched: boolean
+  onRefresh: () => void
+  materialsCount: number
+  loading: boolean
+}
+
+const SmartMatchInput: React.FC<SmartMatchInputProps> = ({
+  inputValue,
+  onInputChange,
+  matching,
+  onMatch,
+  hasMatched,
+  onRefresh,
+  materialsCount,
+  loading,
+}) => {
+  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">
+        <span className="xx-smart-match-tip">
+          {loading ? "扫描视频库中…" : `当前视频库共 ${materialsCount} 个素材可供匹配`}
+        </span>
+        <div style={{ display: "flex", gap: 8 }}>
+          {hasMatched && (
+            <button
+              type="button"
+              className="xx-btn xx-btn-ghost xx-btn-sm"
+              onClick={onRefresh}
+              disabled={matching || loading}
+            >
+              🔄 换一批
+            </button>
+          )}
+          <button
+            type="button"
+            className="xx-btn xx-btn-primary xx-btn-sm"
+            onClick={onMatch}
+            disabled={matching || loading || !inputValue.trim()}
+          >
+            {matching ? (
+              <>
+                <LoadingOutlined style={{ marginRight: 6 }} />
+                匹配中…
+              </>
+            ) : (
+              "✨ 智能匹配"
+            )}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default SmartMatchInput
@@ -0,0 +1,114 @@
+/**
+ * 智能匹配结果区（含加载/空状态/已选汇总）
+ */
+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[]
+  selectedIds: string[]
+  matching: boolean
+  hasMatched: boolean
+  onToggle: (assetId: string) => void
+  onSelectAll: () => void
+  onClear: () => void
+  formatDuration: (seconds: number) => string
+  selectedTotalDuration: number
+}
+
+const SmartMatchResults: React.FC<SmartMatchResultsProps> = ({
+  results,
+  selectedIds,
+  matching,
+  hasMatched,
+  onToggle,
+  onSelectAll,
+  onClear,
+  formatDuration,
+  selectedTotalDuration,
+}) => {
+  // 匹配中状态
+  if (matching) {
+    return (
+      <div className="xx-smart-match-loading">
+        <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-tertiary)", fontSize: 12, marginTop: 4 }}>
+          正在根据描述从视频库中匹配最合适的素材
+        </div>
+      </div>
+    )
+  }
+
+  // 未匹配状态提示
+  if (!hasMatched) {
+    return (
+      <div className="xx-smart-match-empty">
+        <div style={{ fontSize: 36, marginBottom: 8 }}>💡</div>
+        <div style={{ color: "var(--text-secondary)", fontSize: 13 }}>
+          输入视频内容描述，点击「智能匹配」让 AI 帮你选素材
+        </div>
+      </div>
+    )
+  }
+
+  // 无结果
+  if (results.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>
+          <div className="xx-smart-match-results-actions">
+            <button type="button" className="xx-link-btn" onClick={onSelectAll}>
+              全选
+            </button>
+            <span style={{ color: "var(--border-color)" }}>|</span>
+            <button type="button" className="xx-link-btn" onClick={onClear}>
+              清空
+            </button>
+          </div>
+        </div>
+        <div className="xx-smart-match-grid">
+          {results.map((result) => {
+            const isSelected = selectedIds.includes(result.asset.id)
+            return (
+              <SmartMatchCard
+                key={result.asset.id}
+                result={result}
+                selected={isSelected}
+                onClick={() => onToggle(result.asset.id)}
+                formatDuration={formatDuration}
+              />
+            )
+          })}
+        </div>
+      </div>
+
+      {/* 已选素材汇总 */}
+      {selectedIds.length > 0 && (
+        <div className="xx-smart-match-summary">
+          <div className="xx-smart-match-summary-header">
+            <span className="xx-pill xx-pill-ok">已选 {selectedIds.length} 个素材</span>
+            <span style={{ color: "var(--text-tertiary)", fontSize: 12 }}>
+              预计总时长约 {selectedTotalDuration.toFixed(0)} 秒
+            </span>
+          </div>
+        </div>
+      )}
+    </>
+  )
+}
+
+export default SmartMatchResults
@@ -0,0 +1,35 @@
+/**
+ * 单个 AI 标题卡片
+ */
+import React from "react"
+import { CheckCircleFilled } from "@ant-design/icons"
+
+interface AiTitleCardProps {
+  title: string
+  highlight: string
+  style: "catchy" | "emotional" | "informative"
+  selected: boolean
+  onClick: () => void
+}
+
+const AiTitleCard: React.FC<AiTitleCardProps> = ({
+  title,
+  highlight,
+  style,
+  selected,
+  onClick,
+}) => {
+  return (
+    <div className={`xx-ai-title-card ${selected ? "selected" : ""} ${style}`} onClick={onClick}>
+      <div className="xx-ai-title-card-text">{title}</div>
+      <div className="xx-ai-title-card-tag">{highlight}</div>
+      {selected && (
+        <div className="xx-ai-title-card-check">
+          <CheckCircleFilled style={{ color: "#fff", fontSize: 14 }} />
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default AiTitleCard
@@ -0,0 +1,105 @@
+/**
+ * AI 智能生成标题
+ * 输入框 + 生成按钮 + 结果列表 + 加载状态
+ */
+import React from "react"
+import { LoadingOutlined } from "@ant-design/icons"
+import AiTitleCard from "./AiTitleCard"
+
+interface AiTitleItem {
+  title: string
+  highlight: string
+  style: "catchy" | "emotional" | "informative"
+}
+
+interface AiTitleGeneratorProps {
+  inputValue: string
+  onInputChange: (value: string) => void
+  generating: boolean
+  onGenerate: () => void
+  results: AiTitleItem[]
+  hasGenerated: boolean
+  onSelect: (title: string) => void
+  selectedTitle: string
+  onRefresh: () => void
+}
+
+const AiTitleGenerator: React.FC<AiTitleGeneratorProps> = ({
+  inputValue,
+  onInputChange,
+  generating,
+  onGenerate,
+  results,
+  hasGenerated,
+  onSelect,
+  selectedTitle,
+  onRefresh,
+}) => {
+  return (
+    <div className="xx-ai-title-section">
+      <div className="xx-ai-title-header">
+        <span className="xx-ai-title-label">✨ AI 智能生成标题</span>
+      </div>
+      <div className="xx-ai-title-input-row">
+        <input
+          className="xx-ai-title-input"
+          placeholder="输入视频内容描述或关键词，如：职场成长、副业赚钱…"
+          value={inputValue}
+          onChange={(e) => onInputChange(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === "Enter") onGenerate()
+          }}
+        />
+        <button
+          type="button"
+          className="xx-btn xx-btn-primary"
+          onClick={onGenerate}
+          disabled={generating || !inputValue.trim()}
+        >
+          {generating ? (
+            <>
+              <LoadingOutlined style={{ marginRight: 6 }} />
+              生成中
+            </>
+          ) : (
+            "生成标题"
+          )}
+        </button>
+      </div>
+
+      {/* 生成结果 */}
+      {hasGenerated && !generating && results.length > 0 && (
+        <div className="xx-ai-title-results">
+          <div className="xx-ai-title-results-header">
+            <span className="xx-ai-title-results-count">为你生成 {results.length} 个标题</span>
+            <button type="button" className="xx-link-btn" onClick={onRefresh} disabled={generating}>
+              🔄 换一批
+            </button>
+          </div>
+          <div className="xx-ai-title-list">
+            {results.map((item, idx) => (
+              <AiTitleCard
+                key={idx}
+                title={item.title}
+                highlight={item.highlight}
+                style={item.style}
+                selected={selectedTitle === item.title}
+                onClick={() => onSelect(item.title)}
+              />
+            ))}
+          </div>
+        </div>
+      )}
+
+      {/* 生成中 */}
+      {generating && (
+        <div className="xx-ai-title-loading">
+          <LoadingOutlined style={{ color: "var(--primary-color)", marginRight: 8 }} />
+          AI 正在为你创作标题…
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default AiTitleGenerator
@@ -0,0 +1,41 @@
+/**
+ * 标题预设样式网格
+ */
+import React from "react"
+
+interface TitlePresetItem {
+  key: string
+  label: string
+  previewStyle: React.CSSProperties
+}
+
+interface TitlePresetsGridProps {
+  presets: TitlePresetItem[]
+  activePreset: string | null
+  onApply: (presetKey: string) => void
+}
+
+const TitlePresetsGrid: React.FC<TitlePresetsGridProps> = ({ presets, activePreset, onApply }) => {
+  return (
+    <div className="xx-title-presets-grid">
+      {presets.map((p) => {
+        const isActive = activePreset === p.key
+        return (
+          <button
+            key={p.key}
+            className={`xx-title-preset-card${isActive ? " active" : ""}`}
+            onClick={() => onApply(p.key)}
+            title={p.label}
+          >
+            <span className="xx-title-preset-preview-text" style={p.previewStyle}>
+              标题
+            </span>
+            <span className="xx-title-preset-card-label">{p.label}</span>
+          </button>
+        )
+      })}
+    </div>
+  )
+}
+
+export default TitlePresetsGrid
@@ -0,0 +1,151 @@
+/**
+ * 标题样式设置区
+ * 位置/字体/字号/样式按钮/预设
+ */
+import React from "react"
+import type { TitleSettings } from "../../types"
+import TitlePresetsGrid from "./TitlePresetsGrid"
+
+interface PositionOption {
+  value: string
+  label: string
+}
+
+interface TitlePresetItem {
+  key: string
+  label: string
+  previewStyle: React.CSSProperties
+}
+
+interface TitleStylePanelProps {
+  settings: TitleSettings
+  onUpdatePosition: (position: string) => void
+  onUpdateFont: (font: string) => void
+  onUpdateSize: (size: number) => void
+  onToggleBold: () => void
+  onToggleItalic: () => void
+  onToggleStroke: () => void
+  onToggleShadow: () => void
+  onApplyPreset: (presetKey: string) => void
+  activePreset: string | null
+  titlePresets: TitlePresetItem[]
+  POSITION_OPTIONS: PositionOption[]
+  FONT_OPTIONS: string[]
+}
+
+const TitleStylePanel: React.FC<TitleStylePanelProps> = ({
+  settings,
+  onUpdatePosition,
+  onUpdateFont,
+  onUpdateSize,
+  onToggleBold,
+  onToggleItalic,
+  onToggleStroke,
+  onToggleShadow,
+  onApplyPreset,
+  activePreset,
+  titlePresets,
+  POSITION_OPTIONS,
+  FONT_OPTIONS,
+}) => {
+  return (
+    <div className="xx-title-style-section">
+      <h4 className="xx-section-subtitle">标题样式</h4>
+
+      {/* 位置 + 字体 一行 */}
+      <div className="xx-title-style-row">
+        <div className="xx-form-field xx-half-field">
+          <label>位置</label>
+          <select
+            className="xx-form-select"
+            value={settings.position}
+            onChange={(e) => onUpdatePosition(e.target.value)}
+          >
+            {POSITION_OPTIONS.map((opt) => (
+              <option key={opt.value} value={opt.value}>
+                {opt.label}
+              </option>
+            ))}
+          </select>
+        </div>
+        <div className="xx-form-field xx-half-field">
+          <label>字体</label>
+          <select
+            className="xx-form-select"
+            value={settings.font}
+            onChange={(e) => onUpdateFont(e.target.value)}
+          >
+            {FONT_OPTIONS.map((f) => (
+              <option key={f} value={f}>
+                {f}
+              </option>
+            ))}
+          </select>
+        </div>
+      </div>
+
+      {/* 字号滑块 */}
+      <div className="xx-form-field">
+        <div className="xx-field-label-row">
+          <label>字号</label>
+          <span className="xx-field-value">{settings.size}px</span>
+        </div>
+        <input
+          className="xx-slider"
+          type="range"
+          min={12}
+          max={48}
+          value={settings.size}
+          onChange={(e) => onUpdateSize(Number(e.target.value))}
+        />
+      </div>
+
+      {/* 预设样式 */}
+      <div className="xx-form-field">
+        <label>预设样式</label>
+        <TitlePresetsGrid
+          presets={titlePresets}
+          activePreset={activePreset}
+          onApply={onApplyPreset}
+        />
+      </div>
+
+      {/* 样式按钮：粗体/斜体/描边/阴影 */}
+      <div className="xx-form-field">
+        <label>样式</label>
+        <div className="xx-style-btns">
+          <button
+            className={`xx-style-btn ${settings.bold ? "active" : ""}`}
+            onClick={onToggleBold}
+            title="粗体"
+          >
+            <b>B</b>
+          </button>
+          <button
+            className={`xx-style-btn ${settings.italic ? "active" : ""}`}
+            onClick={onToggleItalic}
+            title="斜体"
+          >
+            <i>I</i>
+          </button>
+          <button
+            className={`xx-style-btn ${settings.stroke ? "active" : ""}`}
+            onClick={onToggleStroke}
+            title="描边"
+          >
+            S
+          </button>
+          <button
+            className={`xx-style-btn ${settings.shadow ? "active" : ""}`}
+            onClick={onToggleShadow}
+            title="阴影"
+          >
+            ☁
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default TitleStylePanel
@@ -0,0 +1,132 @@
+/**
+ * 克隆声音展开区域
+ * 克隆按钮、轮询提示、已克隆列表、空状态
+ */
+import React from "react"
+import { Typography } from "antd"
+import { ThunderboltOutlined, AudioOutlined, CheckCircleFilled } from "@ant-design/icons"
+import type { VoiceClone } from "@/api/voice-clone"
+
+const { Text } = Typography
+
+interface CloneVoiceSectionProps {
+  clonedVoices: VoiceClone[]
+  hasProcessing: boolean
+  selectedClonedVoice: string
+  onSelect: (voiceId: string) => void
+  onOpenCloneModal: () => void
+  CLONE_STATUS_CONFIG: Record<string, { label: string; color: string }>
+  formatDuration: (seconds: number) => string
+}
+
+const CloneVoiceSection: React.FC<CloneVoiceSectionProps> = ({
+  clonedVoices,
+  hasProcessing,
+  selectedClonedVoice,
+  onSelect,
+  onOpenCloneModal,
+  CLONE_STATUS_CONFIG,
+  formatDuration,
+}) => {
+  return (
+    <div className="xx-clone-section">
+      <p className="xx-clone-section-title">克隆我的声音</p>
+      <Text style={{ fontSize: 12, color: "var(--text-tertiary, #94a3b8)" }}>
+        上传一段您的语音样本，AI 将克隆您的声音用于视频配音
+      </Text>
+
+      <div style={{ marginTop: 12 }}>
+        <button
+          className="xx-btn xx-btn-primary"
+          style={{ height: 36, fontSize: 13 }}
+          onClick={onOpenCloneModal}
+        >
+          <ThunderboltOutlined /> 克隆新声音
+        </button>
+      </div>
+
+      {/* 轮询提示 */}
+      {hasProcessing && (
+        <div className="xx-clone-polling-hint" style={{ marginTop: 10 }}>
+          <span className="xx-clone-polling-dot" />
+          正在同步克隆进度...
+        </div>
+      )}
+
+      {/* 已克隆声音列表 */}
+      {clonedVoices.length > 0 && (
+        <div className="xx-clone-voices-list">
+          {clonedVoices.map((cv) => {
+            const statusCfg = CLONE_STATUS_CONFIG[cv.status]
+            const isReady = cv.status === "ready"
+            const selected = selectedClonedVoice === cv.id
+            return (
+              <div
+                key={cv.id}
+                className={`xx-clone-voice-row ${selected ? "selected" : ""} ${
+                  !isReady ? "disabled" : ""
+                }`}
+                onClick={() => {
+                  if (isReady) onSelect(cv.id)
+                }}
+                role="button"
+                tabIndex={isReady ? 0 : -1}
+                aria-pressed={selected}
+              >
+                <div className={`xx-clone-avatar ${cv.status}`}>
+                  <AudioOutlined />
+                </div>
+                <div className="xx-clone-info">
+                  <div className="xx-clone-name">{cv.name}</div>
+                  <div className="xx-clone-status">
+                    <span className="xx-clone-status-dot" style={{ background: statusCfg.color }} />
+                    <span style={{ color: statusCfg.color }}>{statusCfg.label}</span>
+                    {isReady && (
+                      <span
+                        style={{
+                          color: "var(--text-secondary)",
+                          marginLeft: 8,
+                        }}
+                      >
+                        {formatDuration(cv.duration_seconds)}
+                      </span>
+                    )}
+                  </div>
+                </div>
+                {selected && isReady && (
+                  <CheckCircleFilled style={{ color: "var(--primary-color, #4f46e5)" }} />
+                )}
+              </div>
+            )
+          })}
+        </div>
+      )}
+
+      {clonedVoices.length === 0 && (
+        <Text
+          style={{
+            color: "var(--text-secondary)",
+            display: "block",
+            textAlign: "center",
+            padding: "16px 0",
+          }}
+        >
+          暂无克隆音色，点击「克隆新声音」开始
+        </Text>
+      )}
+
+      <Text
+        style={{
+          fontSize: 12,
+          color: "var(--text-tertiary, #94a3b8)",
+          marginTop: 10,
+          display: "block",
+        }}
+      >
+        💡 提示：录音环境越安静，克隆效果越好。
+      </Text>
+    </div>
+  )
+}
+
+export default CloneVoiceSection
@@ -0,0 +1,93 @@
+/**
+ * 自定义录制面板
+ * textarea + 合成按钮 + 结果区 + 存为素材按钮
+ */
+import React from "react"
+import { Typography } from "antd"
+import { AudioOutlined, SaveOutlined } from "@ant-design/icons"
+
+const { Text } = Typography
+
+interface CustomVoicePanelProps {
+  customVoiceText: string
+  onTextChange: (text: string) => void
+  synthesizePending: boolean
+  onSynthesize: () => void
+  ttsError: string | null
+  customAudioUrl: string | null
+  completedTtsJobId: string | null
+  onOpenSaveModal: () => void
+}
+
+const CustomVoicePanel: React.FC<CustomVoicePanelProps> = ({
+  customVoiceText,
+  onTextChange,
+  synthesizePending,
+  onSynthesize,
+  ttsError,
+  customAudioUrl,
+  completedTtsJobId,
+  onOpenSaveModal,
+}) => {
+  return (
+    <div>
+      <textarea
+        placeholder="输入配音文案，点击合成按钮生成语音…"
+        value={customVoiceText}
+        onChange={(e) => onTextChange(e.target.value)}
+        maxLength={500}
+        style={{
+          width: "100%",
+          minHeight: 100,
+          border: "1px solid var(--border-color, #e2e8f0)",
+          borderRadius: "var(--radius-sm, 10px)",
+          padding: 12,
+          fontSize: 14,
+          resize: "vertical",
+          outline: "none",
+        }}
+      />
+      <div style={{ marginTop: 12, display: "flex", gap: 8 }}>
+        <button
+          className="xx-btn xx-btn-ghost"
+          disabled={!customVoiceText.trim() || synthesizePending}
+          onClick={onSynthesize}
+        >
+          <AudioOutlined /> {synthesizePending ? "合成中…" : "合成语音"}
+        </button>
+      </div>
+      {ttsError && (
+        <Text
+          style={{
+            color: "var(--error, #ef4444)",
+            marginTop: 8,
+            display: "block",
+          }}
+        >
+          {ttsError}
+        </Text>
+      )}
+      {customAudioUrl && completedTtsJobId && (
+        <div
+          style={{
+            marginTop: 8,
+            display: "flex",
+            alignItems: "center",
+            gap: 12,
+          }}
+        >
+          <Text style={{ color: "var(--success, #10b981)" }}>✓ 语音合成完成</Text>
+          <button
+            className="xx-btn xx-btn-primary"
+            style={{ height: 30, padding: "0 14px", fontSize: 12 }}
+            onClick={onOpenSaveModal}
+          >
+            <SaveOutlined /> 存为素材
+          </button>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default CustomVoicePanel
@@ -0,0 +1,77 @@
+/**
+ * 预设音色下拉选择 + 试听按钮
+ * voiceMode === "preset" 时显示的详情区
+ */
+import React from "react"
+import { PlayCircleOutlined, PauseCircleOutlined } from "@ant-design/icons"
+import type { PresetVoiceItem } from "@/api/voices"
+
+interface PresetVoiceDetailProps {
+  presetVoices: PresetVoiceItem[]
+  selectedVoice: string
+  onSelect: (voiceId: string) => void
+  playingVoice: string | null
+  onTogglePlay: (voiceId: string, previewUrl: string | null) => void
+  presetVoicesLoading: boolean
+}
+
+const PresetVoiceDetail: React.FC<PresetVoiceDetailProps> = ({
+  presetVoices,
+  selectedVoice,
+  onSelect,
+  playingVoice,
+  onTogglePlay,
+  presetVoicesLoading,
+}) => {
+  return (
+    <div>
+      <div className="xx-form-field">
+        <label>从配音库选择</label>
+        <select value={selectedVoice} onChange={(e) => onSelect(e.target.value)}>
+          <option value="">请选择配音…</option>
+          {presetVoicesLoading ? (
+            <option disabled>加载中…</option>
+          ) : (
+            presetVoices.map((v) => (
+              <option key={v.voice_id} value={v.voice_id}>
+                {v.name} — {v.description}
+              </option>
+            ))
+          )}
+        </select>
+      </div>
+      {/* 试听按钮 */}
+      {presetVoices.length > 0 && (
+        <div
+          style={{
+            display: "flex",
+            gap: 8,
+            flexWrap: "wrap",
+            marginTop: 8,
+          }}
+        >
+          {presetVoices.slice(0, 4).map((v) => (
+            <button
+              key={v.voice_id}
+              className="xx-btn xx-btn-ghost"
+              style={{ height: 32, padding: "0 12px", fontSize: 12 }}
+              onClick={() => onTogglePlay(v.voice_id, v.preview_url)}
+            >
+              {playingVoice === v.voice_id ? (
+                <>
+                  <PauseCircleOutlined /> 停止
+                </>
+              ) : (
+                <>
+                  <PlayCircleOutlined /> {v.name}
+                </>
+              )}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default PresetVoiceDetail
@@ -0,0 +1,125 @@
+/**
+ * 保存到配音库弹窗
+ */
+import React from "react"
+import { CloseOutlined, PlusOutlined } from "@ant-design/icons"
+import type { TagItem } from "@/api/tags"
+
+interface SaveVoiceModalProps {
+  open: boolean
+  onClose: () => void
+  saveName: string
+  onNameChange: (name: string) => void
+  saveTagIds: string[]
+  onTagIdsChange: (tags: string[] | ((prev: string[]) => string[])) => void
+  saveNewTag: string
+  onNewTagChange: (tag: string) => void
+  onAddTag: (tagName: string) => void
+  allTags: TagItem[]
+  savePending: boolean
+  onConfirm: () => void
+}
+
+const SaveVoiceModal: React.FC<SaveVoiceModalProps> = ({
+  open,
+  onClose,
+  saveName,
+  onNameChange,
+  saveTagIds,
+  onTagIdsChange,
+  saveNewTag,
+  onNewTagChange,
+  onAddTag,
+  allTags,
+  savePending,
+  onConfirm,
+}) => {
+  if (!open) return null
+
+  return (
+    <div className="xx-save-modal-overlay" onClick={onClose}>
+      <div className="xx-save-modal" onClick={(e) => e.stopPropagation()}>
+        <div className="xx-save-modal-header">
+          <span>保存到配音库</span>
+          <button className="xx-save-modal-close" onClick={onClose}>
+            <CloseOutlined />
+          </button>
+        </div>
+        <div className="xx-save-modal-body">
+          <label className="xx-save-modal-label">素材名称</label>
+          <input
+            className="xx-save-modal-input"
+            placeholder="留空则自动生成名称"
+            value={saveName}
+            onChange={(e) => onNameChange(e.target.value)}
+            maxLength={50}
+          />
+          <label className="xx-save-modal-label">
+            标签
+            <span
+              style={{
+                fontWeight: 400,
+                color: "var(--text-tertiary, #94a3b8)",
+              }}
+            >
+              （可选）
+            </span>
+          </label>
+          <div className="xx-save-modal-tags">
+            {saveTagIds.map((id) => {
+              const tag = allTags.find((t) => t.id === id)
+              return tag ? (
+                <span key={id} className="xx-save-modal-tag active">
+                  {tag.name}
+                  <CloseOutlined
+                    className="xx-save-modal-tag-remove"
+                    onClick={() => onTagIdsChange((prev: string[]) => prev.filter((x) => x !== id))}
+                  />
+                </span>
+              ) : null
+            })}
+            <input
+              className="xx-save-modal-tag-input"
+              placeholder="输入标签名回车添加"
+              value={saveNewTag}
+              onChange={(e) => onNewTagChange(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter") {
+                  e.preventDefault()
+                  onAddTag(saveNewTag)
+                }
+              }}
+            />
+          </div>
+          {allTags.length > 0 && (
+            <div className="xx-save-modal-tag-presets">
+              {allTags
+                .filter((t) => !saveTagIds.includes(t.id))
+                .slice(0, 12)
+                .map((t) => (
+                  <button
+                    key={t.id}
+                    className="xx-save-modal-tag-preset"
+                    onClick={() => onTagIdsChange((prev: string[]) => [...prev, t.id])}
+                  >
+                    {t.name}
+                    <PlusOutlined style={{ fontSize: 10, marginLeft: 4 }} />
+                  </button>
+                ))}
+            </div>
+          )}
+        </div>
+        <div className="xx-save-modal-footer">
+          <button className="xx-btn xx-btn-ghost" onClick={onClose}>
+            取消
+          </button>
+          <button className="xx-btn xx-btn-primary" disabled={savePending} onClick={onConfirm}>
+            {savePending ? "保存中…" : "保存"}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default SaveVoiceModal
@@ -0,0 +1,53 @@
+/**
+ * 音色选择卡片
+ * 用于顶部预设音色卡片和克隆入口卡片
+ */
+import React from "react"
+
+interface VoiceChoiceCardProps {
+  selected: boolean
+  onClick: () => void
+  avatar: React.ReactNode
+  title: string
+  description?: string
+  avatarStyle?: React.CSSProperties
+  loading?: boolean
+}
+
+const VoiceChoiceCard: React.FC<VoiceChoiceCardProps> = ({
+  selected,
+  onClick,
+  avatar,
+  title,
+  description,
+  avatarStyle,
+  loading = false,
+}) => {
+  return (
+    <div
+      className={`xx-voice-choice-item ${selected ? "selected" : ""}`}
+      onClick={onClick}
+      role="button"
+      tabIndex={0}
+      aria-pressed={selected}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault()
+          onClick()
+        }
+      }}
+      style={loading ? { opacity: 0.5 } : undefined}
+    >
+      <span className="xx-voice-choice-check">✓</span>
+      <div className="xx-voice-choice-avatar" style={avatarStyle}>
+        {avatar}
+      </div>
+      <div className="xx-voice-choice-info">
+        <h4>{title}</h4>
+        {description && <p>{description}</p>}
+      </div>
+    </div>
+  )
+}
+
+export default VoiceChoiceCard
@@ -0,0 +1,100 @@
+/**
+ * AI 智能推荐配音区域
+ */
+import React from "react"
+import { LoadingOutlined, CheckCircleFilled } from "@ant-design/icons"
+import type { PresetVoiceItem } from "@/api/voices"
+
+interface VoiceRecommendSectionProps {
+  presetVoices: PresetVoiceItem[]
+  voiceRecommendLoading: boolean
+  voiceRecommendations: string[]
+  hasVoiceRecommend: boolean
+  onRecommend: () => void
+  onSelectVoice: (voiceId: string) => void
+  selectedVoiceId: string
+  voiceMode: "preset" | "custom" | "clone"
+  VOICE_GENDER_ICON: Record<string, string>
+}
+
+const VoiceRecommendSection: React.FC<VoiceRecommendSectionProps> = ({
+  presetVoices,
+  voiceRecommendLoading,
+  voiceRecommendations,
+  hasVoiceRecommend,
+  onRecommend,
+  onSelectVoice,
+  selectedVoiceId,
+  voiceMode,
+  VOICE_GENDER_ICON,
+}) => {
+  return (
+    <div className="xx-voice-recommend-section">
+      <div className="xx-voice-recommend-header">
+        <span className="xx-voice-recommend-label">✨ AI 智能推荐</span>
+        <button
+          type="button"
+          className="xx-btn xx-btn-primary xx-btn-sm"
+          onClick={onRecommend}
+          disabled={voiceRecommendLoading}
+        >
+          {voiceRecommendLoading ? (
+            <>
+              <LoadingOutlined style={{ marginRight: 6 }} />
+              推荐中
+            </>
+          ) : hasVoiceRecommend ? (
+            "换一批"
+          ) : (
+            "智能推荐"
+          )}
+        </button>
+      </div>
+
+      {voiceRecommendLoading && (
+        <div className="xx-voice-recommend-loading">
+          <LoadingOutlined style={{ color: "var(--primary-color)", marginRight: 8 }} />
+          根据视频内容为你匹配最合适的音色…
+        </div>
+      )}
+
+      {!voiceRecommendLoading && hasVoiceRecommend && voiceRecommendations.length > 0 && (
+        <div className="xx-voice-recommend-list">
+          {voiceRecommendations.map((voiceId) => {
+            const v = presetVoices.find((pv) => pv.voice_id === voiceId)
+            if (!v) return null
+            const isSelected = voiceMode === "preset" && selectedVoiceId === v.voice_id
+            return (
+              <div
+                key={v.voice_id}
+                className={`xx-voice-recommend-card ${isSelected ? "selected" : ""}`}
+                onClick={() => onSelectVoice(v.voice_id)}
+              >
+                <div className="xx-voice-recommend-avatar">
+                  {VOICE_GENDER_ICON[v.gender] ?? "✨"}
+                </div>
+                <div className="xx-voice-recommend-info">
+                  <div className="xx-voice-recommend-name">{v.name}</div>
+                  <div className="xx-voice-recommend-desc">{v.description}</div>
+                </div>
+                {isSelected && (
+                  <div className="xx-voice-recommend-check">
+                    <CheckCircleFilled style={{ color: "#fff", fontSize: 16 }} />
+                  </div>
+                )}
+              </div>
+            )
+          })}
+        </div>
+      )}
+
+      {!voiceRecommendLoading && !hasVoiceRecommend && (
+        <div className="xx-voice-recommend-empty">
+          <span>点击「智能推荐」，AI 根据视频内容匹配音色</span>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default VoiceRecommendSection
@@ -0,0 +1,200 @@
+/**
+ * 智能剪辑页面 — 常量定义
+ */
+
+import type { CoverConfig } from "../editing-planner/types"
+
+/* ── 克隆声音状态配置 ── */
+export const CLONE_STATUS_CONFIG: Record<string, { label: string; color: string }> = {
+  ready: { label: "就绪", color: "var(--secondary-color, #10b981)" },
+  processing: { label: "克隆中", color: "var(--accent-color, #f59e0b)" },
+  failed: { label: "失败", color: "var(--error-color, #ef4444)" },
+}
+
+/* ── 模板渐变色映射（根据 mode 分配视觉样式） ── */
+export const MODE_GRADIENTS: Record<string, string> = {
+  pip: "linear-gradient(135deg, #fbbf24, #f59e0b)",
+  one_take: "linear-gradient(135deg, #3b82f6, #1d4ed8)",
+  voice_over: "linear-gradient(135deg, #6366f1, #4f46e5)",
+  voice_pip: "linear-gradient(135deg, #10b981, #059669)",
+}
+
+/* ── 配音性别图标 ── */
+export const VOICE_GENDER_ICON: Record<string, string> = {
+  female: "🎀",
+  male: "🎙️",
+  child: "🧒",
+  neutral: "✨",
+}
+
+/* ── 步骤定义 ── */
+export const STEPS = [
+  { key: 1, label: "选择模板" },
+  { key: 2, label: "选择素材" },
+  { key: 3, label: "生成预览" },
+  { key: 4, label: "选择标题" },
+  { key: 5, label: "选择配音" },
+  { key: 6, label: "选择封面" },
+  { key: 7, label: "确认生成" },
+]
+
+/* ── 标题位置选项 ── */
+export const POSITION_OPTIONS = [
+  { value: "top", label: "顶部" },
+  { value: "center", label: "居中" },
+  { value: "bottom", label: "底部" },
+]
+
+/* ── 标题字体选项 ── */
+export const FONT_OPTIONS = [
+  "思源黑体",
+  "思源宋体",
+  "苹方",
+  "PingFang",
+  "微软雅黑",
+  "楷体",
+  "华康俪金黑",
+]
+
+/* ── 标题样式预设 ── */
+export const TITLE_PRESETS = [
+  {
+    key: "classic_white",
+    label: "经典白字",
+    style: { size: 28, color: "#ffffff", bold: true, italic: false, stroke: true, shadow: false },
+    previewStyle: {
+      fontWeight: 700,
+      color: "#ffffff",
+      WebkitTextStroke: "1px #000000",
+      fontSize: "20px",
+    },
+  },
+  {
+    key: "black_gold",
+    label: "黑金质感",
+    style: { size: 32, color: "#d4a843", bold: true, italic: false, stroke: false, shadow: true },
+    previewStyle: {
+      fontWeight: 700,
+      color: "#d4a843",
+      textShadow: "1px 1px 3px rgba(0,0,0,0.8)",
+      fontSize: "20px",
+    },
+  },
+  {
+    key: "fresh_minimal",
+    label: "清新简约",
+    style: { size: 24, color: "#333333", bold: false, italic: false, stroke: false, shadow: false },
+    previewStyle: { fontWeight: 400, color: "#333333", fontSize: "18px" },
+  },
+  {
+    key: "variety_show",
+    label: "综艺花字",
+    style: { size: 36, color: "#ff4081", bold: true, italic: false, stroke: true, shadow: true },
+    previewStyle: {
+      fontWeight: 900,
+      color: "#ff4081",
+      WebkitTextStroke: "1.5px #ffffff",
+      textShadow: "2px 2px 4px rgba(0,0,0,0.5)",
+      fontSize: "22px",
+    },
+  },
+  {
+    key: "business",
+    label: "商务极简",
+    style: { size: 24, color: "#1a1a1a", bold: false, italic: false, stroke: false, shadow: false },
+    previewStyle: { fontWeight: 400, color: "#1a1a1a", fontSize: "17px" },
+  },
+  {
+    key: "retro_film",
+    label: "复古胶片",
+    style: { size: 28, color: "#e8d5b7", bold: false, italic: false, stroke: false, shadow: true },
+    previewStyle: {
+      fontWeight: 400,
+      color: "#e8d5b7",
+      textShadow: "2px 2px 6px rgba(0,0,0,0.7)",
+      fontSize: "18px",
+    },
+  },
+  {
+    key: "neon_glow",
+    label: "霓虹发光",
+    style: { size: 32, color: "#00e5ff", bold: true, italic: false, stroke: false, shadow: true },
+    previewStyle: {
+      fontWeight: 700,
+      color: "#00e5ff",
+      textShadow: "0 0 4px #00e5ff, 0 0 8px #00e5ff, 0 0 16px rgba(0,229,255,0.5)",
+      fontSize: "20px",
+    },
+  },
+  {
+    key: "handwriting",
+    label: "手写字",
+    style: { size: 28, color: "#333333", bold: false, italic: false, stroke: false, shadow: true },
+    previewStyle: {
+      fontWeight: 400,
+      color: "#333333",
+      textShadow: "1px 1px 2px rgba(0,0,0,0.3)",
+      fontSize: "20px",
+    },
+  },
+]
+
+/* ── 封面模式 ── */
+export const COVER_MODE_LABELS: Record<string, string> = {
+  auto: "智能封面",
+  frame: "抽帧选封面",
+  upload: "上传封面",
+}
+
+export const COVER_MODE_ICONS: Record<string, string> = {
+  auto: "🤖",
+  frame: "🎞️",
+  upload: "📤",
+}
+
+/* ── 智能匹配推荐理由 ── */
+export const SMART_MATCH_REASONS = [
+  "画面清晰度高，构图专业",
+  "与描述场景高度契合",
+  "时长适中，适合剪辑节奏",
+  "色彩风格统一",
+  "包含关键动作镜头",
+  "镜头运动流畅自然",
+  "光影效果出色",
+  "人物表情生动",
+]
+
+/* ── AI 标题模板 ── */
+export const AI_TITLE_TEMPLATES: Record<string, string[]> = {
+  catchy: [
+    "震惊！{topic}居然还能这样操作",
+    "99%的人都不知道的{topic}秘诀",
+    "{topic}的终极指南，看完直接封神",
+    "别再走弯路了！{topic}看这一篇就够",
+    "一个视频讲透{topic}，建议收藏",
+  ],
+  emotional: [
+    "致每一个在{topic}路上坚持的人",
+    "关于{topic}，我想说句真心话",
+    "{topic}背后的故事，看完沉默了",
+    "为什么我劝你一定要了解{topic}",
+    "这才是{topic}最动人的样子",
+  ],
+  informative: [
+    "{topic}完整科普：从入门到精通",
+    "深度解析{topic}的核心原理",
+    "{topic}行业趋势报告｜2026最新版",
+    "三分钟带你全面了解{topic}",
+    "{topic}常见问题与解决方案汇总",
+  ],
+}
+
+/* ── 默认封面设置 ── */
+export const DEFAULT_COVER_SETTINGS: CoverConfig = {
+  enabled: true,
+  mode: "auto",
+  frame_time: 0,
+  upload_url: "",
+  ai_suggested_time: null,
+  thumbnail_url: "",
+}
@@ -0,0 +1,370 @@
+/**
+ * 视频生成 Hook
+ * 封装视频生成的核心逻辑、状态管理、轮询等
+ */
+import { useState, useRef, useCallback } from "react"
+import { message } from "antd"
+import type { GeneratedVideo, EditPlanConfig } from "@/api/template-editor"
+import {
+  generateEditPlan,
+  updateEditPlan,
+  getGenerationTaskResults,
+  getGenerationStatus,
+  getEditPlan,
+} from "@/api/template-editor"
+import type { CoverConfig } from "../../editing-planner/types"
+import type { TitleSettings } from "../types"
+
+interface UseGenerateVideoProps {
+  titleSettings: TitleSettings
+  selectedTemplate: string
+  selectedMaterials: string[]
+  materialMode: "manual" | "auto"
+  smartSelectedIds: string[]
+  voiceMode: "preset" | "custom" | "clone"
+  selectedVoice: string
+  selectedClonedVoice: string
+  coverSettings: CoverConfig
+  videoRatio: string
+  style: string
+  duration: number
+  autoSubtitles: boolean
+  bgm: boolean
+  generateCount: number
+}
+
+export function useGenerateVideo({
+  titleSettings,
+  selectedTemplate,
+  selectedMaterials,
+  materialMode,
+  smartSelectedIds,
+  voiceMode,
+  selectedVoice,
+  selectedClonedVoice,
+  coverSettings,
+  videoRatio,
+  style,
+  duration,
+  autoSubtitles,
+  bgm,
+  generateCount,
+}: UseGenerateVideoProps) {
+  /* ── 生成状态 ── */
+  const [generating, setGenerating] = useState(false)
+  const [progress, setProgress] = useState(0)
+  const [generated, setGenerated] = useState(false)
+  const [generateError, setGenerateError] = useState<string | null>(null)
+  const [generatedVideos, setGeneratedVideos] = useState<GeneratedVideo[]>([])
+
+  const progressTimer = useRef<ReturnType<typeof setInterval>>(undefined)
+
+  /* ── 生成阶段映射 ── */
+  const getGenerationPhase = (p: number) => {
+    if (p < 20) return { label: "分析素材与配置", icon: "🔍" }
+    if (p < 50) return { label: "智能剪辑合成", icon: "🎬" }
+    if (p < 80) return { label: "渲染视频中", icon: "⚡" }
+    return { label: "即将完成", icon: "✨" }
+  }
+
+  /* ── 生成视频 ── */
+  const generate = useCallback(async () => {
+    console.log("[handleGenerate] 开始生成, 参数:", {
+      titleSettings,
+      selectedTemplate,
+      selectedMaterials,
+      voiceMode,
+    })
+    if (!titleSettings.title.trim()) {
+      message.warning("请先选择或输入标题")
+      return
+    }
+    if (materialMode === "manual" && selectedMaterials.length === 0) {
+      message.warning("请至少选择一个素材")
+      return
+    }
+
+    if (voiceMode === "clone" && !selectedClonedVoice) {
+      message.warning("请先选择一个克隆音色")
+      return
+    }
+
+    setGenerating(true)
+    setProgress(0)
+    setGenerated(false)
+    setGenerateError(null)
+
+    try {
+      const voiceConfig: Pick<
+        EditPlanConfig,
+        "voice_id" | "voice_clone_profile_id" | "custom_audio_url" | "custom_text"
+      > = {}
+      if (voiceMode === "preset") {
+        voiceConfig.voice_id = selectedVoice || undefined
+      } else if (voiceMode === "clone") {
+        voiceConfig.voice_clone_profile_id = selectedClonedVoice || undefined
+      } else if (voiceMode === "custom") {
+        voiceConfig.voice_id = selectedVoice || undefined
+        // 注意：customAudioUrl / customVoiceText 在 step5 hook 中，
+        // 自定义配音模式需从 step5 组件传回
+      }
+
+      // 获取或创建草稿
+      await getEditPlan(selectedTemplate)
+
+      // 更新草稿内容 + 切换到 editing 状态
+      await updateEditPlan(selectedTemplate, {
+        name: titleSettings.title.trim(),
+        config: {
+          asset_ids: materialMode === "auto" ? smartSelectedIds : selectedMaterials,
+          title_config: {
+            ai_auto_select: titleSettings.aiAutoSelect,
+            content: titleSettings.title,
+            position: titleSettings.position,
+            font_preset: titleSettings.font,
+            font_color: titleSettings.color,
+            font_size: titleSettings.size,
+          },
+          cover_config: coverSettings,
+          ...voiceConfig,
+          ratio: videoRatio,
+          style,
+          duration,
+          auto_subtitles: autoSubtitles,
+          bgm,
+          generate_count: generateCount,
+          material_mode: materialMode,
+        },
+        total_duration: duration,
+        status: "editing",
+      })
+
+      await generateEditPlan(selectedTemplate)
+
+      const poll = async () => {
+        try {
+          const data = await getGenerationStatus(selectedTemplate)
+
+          if (data.plan_status === "completed") {
+            setProgress(100)
+            setGenerating(false)
+            setGenerated(true)
+
+            // 获取生成的视频结果
+            if (data.generation_task_id) {
+              try {
+                const videos = await getGenerationTaskResults(data.generation_task_id)
+                setGeneratedVideos(videos)
+              } catch (err) {
+                console.error("[获取生成结果失败]", err)
+              }
+            }
+
+            message.success("视频生成完成！")
+            return
+          }
+          if (data.plan_status === "failed") {
+            setGenerating(false)
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- 防御性错误提取
+            const dataAny = data as Record<string, any>
+            const rawMsg =
+              dataAny.error_message ||
+              dataAny.error ||
+              dataAny.message ||
+              (data.clips || []).find((c: { status: string }) => c.status === "failed")
+                ?.error_message ||
+              "视频生成失败，请联系管理员或重试"
+            const safeExtract = (val: unknown): string => {
+              if (typeof val === "string") return val
+              if (typeof val === "object" && val !== null) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- 防御性错误提取
+                const obj = val as Record<string, any>
+                if (typeof obj.message === "string") return obj.message
+                if (typeof obj.msg === "string") return obj.msg
+                if (typeof obj.detail === "string") return obj.detail
+                if (obj.message && typeof obj.message === "object") return safeExtract(obj.message)
+                return JSON.stringify(val)
+              }
+              return String(val ?? "")
+            }
+            const errorMsg = safeExtract(rawMsg)
+            console.error("[生成失败] templateId:", selectedTemplate, "响应:", data)
+            setGenerateError(errorMsg)
+            message.error(errorMsg)
+            return
+          }
+
+          const clips = data.clips || []
+          const total = clips.length || 1
+          const done = clips.filter((c: { status: string }) => c.status === "completed").length
+          setProgress(Math.round((done / total) * 100))
+
+          progressTimer.current = setTimeout(poll, 2000) as unknown as ReturnType<
+            typeof setInterval
+          >
+        } catch (pollErr) {
+          console.error("[轮询出错] templateId:", selectedTemplate, pollErr)
+          progressTimer.current = setTimeout(poll, 3000) as unknown as ReturnType<
+            typeof setInterval
+          >
+        }
+      }
+
+      progressTimer.current = setTimeout(poll, 2000) as unknown as ReturnType<typeof setInterval>
+    } catch (err: unknown) {
+      console.error("[handleGenerate] 生成失败:", err)
+      setGenerating(false)
+      const axiosErr = err as {
+        response?: {
+          data?: {
+            message?: string | object
+            error?: string | object
+            detail?: string | object
+            msg?: string | object
+          }
+        }
+        message?: string
+      }
+      const extractString = (val: unknown): string => {
+        if (typeof val === "string") return val
+        if (typeof val === "object" && val !== null) {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any -- 防御性错误提取
+          const obj = val as Record<string, any>
+          if (typeof obj.message === "string") return obj.message
+          if (typeof obj.msg === "string") return obj.msg
+          if (typeof obj.detail === "string") return obj.detail
+          if (typeof obj.message === "object" && obj.message !== null)
+            return extractString(obj.message)
+          if (typeof obj.msg === "object" && obj.msg !== null) return extractString(obj.msg)
+          return JSON.stringify(val)
+        }
+        return ""
+      }
+      const backendMsg =
+        extractString(axiosErr.response?.data?.message) ||
+        extractString(axiosErr.response?.data?.error) ||
+        extractString(axiosErr.response?.data?.detail) ||
+        extractString(axiosErr.response?.data?.msg) ||
+        axiosErr.message ||
+        ""
+      console.error("[handleGenerate] 错误信息:", backendMsg, "完整错误:", axiosErr)
+      const safeExtractErr = (val: unknown): string => {
+        if (typeof val === "string") return val
+        if (typeof val === "object" && val !== null) {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any -- 防御性错误提取
+          const obj = val as Record<string, any>
+          if (typeof obj.message === "string") return obj.message
+          if (typeof obj.msg === "string") return obj.msg
+          if (typeof obj.detail === "string") return obj.detail
+          if (typeof obj.message === "object") return safeExtractErr(obj.message)
+          return JSON.stringify(val)
+        }
+        return String(val ?? "")
+      }
+      const rawError = safeExtractErr(backendMsg)
+      const translateError = (msg: string): string => {
+        if (!msg) return "生成失败，请检查网络后重试或联系管理员"
+        if (msg.includes("editing") || msg.includes("draft") || msg.includes("状态")) {
+          return "正在准备生成，请稍候再试"
+        }
+        if (msg.includes("template_id") || msg.includes("not found") || msg.includes("不存在")) {
+          return "所选模板或素材不可用，请重新选择"
+        }
+        if (msg.includes("asset") && (msg.includes("not found") || msg.includes("missing"))) {
+          return "素材数据异常，请返回视频库重新检查"
+        }
+        if (msg.includes("timeout") || msg.includes("network") || msg.includes("ECONN")) {
+          return "网络连接超时，请检查网络后重试"
+        }
+        if (msg.includes("quota") || msg.includes("limit") || msg.includes("exceed")) {
+          return "已达到生成次数上限，请稍后再试或联系客服"
+        }
+        if (msg.length > 0 && msg.length < 100 && !msg.includes("{")) return msg
+        return "生成失败，请稍后重试或联系管理员"
+      }
+      const finalMsg = translateError(rawError)
+      setGenerateError(finalMsg)
+      message.error(finalMsg)
+    }
+  }, [
+    titleSettings,
+    selectedMaterials,
+    selectedVoice,
+    voiceMode,
+    selectedClonedVoice,
+    videoRatio,
+    style,
+    duration,
+    autoSubtitles,
+    bgm,
+    selectedTemplate,
+    generateCount,
+    materialMode,
+    coverSettings,
+    smartSelectedIds,
+  ])
+
+  /* 重新生成（失败后重试） */
+  const retry = useCallback(() => {
+    setGenerateError(null)
+    generate()
+  }, [generate])
+
+  /* 清除错误 */
+  const dismissError = useCallback(() => {
+    setGenerateError(null)
+  }, [])
+
+  /* ── 下载视频 ── */
+  const download = useCallback(async () => {
+    if (!generatedVideos.length) return
+    const video = generatedVideos[0]
+    try {
+      const url = video.download_url || video.file_url
+      if (url) {
+        const a = document.createElement("a")
+        a.href = url
+        a.download = video.name || "generated-video.mp4"
+        a.target = "_blank"
+        document.body.appendChild(a)
+        a.click()
+        document.body.removeChild(a)
+      }
+    } catch (err) {
+      console.error("[下载失败]", err)
+      message.error("下载失败，请重试")
+    }
+  }, [generatedVideos])
+
+  /* ── 分享视频 ── */
+  const share = useCallback(async () => {
+    if (!generatedVideos.length) return
+    const video = generatedVideos[0]
+    const shareUrl = video.file_url || window.location.href
+    try {
+      await navigator.clipboard.writeText(shareUrl)
+      message.success("视频链接已复制到剪贴板")
+    } catch {
+      message.info(`视频链接: ${shareUrl}`)
+    }
+  }, [generatedVideos])
+
+  return {
+    // 状态
+    generating,
+    progress,
+    generated,
+    generateError,
+    generatedVideos,
+    // 操作
+    generate,
+    retry,
+    dismissError,
+    download,
+    share,
+    // 工具
+    getGenerationPhase,
+  }
+}
+
+export default useGenerateVideo
@@ -0,0 +1,44 @@
+/**
+ * Step 1 模板选择 Hook
+ * 封装模板选择的交互逻辑
+ */
+import { useCallback } from "react"
+import type { EditingTemplate } from "@/api/editing-planner"
+
+interface UseStep1TemplateProps {
+  templates: EditingTemplate[]
+  selectedTemplate: string
+  onSelectTemplate: (id: string) => void
+}
+
+export function useStep1Template({
+  templates,
+  selectedTemplate,
+  onSelectTemplate,
+}: UseStep1TemplateProps) {
+  const handleSelect = useCallback(
+    (id: string) => {
+      onSelectTemplate(id)
+    },
+    [onSelectTemplate],
+  )
+
+  const handleKeySelect = useCallback(
+    (e: React.KeyboardEvent, id: string) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault()
+        onSelectTemplate(id)
+      }
+    },
+    [onSelectTemplate],
+  )
+
+  return {
+    templates,
+    selectedTemplate,
+    handleSelect,
+    handleKeySelect,
+  }
+}
+
+export default useStep1Template
@@ -0,0 +1,205 @@
+/**
+ * Step 2 素材选择 Hook
+ * 封装素材库加载、手动选择、智能匹配等逻辑
+ */
+import { useState, useCallback, useEffect, useMemo } from "react"
+import { message } from "antd"
+import { useQuery } from "@tanstack/react-query"
+import { getAssets, getAssetLibraries } from "@/api/assets"
+import type { AssetItem } from "@/api/assets"
+import { formatDuration } from "../utils/formatDuration"
+import { SMART_MATCH_REASONS } from "../constants"
+
+interface SmartMatchedResult {
+  asset: AssetItem
+  matchScore: number
+  matchReason: string
+}
+
+interface UseStep2MaterialsProps {
+  materialMode: "manual" | "auto"
+  onMaterialModeChange: (mode: "manual" | "auto") => void
+  selectedMaterials: string[]
+  onSelectedMaterialsChange: (ids: string[]) => void
+  smartSelectedIds: string[]
+  onSmartSelectedIdsChange: (ids: string[]) => void
+}
+
+export function useStep2Materials({
+  materialMode,
+  onMaterialModeChange,
+  selectedMaterials,
+  onSelectedMaterialsChange,
+  smartSelectedIds,
+  onSmartSelectedIdsChange,
+}: UseStep2MaterialsProps) {
+  /* ── 素材库数据 API ── */
+  const { data: libraries = [] } = useQuery({
+    queryKey: ["asset-libraries"],
+    queryFn: getAssetLibraries,
+  })
+  const [selectedLibraryId, setSelectedLibraryId] = useState<string>("")
+
+  // 自动选中第一个视频库
+  useEffect(() => {
+    if (libraries.length > 0 && !selectedLibraryId) {
+      setSelectedLibraryId(libraries[0].id)
+    }
+  }, [libraries, selectedLibraryId])
+
+  const { data: materials = { items: [], total: 0 }, isLoading: materialsLoading } = useQuery<{
+    items: AssetItem[]
+    total: number
+  }>({
+    queryKey: ["generate-assets", selectedLibraryId],
+    queryFn: () => getAssets(selectedLibraryId),
+    enabled: !!selectedLibraryId,
+  })
+
+  /* ── 智能素材匹配状态 ── */
+  const [smartMatchInput, setSmartMatchInput] = useState("")
+  const [smartMatching, setSmartMatching] = useState(false)
+  const [smartMatchedResults, setSmartMatchedResults] = useState<SmartMatchedResult[]>([])
+  const [hasMatched, setHasMatched] = useState(false)
+
+  /* ── 手动选择素材 ── */
+  const handleToggleMaterial = useCallback(
+    (materialId: string) => {
+      onSelectedMaterialsChange(
+        selectedMaterials.includes(materialId)
+          ? selectedMaterials.filter((id) => id !== materialId)
+          : [...selectedMaterials, materialId],
+      )
+    },
+    [selectedMaterials, onSelectedMaterialsChange],
+  )
+
+  /* ── 智能素材匹配 ── */
+  const handleSmartMatch = useCallback(async () => {
+    if (!smartMatchInput.trim()) {
+      message.warning("请先输入视频内容描述")
+      return
+    }
+    if (materials.items.length === 0) {
+      message.warning("当前视频库暂无素材")
+      return
+    }
+
+    setSmartMatching(true)
+    setHasMatched(true)
+
+    // 模拟 AI 匹配延迟
+    await new Promise((resolve) => setTimeout(resolve, 1500))
+
+    // 从素材库中随机选取 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)
+
+    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 ? "，画面质感优秀" : ""),
+    }))
+
+    // 按匹配度从高到低排序
+    results.sort((a, b) => b.matchScore - a.matchScore)
+
+    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 handleToggleSmartSelect = useCallback(
+    (assetId: string) => {
+      onSmartSelectedIdsChange(
+        smartSelectedIds.includes(assetId)
+          ? smartSelectedIds.filter((id) => id !== assetId)
+          : [...smartSelectedIds, assetId],
+      )
+    },
+    [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])
+
+  return {
+    // 素材库
+    libraries,
+    selectedLibraryId,
+    setSelectedLibraryId,
+    materials,
+    materialsLoading,
+    // 模式
+    materialMode,
+    onMaterialModeChange,
+    // 手动选择
+    selectedMaterials,
+    handleToggleMaterial,
+    // 智能匹配
+    smartMatchInput,
+    setSmartMatchInput,
+    smartMatching,
+    smartMatchedResults,
+    hasMatched,
+    smartSelectedIds,
+    handleSmartMatch,
+    handleToggleSmartSelect,
+    handleRefreshMatch,
+    handleSelectAllMatched,
+    handleClearSmartSelect,
+    smartSelectedTotalDuration,
+    // utils
+    formatDuration,
+  }
+}
+
+export default useStep2Materials
@@ -0,0 +1,47 @@
+/**
+ * Step 3 生成预览 Hook
+ * 封装预览信息的计算逻辑
+ */
+import { useMemo } from "react"
+import type { EditingTemplate } from "@/api/editing-planner"
+
+interface UseStep3PreviewProps {
+  templates: EditingTemplate[]
+  selectedTemplate: string
+  materialMode: "manual" | "auto"
+  selectedMaterials: string[]
+  smartSelectedIds: string[]
+  duration: number
+  videoRatio: string
+}
+
+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])
+
+  return {
+    templateName,
+    materialCount,
+    duration,
+    videoRatio,
+  }
+}
+
+export default useStep3Preview
@@ -0,0 +1,251 @@
+/**
+ * Step 4 标题设置 Hook
+ * 封装 AI 标题生成、标题样式设置等逻辑
+ */
+import { useState, useCallback, useMemo } from "react"
+import { message } from "antd"
+import { useQuery } from "@tanstack/react-query"
+import { getTitles } from "@/api/titles"
+import { TITLE_PRESETS, AI_TITLE_TEMPLATES } from "../constants"
+import type { TitleSettings } from "../types"
+
+interface UseStep4TitleProps {
+  titleSettings: TitleSettings
+  onTitleSettingsChange: (settings: TitleSettings) => void
+}
+
+interface AiTitleItem {
+  title: string
+  highlight: string
+  style: "catchy" | "emotional" | "informative"
+}
+
+export function useStep4Title({ titleSettings, onTitleSettingsChange }: UseStep4TitleProps) {
+  /* ── 标题库 API ── */
+  const { data: userTitles = [] } = useQuery({
+    queryKey: ["titles"],
+    queryFn: () => getTitles(),
+    staleTime: 30_000,
+  })
+
+  /* ── AI 标题生成状态 ── */
+  const [aiTitleInput, setAiTitleInput] = useState("")
+  const [aiTitleGenerating, setAiTitleGenerating] = useState(false)
+  const [aiTitleResults, setAiTitleResults] = useState<AiTitleItem[]>([])
+  const [hasGeneratedTitles, setHasGeneratedTitles] = useState(false)
+
+  /* ── 辅助函数 ── */
+  const extractTopic = (text: string): string => {
+    const keywords = text
+      .replace(/[，。！？、,.!?]/g, " ")
+      .split(/\s+/)
+      .filter(Boolean)
+    if (keywords.length === 0) return "这个话题"
+    // 取前3个关键词组合
+    return keywords.slice(0, 3).join("")
+  }
+
+  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 &&
+        settings.stroke === p.style.stroke &&
+        settings.shadow === p.style.shadow
+      ) {
+        return p.key
+      }
+    }
+    return null
+  }
+
+  const activePreset = useMemo(() => getActivePreset(titleSettings), [titleSettings])
+
+  /* ── AI 标题生成 ── */
+  const handleGenerateAiTitles = useCallback(async () => {
+    if (!aiTitleInput.trim()) {
+      message.warning("请先输入视频描述或关键词")
+      return
+    }
+    setAiTitleGenerating(true)
+    setHasGeneratedTitles(true)
+
+    // 模拟 AI 生成延迟
+    await new Promise((resolve) => setTimeout(resolve, 1200))
+
+    const topic = extractTopic(aiTitleInput)
+    const results: AiTitleItem[] = []
+
+    const styles: Array<"catchy" | "emotional" | "informative"> = [
+      "catchy",
+      "emotional",
+      "informative",
+    ]
+    styles.forEach((style) => {
+      const templates = AI_TITLE_TEMPLATES[style]
+      // 每种风格随机选2个
+      const shuffled = [...templates].sort(() => Math.random() - 0.5).slice(0, 2)
+      shuffled.forEach((tpl) => {
+        const title = tpl.replace(/\{topic\}/g, topic)
+        const highlights = {
+          catchy: "吸睛标题",
+          emotional: "情感共鸣",
+          informative: "知识干货",
+        }
+        results.push({
+          title,
+          highlight: highlights[style],
+          style,
+        })
+      })
+    })
+
+    // 打乱顺序
+    results.sort(() => Math.random() - 0.5)
+    setAiTitleResults(results)
+    setAiTitleGenerating(false)
+  }, [aiTitleInput])
+
+  const handleSelectAiTitle = useCallback(
+    (title: string) => {
+      onTitleSettingsChange({ ...titleSettings, title, aiAutoSelect: false })
+      message.success("已选用此标题")
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  const handleRefreshAiTitles = useCallback(async () => {
+    if (!aiTitleInput.trim()) return
+    setAiTitleGenerating(true)
+    await new Promise((resolve) => setTimeout(resolve, 800))
+    // 重新生成一批
+    const topic = extractTopic(aiTitleInput)
+    const results: AiTitleItem[] = []
+    const styles: Array<"catchy" | "emotional" | "informative"> = [
+      "catchy",
+      "emotional",
+      "informative",
+    ]
+    const highlights = { catchy: "吸睛标题", emotional: "情感共鸣", informative: "知识干货" }
+    styles.forEach((style) => {
+      const templates = AI_TITLE_TEMPLATES[style]
+      const shuffled = [...templates].sort(() => Math.random() - 0.5).slice(0, 2)
+      shuffled.forEach((tpl) => {
+        results.push({
+          title: tpl.replace(/\{topic\}/g, topic),
+          highlight: highlights[style],
+          style,
+        })
+      })
+    })
+    results.sort(() => Math.random() - 0.5)
+    setAiTitleResults(results)
+    setAiTitleGenerating(false)
+  }, [aiTitleInput])
+
+  /* ── 标题设置更新 ── */
+  const updateTitle = useCallback(
+    (title: string) => {
+      onTitleSettingsChange({ ...titleSettings, title })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  const toggleAiAutoSelect = useCallback(() => {
+    onTitleSettingsChange({ ...titleSettings, aiAutoSelect: !titleSettings.aiAutoSelect })
+  }, [titleSettings, onTitleSettingsChange])
+
+  const updatePosition = useCallback(
+    (position: string) => {
+      onTitleSettingsChange({ ...titleSettings, position })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  const updateFont = useCallback(
+    (font: string) => {
+      onTitleSettingsChange({ ...titleSettings, font })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  const updateSize = useCallback(
+    (size: number) => {
+      onTitleSettingsChange({ ...titleSettings, size })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  const updateColor = useCallback(
+    (color: string) => {
+      onTitleSettingsChange({ ...titleSettings, color })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  const toggleBold = useCallback(() => {
+    onTitleSettingsChange({ ...titleSettings, bold: !titleSettings.bold })
+  }, [titleSettings, onTitleSettingsChange])
+
+  const toggleItalic = useCallback(() => {
+    onTitleSettingsChange({ ...titleSettings, italic: !titleSettings.italic })
+  }, [titleSettings, onTitleSettingsChange])
+
+  const toggleStroke = useCallback(() => {
+    onTitleSettingsChange({ ...titleSettings, stroke: !titleSettings.stroke })
+  }, [titleSettings, onTitleSettingsChange])
+
+  const toggleShadow = useCallback(() => {
+    onTitleSettingsChange({ ...titleSettings, shadow: !titleSettings.shadow })
+  }, [titleSettings, onTitleSettingsChange])
+
+  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,
+        stroke: preset.style.stroke,
+        shadow: preset.style.shadow,
+      })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  return {
+    // 数据
+    userTitles,
+    titleSettings,
+    aiTitleInput,
+    setAiTitleInput,
+    aiTitleGenerating,
+    aiTitleResults,
+    hasGeneratedTitles,
+    activePreset,
+    titlePresets: TITLE_PRESETS,
+    // AI 标题操作
+    handleGenerateAiTitles,
+    handleSelectAiTitle,
+    handleRefreshAiTitles,
+    // 标题设置操作
+    updateTitle,
+    toggleAiAutoSelect,
+    updatePosition,
+    updateFont,
+    updateSize,
+    updateColor,
+    toggleBold,
+    toggleItalic,
+    toggleStroke,
+    toggleShadow,
+    applyPreset,
+  }
+}
+
+export default useStep4Title
@@ -0,0 +1,397 @@
+/**
+ * Step 5 配音选择 Hook
+ * 封装 AI 推荐、预设音色试听、TTS 自定义合成、存为素材等逻辑
+ */
+import { useState, useRef, useCallback, useEffect, useMemo } from "react"
+import { useNavigate } from "react-router-dom"
+import { message } from "antd"
+import { useQuery, useMutation } from "@tanstack/react-query"
+import type { PresetVoiceItem } from "@/api/voices"
+import { fetchPresetVoices } from "@/api/voices"
+import { synthesizeSpeech, getTTSJobStatus, saveTtsToLibrary } from "@/api/tts"
+import { getTags, createTag } from "@/api/tags"
+import { formatDuration } from "../utils/formatDuration"
+import type { VoiceClone } from "@/api/voice-clone"
+import { VOICE_GENDER_ICON, CLONE_STATUS_CONFIG } from "../constants"
+
+interface UseStep5VoiceProps {
+  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
+}
+
+export function useStep5Voice({
+  selectedVoice,
+  onSelectedVoiceChange,
+  voiceMode,
+  onVoiceModeChange,
+  selectedClonedVoice,
+  onSelectedClonedVoiceChange,
+  clonedVoices,
+  addClone,
+  hasProcessing,
+  cloneModalOpen,
+  onCloneModalOpenChange,
+  titleText,
+}: UseStep5VoiceProps) {
+  const navigate = useNavigate()
+  /* ── 预置音色 API ── */
+  const { data: presetVoicesData, isLoading: presetVoicesLoading } = useQuery({
+    queryKey: ["preset-voices"],
+    queryFn: fetchPresetVoices,
+  })
+  const presetVoices: PresetVoiceItem[] = useMemo(
+    () => presetVoicesData?.items ?? [],
+    [presetVoicesData],
+  )
+
+  /* ── 音频播放 ── */
+  const audioRef = useRef<HTMLAudioElement | null>(null)
+  const [playingVoice, setPlayingVoice] = useState<string | null>(null)
+
+  const toggleVoicePlay = useCallback(
+    (voiceId: string, previewUrl: string | null) => {
+      if (playingVoice === voiceId) {
+        audioRef.current?.pause()
+        audioRef.current = null
+        setPlayingVoice(null)
+        return
+      }
+      audioRef.current?.pause()
+      if (!previewUrl) {
+        message.warning("该音色暂无试听音频")
+        return
+      }
+      const audio = new Audio(previewUrl)
+      audioRef.current = audio
+      audio.play().catch(() => {
+        message.error("播放失败，请检查网络")
+      })
+      audio.onended = () => {
+        setPlayingVoice(null)
+        audioRef.current = null
+      }
+      setPlayingVoice(voiceId)
+    },
+    [playingVoice],
+  )
+
+  /* ── 智能配音推荐 ── */
+  const [voiceRecommendLoading, setVoiceRecommendLoading] = useState(false)
+  const [voiceRecommendations, setVoiceRecommendations] = useState<string[]>([])
+  const [hasVoiceRecommend, setHasVoiceRecommend] = useState(false)
+
+  const handleVoiceRecommend = useCallback(async () => {
+    if (presetVoices.length === 0) return
+    setVoiceRecommendLoading(true)
+    setHasVoiceRecommend(true)
+
+    await new Promise((resolve) => setTimeout(resolve, 1000))
+
+    // 根据标题内容风格模拟推荐：情感类→温柔女声，知识类→沉稳男声，活力类→阳光少年
+    const title = titleText.toLowerCase()
+    let recommended: string[] = []
+
+    const femaleVoices = presetVoices.filter((v) => v.gender === "female").map((v) => v.voice_id)
+    const maleVoices = presetVoices.filter((v) => v.gender === "male").map((v) => v.voice_id)
+    const childVoices = presetVoices.filter((v) => v.gender === "child").map((v) => v.voice_id)
+
+    if (/情感|感人|温暖|治愈|故事|回忆/.test(title)) {
+      recommended = femaleVoices.slice(0, 3)
+    } else if (/教程|知识|科普|干货|讲解|分析/.test(title)) {
+      recommended = maleVoices.slice(0, 2).concat(femaleVoices.slice(0, 1))
+    } else if (/活力|热血|运动|搞笑|有趣/.test(title)) {
+      recommended = childVoices.slice(0, 1).concat(maleVoices.slice(0, 1), femaleVoices.slice(0, 1))
+    } else {
+      // 默认推荐前3个
+      recommended = presetVoices.slice(0, 3).map((v) => v.voice_id)
+    }
+
+    // 不足3个时补足
+    if (recommended.length < 3) {
+      const others = presetVoices
+        .filter((v) => !recommended.includes(v.voice_id))
+        .map((v) => v.voice_id)
+      recommended = recommended.concat(others.slice(0, 3 - recommended.length))
+    }
+
+    setVoiceRecommendations(recommended)
+    setVoiceRecommendLoading(false)
+  }, [presetVoices, titleText])
+
+  const handleSelectRecommendedVoice = useCallback(
+    (voiceId: string) => {
+      onVoiceModeChange("preset")
+      onSelectedVoiceChange(voiceId)
+    },
+    [onVoiceModeChange, onSelectedVoiceChange],
+  )
+
+  /* ── TTS 自定义合成状态 ── */
+  const [customVoiceText, setCustomVoiceText] = useState("")
+  const [customAudioUrl, setCustomAudioUrl] = useState<string | null>(null)
+  const [ttsError, setTtsError] = useState<string | null>(null)
+  const [ttsJobId, setTtsJobId] = useState<string | null>(null)
+  /** 合成完成后保留的 job ID，用于"存为素材" */
+  const [completedTtsJobId, setCompletedTtsJobId] = useState<string | null>(null)
+
+  /* ── TTS mutation ── */
+  const synthesizeMutation = useMutation({
+    mutationFn: synthesizeSpeech,
+    onSuccess: (data) => {
+      setTtsJobId(data.job_id)
+      message.info("语音合成已提交，等待处理…")
+    },
+    onError: () => {
+      setTtsError("语音合成请求失败，请重试")
+    },
+  })
+
+  /** 轮询 TTS 任务状态 */
+  useEffect(() => {
+    if (!ttsJobId) return
+    let cancelled = false
+    let timer: ReturnType<typeof setTimeout>
+
+    const poll = async () => {
+      try {
+        const status = await getTTSJobStatus(ttsJobId)
+        if (cancelled) return
+        if (status.status === "completed") {
+          setCustomAudioUrl(status.output_audio_url)
+          setCompletedTtsJobId(ttsJobId)
+          setTtsJobId(null)
+          setTtsError(null)
+          message.success("语音合成完成！")
+          return
+        }
+        if (status.status === "failed" || status.status === "cancelled") {
+          setTtsError(status.error_message || "语音合成失败")
+          setTtsJobId(null)
+          return
+        }
+        timer = setTimeout(poll, 2000)
+      } catch {
+        if (!cancelled) {
+          setTtsError("查询合成状态失败")
+          setTtsJobId(null)
+        }
+      }
+    }
+
+    timer = setTimeout(poll, 2000)
+    return () => {
+      cancelled = true
+      clearTimeout(timer)
+    }
+  }, [ttsJobId])
+
+  /** 触发自定义文本 TTS 合成 */
+  const handleSynthesizeVoice = useCallback(() => {
+    if (!customVoiceText.trim()) {
+      message.warning("请先输入配音文案")
+      return
+    }
+    setTtsError(null)
+    setCustomAudioUrl(null)
+    synthesizeMutation.mutate({
+      text: customVoiceText.trim(),
+      voice_id: selectedVoice || undefined,
+      language: "zh-CN",
+    })
+  }, [customVoiceText, selectedVoice, synthesizeMutation])
+
+  /* ── 存为素材弹窗状态 ── */
+  const [saveModalOpen, setSaveModalOpen] = useState(false)
+  const [saveName, setSaveName] = useState("")
+  const [saveTagIds, setSaveTagIds] = useState<string[]>([])
+  const [saveNewTag, setSaveNewTag] = useState("")
+
+  /* ── 标签列表（用于存为素材弹窗） ── */
+  const { data: allTags = [] } = useQuery({
+    queryKey: ["generate-save-tags"],
+    queryFn: getTags,
+    staleTime: 30_000,
+  })
+
+  /* ── 存为素材 mutation ── */
+  const saveToLibraryMutation = useMutation({
+    mutationFn: (params: { name?: string; tag_ids?: string[] }) =>
+      saveTtsToLibrary(completedTtsJobId!, params),
+    onSuccess: () => {
+      message.success({
+        content: (
+          <span>
+            已保存到配音库！{" "}
+            <a
+              onClick={handleGoToLibrary}
+              style={{
+                color: "var(--primary-500, #6366f1)",
+                cursor: "pointer",
+              }}
+            >
+              去视频库查看
+            </a>
+          </span>
+        ),
+        duration: 5,
+      })
+      setSaveModalOpen(false)
+      setSaveName("")
+      setSaveTagIds([])
+      setSaveNewTag("")
+      setCompletedTtsJobId(null)
+      setCustomAudioUrl(null)
+    },
+    onError: (err: Error) => {
+      message.error(`保存失败：${err.message || "请重试"}`)
+    },
+  })
+
+  /** 打开存为素材弹窗 */
+  const handleOpenSaveModal = useCallback(() => {
+    setSaveName("")
+    setSaveTagIds([])
+    setSaveNewTag("")
+    setSaveModalOpen(true)
+  }, [])
+
+  /** 确认保存 */
+  const handleConfirmSave = useCallback(() => {
+    if (!completedTtsJobId) return
+    saveToLibraryMutation.mutate({
+      name: saveName.trim() || undefined,
+      tag_ids: saveTagIds.length > 0 ? saveTagIds : undefined,
+    })
+  }, [completedTtsJobId, saveName, saveTagIds, saveToLibraryMutation])
+
+  /** 在弹窗中新增标签（先创建再选中） */
+  const handleAddTagInModal = useCallback(
+    async (tagName: string) => {
+      const trimmed = tagName.trim()
+      if (!trimmed) return
+      /* 已在选中列表则跳过 */
+      const existing = allTags.find((t) => t.name === trimmed)
+      if (existing) {
+        if (!saveTagIds.includes(existing.id)) {
+          setSaveTagIds((prev) => [...prev, existing.id])
+        }
+        return
+      }
+      try {
+        const created = await createTag(trimmed)
+        setSaveTagIds((prev) => [...prev, created.id])
+        setSaveNewTag("")
+      } catch {
+        message.error(`创建标签"${trimmed}"失败`)
+      }
+    },
+    [allTags, saveTagIds],
+  )
+
+  /** 保存成功后跳转到视频库 */
+  const handleGoToLibrary = useCallback(() => {
+    navigate("/app/voice-materials")
+  }, [navigate])
+
+  /* ── 克隆成功回调 ── */
+  const handleCloneSuccess = useCallback(
+    (voice: VoiceClone) => {
+      addClone(voice)
+      onCloneModalOpenChange(false)
+      message.success("音色克隆成功！")
+    },
+    [addClone, onCloneModalOpenChange],
+  )
+
+  /* ── 预设音色选择操作 ── */
+  const handleSelectPresetVoice = useCallback(
+    (voiceId: string) => {
+      onVoiceModeChange("preset")
+      onSelectedVoiceChange(voiceId)
+    },
+    [onVoiceModeChange, onSelectedVoiceChange],
+  )
+
+  const handleSelectCloneVoice = useCallback(() => {
+    onVoiceModeChange("clone")
+  }, [onVoiceModeChange])
+
+  const handleSelectClonedVoice = useCallback(
+    (voiceId: string) => {
+      onSelectedClonedVoiceChange(voiceId)
+    },
+    [onSelectedClonedVoiceChange],
+  )
+
+  const handleOpenCloneModal = useCallback(() => {
+    onCloneModalOpenChange(true)
+  }, [onCloneModalOpenChange])
+
+  return {
+    // 数据
+    presetVoices,
+    presetVoicesLoading,
+    clonedVoices,
+    hasProcessing,
+    // 模式 & 选择
+    voiceMode,
+    selectedVoice,
+    selectedClonedVoice,
+    // AI 推荐
+    voiceRecommendLoading,
+    voiceRecommendations,
+    hasVoiceRecommend,
+    handleVoiceRecommend,
+    handleSelectRecommendedVoice,
+    // 音频播放
+    playingVoice,
+    toggleVoicePlay,
+    // 预设音色操作
+    handleSelectPresetVoice,
+    handleSelectCloneVoice,
+    // 自定义 TTS
+    customVoiceText,
+    setCustomVoiceText,
+    customAudioUrl,
+    ttsError,
+    ttsJobId,
+    completedTtsJobId,
+    synthesizeMutation,
+    handleSynthesizeVoice,
+    // 存为素材
+    saveModalOpen,
+    setSaveModalOpen,
+    saveName,
+    setSaveName,
+    saveTagIds,
+    setSaveTagIds,
+    saveNewTag,
+    setSaveNewTag,
+    allTags,
+    saveToLibraryMutation,
+    handleOpenSaveModal,
+    handleConfirmSave,
+    handleAddTagInModal,
+    // 克隆
+    cloneModalOpen,
+    handleOpenCloneModal,
+    handleCloneSuccess,
+    handleSelectClonedVoice,
+    // utils
+    VOICE_GENDER_ICON,
+    CLONE_STATUS_CONFIG,
+    formatDuration,
+  }
+}
+
+export default useStep5Voice
@@ -0,0 +1,81 @@
+/**
+ * Step 6 封面设置 Hook
+ * 封装封面设置的交互逻辑
+ */
+import { useCallback } from "react"
+import type { CoverConfig } from "../../editing-planner/types"
+import { COVER_MODE_LABELS, COVER_MODE_ICONS, DEFAULT_COVER_SETTINGS } from "../constants"
+
+interface UseStep6CoverProps {
+  coverSettings: CoverConfig
+  onCoverSettingsChange: (settings: CoverConfig) => void
+  duration: number
+}
+
+export function useStep6Cover({
+  coverSettings,
+  onCoverSettingsChange,
+  duration,
+}: UseStep6CoverProps) {
+  const formatTime = useCallback((seconds: number) => {
+    const m = Math.floor(seconds / 60)
+    const s = Math.floor(seconds % 60)
+    const ms = Math.floor((seconds % 1) * 10)
+    return `${m.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}.${ms}`
+  }, [])
+
+  const toggleEnabled = useCallback(
+    (enabled: boolean) => {
+      onCoverSettingsChange({ ...coverSettings, enabled })
+    },
+    [coverSettings, onCoverSettingsChange],
+  )
+
+  const setMode = useCallback(
+    (mode: CoverConfig["mode"]) => {
+      onCoverSettingsChange({ ...coverSettings, mode })
+    },
+    [coverSettings, onCoverSettingsChange],
+  )
+
+  const setFrameTime = useCallback(
+    (frameTime: number) => {
+      onCoverSettingsChange({ ...coverSettings, frame_time: frameTime })
+    },
+    [coverSettings, onCoverSettingsChange],
+  )
+
+  const handleUpload = useCallback(
+    (file: File) => {
+      const reader = new FileReader()
+      reader.onload = (ev) => {
+        const url = ev.target?.result as string
+        onCoverSettingsChange({
+          ...coverSettings,
+          upload_url: url,
+          thumbnail_url: url,
+          mode: "upload",
+        })
+      }
+      reader.readAsDataURL(file)
+    },
+    [coverSettings, onCoverSettingsChange],
+  )
+
+  const totalDuration = duration || 30
+
+  return {
+    coverSettings,
+    formatTime,
+    toggleEnabled,
+    setMode,
+    setFrameTime,
+    handleUpload,
+    totalDuration,
+    COVER_MODE_LABELS,
+    COVER_MODE_ICONS,
+    DEFAULT_COVER_SETTINGS,
+  }
+}
+
+export default useStep6Cover
@@ -0,0 +1,121 @@
+/**
+ * Step 7 确认生成 Hook
+ * 封装生成确认页的展示逻辑
+ */
+import { useMemo } from "react"
+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 { COVER_MODE_LABELS } from "../constants"
+
+interface UseStep7GenerateProps {
+  templates: EditingTemplate[]
+  selectedTemplate: string
+  materialMode: "manual" | "auto"
+  selectedMaterials: string[]
+  smartSelectedIds: string[]
+  title: string
+  voiceMode: "preset" | "custom" | "clone"
+  selectedVoice: string
+  selectedClonedVoice: string
+  presetVoices: PresetVoiceItem[]
+  clonedVoices: VoiceClone[]
+  coverSettings: CoverConfig
+  generateCount: number
+  onGenerateCountChange: (count: number) => void
+  generating: boolean
+  generated: boolean
+  generateError: string | null
+  progress: number
+  generatedVideos: GeneratedVideo[]
+}
+
+export function useStep7Generate({
+  templates,
+  selectedTemplate,
+  materialMode,
+  selectedMaterials,
+  smartSelectedIds,
+  title,
+  voiceMode,
+  selectedVoice,
+  selectedClonedVoice,
+  presetVoices,
+  clonedVoices,
+  coverSettings,
+  generateCount,
+  onGenerateCountChange,
+  generating,
+  generated,
+  generateError,
+  progress,
+  generatedVideos,
+}: UseStep7GenerateProps) {
+  const templateName = useMemo(
+    () => templates.find((t) => t.id === selectedTemplate)?.name ?? "未选择",
+    [templates, selectedTemplate],
+  )
+
+  const materialSummary = useMemo(() => {
+    if (materialMode === "auto") {
+      return `${smartSelectedIds.length} 个素材（智能匹配）`
+    }
+    return `${selectedMaterials.length} 个素材`
+  }, [materialMode, selectedMaterials.length, smartSelectedIds.length])
+
+  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 coverSummary = useMemo(() => {
+    if (!coverSettings.enabled) return "不使用"
+    return COVER_MODE_LABELS[coverSettings.mode] || "智能封面"
+  }, [coverSettings])
+
+  const getGenerationPhase = (p: number) => {
+    if (p < 20) return { label: "分析素材与配置", icon: "🔍" }
+    if (p < 50) return { label: "智能剪辑合成", icon: "🎬" }
+    if (p < 80) return { label: "渲染视频中", icon: "⚡" }
+    return { label: "即将完成", icon: "✨" }
+  }
+
+  const handleDecrement = () => {
+    onGenerateCountChange(Math.max(1, generateCount - 1))
+  }
+
+  const handleIncrement = () => {
+    onGenerateCountChange(Math.min(10, generateCount + 1))
+  }
+
+  const handleScrollToPreview = () => {
+    const el = document.querySelector(".xx-preview-section")
+    el?.scrollIntoView({ behavior: "smooth", block: "start" })
+  }
+
+  return {
+    templateName,
+    materialSummary,
+    title,
+    voiceName,
+    coverSummary,
+    generateCount,
+    handleDecrement,
+    handleIncrement,
+    generating,
+    generated,
+    generateError,
+    progress,
+    generatedVideos,
+    getGenerationPhase,
+    handleScrollToPreview,
+  }
+}
+
+export default useStep7Generate
@@ -0,0 +1,73 @@
+/**
+ * 智能剪辑页面 — 类型定义
+ */
+
+import type { AssetItem } from "@/api/assets"
+
+/* ── 标题设置 ── */
+export interface TitleSettings {
+  aiAutoSelect: boolean
+  title: string
+  position: string
+  font: string
+  size: number
+  bold: boolean
+  italic: boolean
+  stroke: boolean
+  shadow: boolean
+  color: string
+}
+
+/* ── 智能匹配结果 ── */
+export interface SmartMatchResult {
+  asset: AssetItem
+  matchScore: number
+  reasons: string[]
+}
+
+/* ── AI 标题结果 ── */
+export interface AiTitleResult {
+  title: string
+  style: string
+  styleLabel: string
+  highlights: string[]
+}
+
+/* ── 配音推荐结果 ── */
+export interface VoiceRecommendation {
+  voiceId: string
+  voiceName: string
+  reason: string
+}
+
+/* ── 步骤定义 ── */
+export interface StepDef {
+  key: number
+  label: string
+}
+
+/* ── 标题预设样式 ── */
+export interface TitlePresetStyle {
+  size: number
+  color: string
+  bold: boolean
+  italic: boolean
+  stroke: boolean
+  shadow: boolean
+}
+
+export interface TitlePreset {
+  key: string
+  label: string
+  style: TitlePresetStyle
+  previewStyle: Record<string, string | number>
+}
+
+/* ── 生成结果视频 ── */
+export interface GeneratedVideoResult {
+  id: string
+  url: string
+  thumbnail: string
+  duration: number
+  title: string
+}
@@ -0,0 +1,9 @@
+/**
+ * 时长格式化工具
+ * 秒数转分秒格式，如 65 -> "1:05"
+ */
+export const formatDuration = (seconds: number): string => {
+  const m = Math.floor(seconds / 60)
+  const s = seconds % 60
+  return `${m}:${String(s).padStart(2, "0")}`
+}
@@ -2,832 +2,87 @@
 * 成片库页面 — V21 设计系统
 * 卡片网格布局，支持视频播放/下载/分享、批量操作、筛选
 * 使用 useQuery 对接后端真实 API（api/products.ts）
+ *
+ * 代码结构（三阶段重构后）：
+ * - types.ts: 类型定义
+ * - constants.ts: 常量配置
+ * - utils/index.ts: 工具函数
+ * - components/ProductCard.tsx: 产品卡片组件
+ * - components/VideoPlayer.tsx: 视频播放器组件
+ * - hooks/useProductList.ts: 列表查询与筛选
+ * - hooks/useProductActions.ts: 单个/批量操作
 */
-import React, { useMemo, useState, useRef, useEffect, useCallback } from "react"
-import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
-import { useNavigate } from "react-router-dom"
-import { message, Popconfirm } from "antd"
+import React, { useState } from "react"
+import { Popconfirm, message } from "antd"
 import {
  SearchOutlined,
  VideoCameraOutlined,
  DownloadOutlined,
-  ShareAltOutlined,
  DeleteOutlined,
-  PlayCircleOutlined,
-  PauseCircleOutlined,
-  CloseOutlined,
  CheckOutlined,
  CloudUploadOutlined,
-  EyeOutlined,
 } from "@ant-design/icons"
 import { Button, Input, Select } from "@/components/ui"
-import {
-  getProducts,
-  deleteProduct,
-  getProductDownloadUrl,
-  updateReviewStatus,
-  batchDownload,
-  getBatchDownloadStatus,
-  type ProductItem as ApiProductItem,
-  type ReviewStatus,
-} from "@/api/products"
+import type { ProductItem } from "./types"
+import { ProductCard } from "./components/ProductCard"
+import { VideoPlayer } from "./components/VideoPlayer"
+import { useProductList } from "./hooks/useProductList"
+import { useProductActions } from "./hooks/useProductActions"
 import "./products.css"

-/* ============================================================
- * 类型 & 常量
- * ============================================================ */
-type ProductStatus = "completed" | "processing" | "review" | "failed"
-
-interface ProductItem {
-  id: string
-  name: string
-  status: ProductStatus
-  duration: number // 秒
-  date: string
-  gradient: string
-  duplicateRate: number // 查重率百分比
-  isPublished: boolean
-  resolution: string
-  fileSize: number // MB
-  videoUrl?: string
-  thumbnailUrl?: string
-  /** 复核状态 */
-  reviewStatus?: ReviewStatus
-  /** 所属项目 ID */
-  projectId?: string
-  /** 所属项目名称 */
-  projectName?: string
-}
-
-/** 将后端 status 映射为前端 ProductStatus */
-const normalizeStatus = (s: string): ProductStatus => {
-  const map: Record<string, ProductStatus> = {
-    completed: "completed",
-    succeeded: "completed",
-    processing: "processing",
-    running: "processing",
-    review: "review",
-    failed: "failed",
-    error: "failed",
-  }
-  return map[s] ?? "processing"
-}
-
-/** 渐变色列表（按 id hash 选取） */
-const GRADIENTS = [
-  "linear-gradient(135deg, #1e1b4b 0%, #4f46e5 50%, #818cf8 100%)",
-  "linear-gradient(135deg, #831843 0%, #db2777 50%, #f472b6 100%)",
-  "linear-gradient(135deg, #064e3b 0%, #059669 50%, #34d399 100%)",
-  "linear-gradient(135deg, #78350f 0%, #d97706 50%, #fbbf24 100%)",
-  "linear-gradient(135deg, #1e3a5f 0%, #2563eb 50%, #60a5fa 100%)",
-  "linear-gradient(135deg, #581c87 0%, #9333ea 50%, #c084fc 100%)",
-  "linear-gradient(135deg, #7f1d1d 0%, #dc2626 50%, #f87171 100%)",
-  "linear-gradient(135deg, #134e4a 0%, #0d9488 50%, #5eead4 100%)",
-  "linear-gradient(135deg, #1e1b4b 0%, #6366f1 50%, #a5b4fc 100%)",
-  "linear-gradient(135deg, #3b0764 0%, #7c3aed 50%, #a78bfa 100%)",
-  "linear-gradient(135deg, #052e16 0%, #16a34a 50%, #86efac 100%)",
-  "linear-gradient(135deg, #450a0e 0%, #e11d48 50%, #fb7185 100%)",
-]
-
-/** 根据 id 生成稳定的渐变色 */
-const gradientForId = (id: string): string => {
-  let hash = 0
-  for (let i = 0; i < id.length; i++) hash = (hash * 31 + id.charCodeAt(i)) | 0
-  return GRADIENTS[Math.abs(hash) % GRADIENTS.length]
-}
-
-/** 将后端 ProductItem 映射为前端 ProductItem */
-const mapApiProduct = (item: ApiProductItem): ProductItem => ({
-  id: item.id,
-  name: item.title,
-  status: normalizeStatus(item.status),
-  duration: item.duration_seconds ?? 0,
-  date: item.created_at ? formatDateTime(item.created_at) : "—",
-  gradient: gradientForId(item.id),
-  duplicateRate: item.duplicate_rate ?? 0,
-  isPublished: false, // TODO: 后端发布状态字段待补齐
-  resolution: item.resolution ?? "1080×1920",
-  fileSize: item.file_size ? +(item.file_size / (1024 * 1024)).toFixed(1) : 0,
-  videoUrl: item.video_url,
-  thumbnailUrl: item.thumbnail_url,
-  reviewStatus: item.review_status,
-  projectId: item.project_id,
-  projectName: item.project_name,
-})
-
-/* ============================================================
- * 工具函数
- * ============================================================ */
-const statusConfig: Record<ProductStatus, { text: string; className: string }> = {
-  completed: { text: "已完成", className: "completed" },
-  processing: { text: "处理中", className: "processing" },
-  review: { text: "待复核", className: "review" },
-  failed: { text: "失败", className: "failed" },
-}
-
-/** 格式化时间 mm:ss */
-const formatTime = (seconds: number): string => {
-  const mins = Math.floor(seconds / 60)
-  const secs = Math.floor(seconds % 60)
-  return `${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`
-}
-
-/** 格式化文件大小 */
-const formatSize = (mb: number): string => {
-  if (mb <= 0) return "-"
-  if (mb < 1) return `${(mb * 1024).toFixed(0)} KB`
-  return `${mb.toFixed(1)} MB`
-}
-
-/** 格式化日期时间（MM-DD HH:mm） */
-const formatDateTime = (isoString: string): string => {
-  const d = new Date(isoString)
-  const month = (d.getMonth() + 1).toString().padStart(2, "0")
-  const day = d.getDate().toString().padStart(2, "0")
-  const hour = d.getHours().toString().padStart(2, "0")
-  const minute = d.getMinutes().toString().padStart(2, "0")
-  return `${month}-${day} ${hour}:${minute}`
-}
-
-/** 复核状态配置 */
-const reviewStatusConfig: Record<ReviewStatus, { text: string; className: string }> = {
-  pending_review: { text: "待复核", className: "review-pending" },
-  approved: { text: "已通过", className: "review-approved" },
-  rejected: { text: "需修改", className: "review-rejected" },
-}
-
-/** 复核状态循环顺序 */
-const REVIEW_STATUS_CYCLE: ReviewStatus[] = ["pending_review", "approved", "rejected"]
-
-/** 获取下一个复核状态 */
-const getNextReviewStatus = (current?: ReviewStatus): ReviewStatus => {
-  if (!current) return "approved"
-  const idx = REVIEW_STATUS_CYCLE.indexOf(current)
-  return REVIEW_STATUS_CYCLE[(idx + 1) % REVIEW_STATUS_CYCLE.length]
-}
-
-/* ============================================================
- * ProductCard 组件
- * ============================================================ */
-const ProductCard: React.FC<{
-  product: ProductItem
-  isSelected: boolean
-  batchMode: boolean
-  onToggleSelect: (id: string) => void
-  onPlay: (product: ProductItem) => void
-  onDownload: (product: ProductItem) => void
-  onShare: (product: ProductItem) => void
-  onDelete: (id: string) => void
-  onPublish: (product: ProductItem) => void
-  onReviewStatusChange: (id: string) => void
-}> = ({
-  product,
-  isSelected,
-  batchMode,
-  onToggleSelect,
-  onPlay,
-  onDownload,
-  onShare,
-  onDelete,
-  onPublish,
-  onReviewStatusChange,
-}) => {
-  const st = statusConfig[product.status]
-
-  /** 查重率样式 */
-  const dupClass =
-    product.duplicateRate <= 5 ? "good" : product.duplicateRate <= 15 ? "warn" : "bad"
-
-  /** 点击卡片 */
-  const handleCardClick = () => {
-    if (batchMode) {
-      onToggleSelect(product.id)
-    } else {
-      onPlay(product)
-    }
-  }
-
-  /** 点击复选框 */
-  const handleCheckboxClick = (e: React.MouseEvent) => {
-    e.stopPropagation()
-    onToggleSelect(product.id)
-  }
-
-  return (
-    <div
-      className={`xx-product-card${isSelected ? " selected" : ""}${product.isPublished ? " published" : ""}`}
-      onClick={handleCardClick}
-    >
-      {/* 复选框（左上角） */}
-      <div
-        className={`xx-product-card-checkbox${isSelected ? " checked" : ""}`}
-        onClick={handleCheckboxClick}
-        title={isSelected ? "取消选择" : "选择"}
-      >
-        {isSelected && <CheckOutlined />}
-      </div>
-
-      {/* 已发布徽章（右上角） */}
-      {product.isPublished && <div className="xx-product-badge">✅ 已发布</div>}
-
-      {/* 复核状态标签（右上角） */}
-      {product.reviewStatus && (
-        <div
-          className={`xx-product-review-tag ${reviewStatusConfig[product.reviewStatus].className}`}
-          onClick={(e) => {
-            e.stopPropagation()
-            onReviewStatusChange(product.id)
-          }}
-          title={`点击切换复核状态（当前：${reviewStatusConfig[product.reviewStatus].text}）`}
-        >
-          {reviewStatusConfig[product.reviewStatus].text}
-        </div>
-      )}
-      {/* 无复核状态时显示"待复核"入口 */}
-      {!product.reviewStatus && (
-        <div
-          className="xx-product-review-tag review-pending"
-          onClick={(e) => {
-            e.stopPropagation()
-            onReviewStatusChange(product.id)
-          }}
-          title="点击设置复核状态"
-        >
-          待复核
-        </div>
-      )}
-
-      {/* 缩略图 */}
-      <div className="xx-product-thumb">
-        {product.thumbnailUrl ? (
-          <img
-            className="xx-product-thumb-bg"
-            src={product.thumbnailUrl}
-            alt={product.name}
-            style={{ width: "100%", height: "100%", objectFit: "cover" }}
-          />
-        ) : (
-          <div className="xx-product-thumb-bg" style={{ background: product.gradient }} />
-        )}
-        <div className="xx-product-play">
-          <PlayCircleOutlined />
-        </div>
-        {product.duration > 0 && (
-          <span className="xx-product-duration">{formatTime(product.duration)}</span>
-        )}
-      </div>
-
-      {/* 信息区 */}
-      <div className="xx-product-info">
-        <h4 className="xx-product-title" title={product.name}>
-          {product.name}
-        </h4>
-        <div className="xx-product-meta">
-          <span className={`xx-product-status ${st.className}`}>{st.text}</span>
-          <span className="xx-product-date">{product.date}</span>
-        </div>
-        {product.duplicateRate > 0 && (
-          <span className={`xx-product-dup-rate ${dupClass}`}>
-            查重率：{product.duplicateRate.toFixed(1)}%
-          </span>
-        )}
-      </div>
-
-      {/* 操作按钮 */}
-      <div className="xx-product-actions" onClick={(e) => e.stopPropagation()}>
-        <button
-          className="xx-product-action-btn"
-          onClick={() => onDownload(product)}
-          disabled={product.status !== "completed"}
-          title="下载"
-        >
-          <DownloadOutlined /> 下载
-        </button>
-        <button
-          className="xx-product-action-btn"
-          onClick={() => onShare(product)}
-          disabled={product.status !== "completed"}
-          title="分享"
-        >
-          <ShareAltOutlined /> 分享
-        </button>
-        {product.isPublished ? (
-          <span className="xx-product-action-btn success" style={{ cursor: "default" }}>
-            ✅ 已发布
-          </span>
-        ) : (
-          <button
-            className="xx-product-action-btn primary"
-            onClick={() => onPublish(product)}
-            disabled={product.status !== "completed"}
-            title="发布"
-          >
-            <CloudUploadOutlined /> 发布
-          </button>
-        )}
-      </div>
-
-      {/* 删除按钮（不在批量模式下显示） */}
-      {!batchMode && (
-        <div style={{ padding: "0 14px 14px" }} onClick={(e) => e.stopPropagation()}>
-          <Popconfirm
-            title={`确定删除"${product.name}"？`}
-            onConfirm={() => onDelete(product.id)}
-            okText="删除"
-            cancelText="取消"
-          >
-            <button
-              className="xx-product-action-btn"
-              style={{ width: "100%", color: "#dc2626" }}
-              title="删除"
-            >
-              <DeleteOutlined /> 删除
-            </button>
-          </Popconfirm>
-        </div>
-      )}
-    </div>
-  )
-}
-
-/* ============================================================
- * VideoPlayer 弹窗组件
- * ============================================================ */
-const VideoPlayer: React.FC<{
-  product: ProductItem
-  onClose: () => void
-  onDownload: (product: ProductItem) => void
-  onShare: (product: ProductItem) => void
-  onViewDetail: (product: ProductItem) => void
-}> = ({ product, onClose, onDownload, onShare, onViewDetail }) => {
-  const videoRef = useRef<HTMLVideoElement>(null)
-  const progressRef = useRef<HTMLDivElement>(null)
-  const [isPlaying, setIsPlaying] = useState(false)
-  const [currentTime, setCurrentTime] = useState(0)
-  const [duration, setDuration] = useState(product.duration)
-
-  const hasVideo = !!product.videoUrl
-
-  /** 播放/暂停 */
-  const handlePlayPause = useCallback(() => {
-    const video = videoRef.current
-    if (!video) return
-    if (isPlaying) {
-      video.pause()
-    } else {
-      video.play().catch(() => {})
-    }
-    setIsPlaying(!isPlaying)
-  }, [isPlaying])
-
-  /** 视频事件监听 */
-  useEffect(() => {
-    const video = videoRef.current
-    if (!video) return
-    const onTime = () => setCurrentTime(video.currentTime)
-    const onDur = () => setDuration(video.duration || product.duration)
-    const onEnd = () => setIsPlaying(false)
-    video.addEventListener("timeupdate", onTime)
-    video.addEventListener("loadedmetadata", onDur)
-    video.addEventListener("ended", onEnd)
-    return () => {
-      video.removeEventListener("timeupdate", onTime)
-      video.removeEventListener("loadedmetadata", onDur)
-      video.removeEventListener("ended", onEnd)
-    }
-  }, [product.duration])
-
-  /** 进度条点击 */
-  const handleProgressClick = (e: React.MouseEvent<HTMLDivElement>) => {
-    if (!progressRef.current) return
-    const rect = progressRef.current.getBoundingClientRect()
-    const percent = (e.clientX - rect.left) / rect.width
-    const newTime = percent * duration
-    setCurrentTime(newTime)
-    if (videoRef.current) videoRef.current.currentTime = newTime
-  }
-
-  /** ESC 关闭 */
-  useEffect(() => {
-    const handleKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") onClose()
-    }
-    window.addEventListener("keydown", handleKey)
-    return () => window.removeEventListener("keydown", handleKey)
-  }, [onClose])
-
-  const progress = duration > 0 ? (currentTime / duration) * 100 : 0
-
-  return (
-    <div className="xx-player-overlay" onClick={onClose}>
-      <div className="xx-player-container" onClick={(e) => e.stopPropagation()}>
-        {/* 视频区域 */}
-        <div className="xx-player-video-wrap">
-          {hasVideo ? (
-            <video
-              ref={videoRef}
-              src={product.videoUrl}
-              style={{ width: "100%", height: "100%", objectFit: "contain" }}
-            />
-          ) : (
-            /* 无视频 URL 时用渐变占位 */
-            <div
-              style={{
-                width: "100%",
-                height: "100%",
-                background: product.gradient,
-                display: "grid",
-                placeItems: "center",
-                color: "rgba(255,255,255,0.3)",
-                fontSize: "64px",
-              }}
-            >
-              <VideoCameraOutlined />
-            </div>
-          )}
-
-          {/* 播放/暂停按钮 */}
-          <button className="xx-player-play-btn" onClick={handlePlayPause}>
-            {isPlaying ? <PauseCircleOutlined /> : <PlayCircleOutlined />}
-          </button>
-
-          {/* 关闭按钮 */}
-          <button className="xx-player-close" onClick={onClose}>
-            <CloseOutlined />
-          </button>
-
-          {/* 进度条 */}
-          <div className="xx-player-progress-wrap">
-            <div ref={progressRef} className="xx-player-progress" onClick={handleProgressClick}>
-              <div className="xx-player-progress-bar" style={{ width: `${progress}%` }} />
-            </div>
-            <div className="xx-player-time">
-              <span>{formatTime(currentTime)}</span>
-              <span>{formatTime(duration)}</span>
-            </div>
-          </div>
-        </div>
-
-        {/* 信息区 */}
-        <div className="xx-player-info">
-          <h3 className="xx-player-title">{product.name}</h3>
-          <div className="xx-player-details">
-            <div className="xx-player-detail-item">
-              <span className="xx-player-detail-label">分辨率：</span>
-              <span className="xx-player-detail-value">{product.resolution}</span>
-            </div>
-            <div className="xx-player-detail-item">
-              <span className="xx-player-detail-label">时长：</span>
-              <span className="xx-player-detail-value">{formatTime(product.duration)}</span>
-            </div>
-            <div className="xx-player-detail-item">
-              <span className="xx-player-detail-label">文件大小：</span>
-              <span className="xx-player-detail-value">{formatSize(product.fileSize)}</span>
-            </div>
-            <div className="xx-player-detail-item">
-              <span className="xx-player-detail-label">查重率：</span>
-              <span className="xx-player-detail-value">
-                {product.duplicateRate > 0 ? `${product.duplicateRate.toFixed(1)}%` : "-"}
-              </span>
-            </div>
-          </div>
-        </div>
-
-        {/* 底部操作 */}
-        <div className="xx-player-footer">
-          <Button
-            buttonType="ghost"
-            buttonSize="sm"
-            icon={<DownloadOutlined />}
-            onClick={() => onDownload(product)}
-            disabled={product.status !== "completed"}
-          >
-            下载视频
-          </Button>
-          <Button
-            buttonType="ghost"
-            buttonSize="sm"
-            icon={<ShareAltOutlined />}
-            onClick={() => onShare(product)}
-            disabled={product.status !== "completed"}
-          >
-            分享
-          </Button>
-          <Button
-            buttonType="ghost"
-            buttonSize="sm"
-            icon={<EyeOutlined />}
-            onClick={() => onViewDetail(product)}
-          >
-            查看详情
-          </Button>
-          <div style={{ flex: 1 }} />
-          <Button buttonType="primary" buttonSize="sm" onClick={onClose}>
-            关闭
-          </Button>
-        </div>
-      </div>
-    </div>
-  )
-}
-
 /* ============================================================
 * 主组件
 * ============================================================ */
 const ProductLibrary: React.FC = () => {
-  const queryClient = useQueryClient()
-  const navigate = useNavigate()
-
-  /* ── 获取成品列表 ── */
  const {
-    data: apiProducts = [],
+    products,
+    filteredProducts,
    isLoading,
    isError,
    error,
    refetch,
-  } = useQuery<ApiProductItem[], Error>({
-    queryKey: ["products"],
-    queryFn: () => getProducts(),
-    staleTime: 30_000,
-  })
-
-  // 映射为前端类型，按创建时间倒序排列，防御非数组返回
-  const products = useMemo(() => {
-    const list = (Array.isArray(apiProducts) ? apiProducts : []).map(mapApiProduct)
-    // 按创建时间倒序（最新的在最前面），无时间的排最后
-    return list.sort((a, b) => {
-      if (!a.date || a.date === "—") return 1
-      if (!b.date || b.date === "—") return -1
-      return new Date(b.date).getTime() - new Date(a.date).getTime()
-    })
-  }, [apiProducts])
-
-  /* ── 删除 mutation ── */
-  const deleteMutation = useMutation({
-    mutationFn: deleteProduct,
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["products"] })
-      message.success("已删除")
-    },
-    onError: () => {
-      message.error("删除失败")
-    },
-  })
-
-  /* ── 复核状态 mutation ── */
-  const reviewMutation = useMutation({
-    mutationFn: ({ id, status }: { id: string; status: ReviewStatus }) =>
-      updateReviewStatus(id, status),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["products"] })
-      message.success("复核状态已更新")
-    },
-    onError: () => {
-      message.error("更新复核状态失败")
-    },
-  })
-
-  /* 筛选 */
-  const [searchText, setSearchText] = useState("")
-  const [filterStatus, setFilterStatus] = useState<string>("all")
-  const [filterTime, setFilterTime] = useState<string>("all")
-  const [filterDuration, setFilterDuration] = useState<string>("all")
-  const [filterProject, setFilterProject] = useState<string>("all")
-  const [filterReviewStatus, setFilterReviewStatus] = useState<string>("all")
-
-  /* 批量操作 */
-  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set())
+    searchText,
+    setSearchText,
+    filterStatus,
+    setFilterStatus,
+    filterTime,
+    setFilterTime,
+    filterDuration,
+    setFilterDuration,
+    filterProject,
+    setFilterProject,
+    filterReviewStatus,
+    setFilterReviewStatus,
+    projectOptions,
+    selectedIds,
+    batchMode,
+    allSelected,
+    handleSelectAll,
+    handleToggleSelect,
+    clearSelection,
+  } = useProductList()

  /* 播放器 */
  const [playingProduct, setPlayingProduct] = useState<ProductItem | null>(null)

-  /* 派生数据 */
-  const batchMode = selectedIds.size > 0
-
-  const filteredProducts = useMemo(() => {
-    let list = products
-
-    /* 状态筛选 */
-    if (filterStatus !== "all") {
-      list = list.filter((p) => p.status === filterStatus)
-    }
-
-    /* 时间筛选 */
-    if (filterTime !== "all") {
-      const now = new Date()
-      list = list.filter((p) => {
-        const d = new Date(p.date)
-        const diff = (now.getTime() - d.getTime()) / (1000 * 60 * 60 * 24)
-        switch (filterTime) {
-          case "today":
-            return diff < 1
-          case "week":
-            return diff <= 7
-          case "month":
-            return diff <= 30
-          default:
-            return true
-        }
-      })
-    }
-
-    /* 时长筛选 */
-    if (filterDuration !== "all") {
-      list = list.filter((p) => {
-        switch (filterDuration) {
-          case "short":
-            return p.duration > 0 && p.duration <= 60
-          case "medium":
-            return p.duration > 60 && p.duration <= 180
-          case "long":
-            return p.duration > 180
-          default:
-            return true
-        }
-      })
-    }
-
-    /* 项目筛选 */
-    if (filterProject !== "all") {
-      list = list.filter((p) => p.projectId === filterProject)
-    }
-
-    /* 复核状态筛选 */
-    if (filterReviewStatus !== "all") {
-      if (filterReviewStatus === "none") {
-        list = list.filter((p) => !p.reviewStatus)
-      } else {
-        list = list.filter((p) => p.reviewStatus === filterReviewStatus)
-      }
-    }
-
-    /* 搜索 */
-    if (searchText.trim()) {
-      const q = searchText.trim().toLowerCase()
-      list = list.filter((p) => p.name.toLowerCase().includes(q))
-    }
-
-    return list
-  }, [
+  const {
+    handleDownload,
+    handleShare,
+    handleViewDetail,
+    handleDelete,
+    handlePublish,
+    handleReviewStatusChange,
+    handleBatchDownload,
+    handleBatchDelete,
+    handleBatchPublish,
+    batchDownloading,
+  } = useProductActions({
+    selectedIds,
+    clearSelection,
    products,
-    filterStatus,
-    filterTime,
-    filterDuration,
-    filterProject,
-    filterReviewStatus,
-    searchText,
-  ])
+    setPlayingProduct,
+  })

-  /* 全选 */
-  const allSelected =
-    filteredProducts.length > 0 && filteredProducts.every((p) => selectedIds.has(p.id))
-
-  const handleSelectAll = () => {
-    if (allSelected) {
-      setSelectedIds(new Set())
-    } else {
-      setSelectedIds(new Set(filteredProducts.map((p) => p.id)))
-    }
-  }
-
-  /* 切换单个选择 */
-  const handleToggleSelect = (id: string) => {
-    setSelectedIds((prev) => {
-      const next = new Set(prev)
-      if (next.has(id)) {
-        next.delete(id)
-      } else {
-        next.add(id)
-      }
-      return next
-    })
-  }
-
-  /* 下载 — 调用真实 API 获取下载链接 */
-  const handleDownload = async (product: ProductItem) => {
-    if (product.status !== "completed") return
-    try {
-      const { url } = await getProductDownloadUrl(product.id)
-      // 打开下载链接
-      const a = document.createElement("a")
-      a.href = url
-      a.download = ""
-      a.click()
-      message.success(`正在下载"${product.name}"`)
-    } catch {
-      message.error("获取下载链接失败")
-    }
-  }
-
-  /* 分享 */
-  const handleShare = (product: ProductItem) => {
-    if (product.status !== "completed") return
-    const link = `${window.location.origin}/share/${product.id}`
-    navigator.clipboard?.writeText(link).then(
-      () => message.success(`分享链接已复制：${link}`),
-      () => message.success(`分享链接：${link}（请手动复制）`),
-    )
-  }
-
-  /* 查看详情 — 跳转到产品详情页 */
-  const handleViewDetail = (product: ProductItem) => {
-    setPlayingProduct(null) // 关闭播放器
-    navigate(`/app/products/${product.id}`)
-  }
-
-  /* 删除 */
-  const handleDelete = (id: string) => {
-    deleteMutation.mutate(id)
-    setSelectedIds((prev) => {
-      const next = new Set(prev)
-      next.delete(id)
-      return next
-    })
-  }
-
-  /* 发布 — TODO: 后端发布 API 待实现 */
-  const handlePublish = (_product: ProductItem) => {
-    // TODO: 对接后端发布 API（当前后端未提供发布接口）
-    message.info("发布功能待后端 API 补齐")
-  }
-
-  /* 切换复核状态 */
-  const handleReviewStatusChange = (id: string) => {
-    const current = products.find((p) => p.id === id)?.reviewStatus
-    const nextStatus = getNextReviewStatus(current)
-    reviewMutation.mutate({ id, status: nextStatus })
-  }
-
-  /* 批量下载 — 使用 batch-download API + 轮询 */
-  const [batchDownloading, setBatchDownloading] = useState(false)
-
-  const handleBatchDownload = async () => {
-    const ids = Array.from(selectedIds)
-    if (ids.length === 0) return
-    setBatchDownloading(true)
-    try {
-      // 发起批量下载任务
-      const { job_id } = await batchDownload(ids)
-      message.info(`批量下载任务已创建，正在打包 ${ids.length} 个视频...`)
-
-      // 轮询下载状态（最多 60 次，每次 2 秒）
-      let attempts = 0
-      const maxAttempts = 60
-      const poll = async (): Promise<void> => {
-        if (attempts >= maxAttempts) {
-          message.warning("打包超时，请稍后在消息中心查看")
-          return
-        }
-        attempts++
-        await new Promise((r) => setTimeout(r, 2000))
-        const status = await getBatchDownloadStatus(job_id)
-        if (status.status === "completed" && status.download_url) {
-          const a = document.createElement("a")
-          a.href = status.download_url
-          a.download = ""
-          a.click()
-          message.success(`已打包下载 ${ids.length} 个视频`)
-          setSelectedIds(new Set())
-        } else if (status.status === "failed") {
-          message.error("批量下载失败，请重试")
-        } else {
-          // 继续轮询
-          await poll()
-        }
-      }
-      await poll()
-    } catch {
-      message.error("发起批量下载失败")
-    } finally {
-      setBatchDownloading(false)
-    }
-  }
-
-  /* 批量删除 */
-  const handleBatchDelete = async () => {
-    const ids = Array.from(selectedIds)
-    let successCount = 0
-    for (const id of ids) {
-      try {
-        await deleteProduct(id)
-        successCount++
-      } catch {
-        // 忽略单个失败
-      }
-    }
-    queryClient.invalidateQueries({ queryKey: ["products"] })
-    setSelectedIds(new Set())
-    message.success(`已批量删除 ${successCount}/${ids.length} 个视频`)
-  }
-
-  /* 批量发布 */
-  const handleBatchPublish = () => {
-    // TODO: 对接后端批量发布 API
-    message.info("批量发布功能待后端 API 补齐")
-    setSelectedIds(new Set())
-  }
-
-  // ── Loading 状态 ──
  if (isLoading) {
    return (
      <div className="xx-products-page">
@@ -939,7 +194,7 @@ const ProductLibrary: React.FC = () => {
                批量删除
              </Button>
            </Popconfirm>
-            <Button buttonType="ghost" buttonSize="sm" onClick={() => setSelectedIds(new Set())}>
+            <Button buttonType="ghost" buttonSize="sm" onClick={clearSelection}>
              取消选择
            </Button>
          </div>
@@ -995,19 +250,7 @@ const ProductLibrary: React.FC = () => {
            value={filterProject}
            onChange={setFilterProject}
            style={{ width: 140 }}
-            options={[
-              { value: "all", label: "全部项目" },
-              ...Array.from(
-                new Map(
-                  products
-                    .filter((p) => p.projectId && p.projectName)
-                    .map((p) => [p.projectId!, p.projectName!] as const),
-                ),
-              ).map(([id, name]) => ({
-                value: id as string,
-                label: name as string,
-              })),
-            ]}
+            options={[{ value: "all", label: "全部项目" }, ...projectOptions]}
          />
          <Select
            value={filterReviewStatus}
@@ -0,0 +1,196 @@
+import React from "react"
+import { Popconfirm } from "antd"
+import {
+  CheckOutlined,
+  PlayCircleOutlined,
+  DownloadOutlined,
+  ShareAltOutlined,
+  DeleteOutlined,
+  CloudUploadOutlined,
+} from "@ant-design/icons"
+import type { ProductItem } from "../types"
+import { statusConfig, reviewStatusConfig } from "../constants"
+import { formatTime } from "../utils"
+
+interface ProductCardProps {
+  product: ProductItem
+  isSelected: boolean
+  batchMode: boolean
+  onToggleSelect: (id: string) => void
+  onPlay: (product: ProductItem) => void
+  onDownload: (product: ProductItem) => void
+  onShare: (product: ProductItem) => void
+  onDelete: (id: string) => void
+  onPublish: (product: ProductItem) => void
+  onReviewStatusChange: (id: string) => void
+}
+
+export const ProductCard: React.FC<ProductCardProps> = ({
+  product,
+  isSelected,
+  batchMode,
+  onToggleSelect,
+  onPlay,
+  onDownload,
+  onShare,
+  onDelete,
+  onPublish,
+  onReviewStatusChange,
+}) => {
+  const st = statusConfig[product.status]
+
+  /** 查重率样式 */
+  const dupClass =
+    product.duplicateRate <= 5 ? "good" : product.duplicateRate <= 15 ? "warn" : "bad"
+
+  /** 点击卡片 */
+  const handleCardClick = () => {
+    if (batchMode) {
+      onToggleSelect(product.id)
+    } else {
+      onPlay(product)
+    }
+  }
+
+  /** 点击复选框 */
+  const handleCheckboxClick = (e: React.MouseEvent) => {
+    e.stopPropagation()
+    onToggleSelect(product.id)
+  }
+
+  return (
+    <div
+      className={`xx-product-card${isSelected ? " selected" : ""}${product.isPublished ? " published" : ""}`}
+      onClick={handleCardClick}
+    >
+      {/* 复选框（左上角） */}
+      <div
+        className={`xx-product-card-checkbox${isSelected ? " checked" : ""}`}
+        onClick={handleCheckboxClick}
+        title={isSelected ? "取消选择" : "选择"}
+      >
+        {isSelected && <CheckOutlined />}
+      </div>
+
+      {/* 已发布徽章（右上角） */}
+      {product.isPublished && <div className="xx-product-badge">✅ 已发布</div>}
+
+      {/* 复核状态标签（右上角） */}
+      {product.reviewStatus && (
+        <div
+          className={`xx-product-review-tag ${reviewStatusConfig[product.reviewStatus].className}`}
+          onClick={(e) => {
+            e.stopPropagation()
+            onReviewStatusChange(product.id)
+          }}
+          title={`点击切换复核状态（当前：${reviewStatusConfig[product.reviewStatus].text}）`}
+        >
+          {reviewStatusConfig[product.reviewStatus].text}
+        </div>
+      )}
+      {/* 无复核状态时显示"待复核"入口 */}
+      {!product.reviewStatus && (
+        <div
+          className="xx-product-review-tag review-pending"
+          onClick={(e) => {
+            e.stopPropagation()
+            onReviewStatusChange(product.id)
+          }}
+          title="点击设置复核状态"
+        >
+          待复核
+        </div>
+      )}
+
+      {/* 缩略图 */}
+      <div className="xx-product-thumb">
+        {product.thumbnailUrl ? (
+          <img
+            className="xx-product-thumb-bg"
+            src={product.thumbnailUrl}
+            alt={product.name}
+            style={{ width: "100%", height: "100%", objectFit: "cover" }}
+          />
+        ) : (
+          <div className="xx-product-thumb-bg" style={{ background: product.gradient }} />
+        )}
+        <div className="xx-product-play">
+          <PlayCircleOutlined />
+        </div>
+        {product.duration > 0 && (
+          <span className="xx-product-duration">{formatTime(product.duration)}</span>
+        )}
+      </div>
+
+      {/* 信息区 */}
+      <div className="xx-product-info">
+        <h4 className="xx-product-title" title={product.name}>
+          {product.name}
+        </h4>
+        <div className="xx-product-meta">
+          <span className={`xx-product-status ${st.className}`}>{st.text}</span>
+          <span className="xx-product-date">{product.date}</span>
+        </div>
+        {product.duplicateRate > 0 && (
+          <span className={`xx-product-dup-rate ${dupClass}`}>
+            查重率：{product.duplicateRate.toFixed(1)}%
+          </span>
+        )}
+      </div>
+
+      {/* 操作按钮 */}
+      <div className="xx-product-actions" onClick={(e) => e.stopPropagation()}>
+        <button
+          className="xx-product-action-btn"
+          onClick={() => onDownload(product)}
+          disabled={product.status !== "completed"}
+          title="下载"
+        >
+          <DownloadOutlined /> 下载
+        </button>
+        <button
+          className="xx-product-action-btn"
+          onClick={() => onShare(product)}
+          disabled={product.status !== "completed"}
+          title="分享"
+        >
+          <ShareAltOutlined /> 分享
+        </button>
+        {product.isPublished ? (
+          <span className="xx-product-action-btn success" style={{ cursor: "default" }}>
+            ✅ 已发布
+          </span>
+        ) : (
+          <button
+            className="xx-product-action-btn primary"
+            onClick={() => onPublish(product)}
+            disabled={product.status !== "completed"}
+            title="发布"
+          >
+            <CloudUploadOutlined /> 发布
+          </button>
+        )}
+      </div>
+
+      {/* 删除按钮（不在批量模式下显示） */}
+      {!batchMode && (
+        <div style={{ padding: "0 14px 14px" }} onClick={(e) => e.stopPropagation()}>
+          <Popconfirm
+            title={`确定删除"${product.name}"？`}
+            onConfirm={() => onDelete(product.id)}
+            okText="删除"
+            cancelText="取消"
+          >
+            <button
+              className="xx-product-action-btn"
+              style={{ width: "100%", color: "#dc2626" }}
+              title="删除"
+            >
+              <DeleteOutlined /> 删除
+            </button>
+          </Popconfirm>
+        </div>
+      )}
+    </div>
+  )
+}
@@ -0,0 +1,199 @@
+import React, { useRef, useState, useEffect, useCallback } from "react"
+import {
+  VideoCameraOutlined,
+  PlayCircleOutlined,
+  PauseCircleOutlined,
+  CloseOutlined,
+  DownloadOutlined,
+  ShareAltOutlined,
+  EyeOutlined,
+} from "@ant-design/icons"
+import { Button } from "@/components/ui"
+import type { ProductItem } from "../types"
+import { formatTime, formatSize } from "../utils"
+
+interface VideoPlayerProps {
+  product: ProductItem
+  onClose: () => void
+  onDownload: (product: ProductItem) => void
+  onShare: (product: ProductItem) => void
+  onViewDetail: (product: ProductItem) => void
+}
+
+export const VideoPlayer: React.FC<VideoPlayerProps> = ({
+  product,
+  onClose,
+  onDownload,
+  onShare,
+  onViewDetail,
+}) => {
+  const videoRef = useRef<HTMLVideoElement>(null)
+  const progressRef = useRef<HTMLDivElement>(null)
+  const [isPlaying, setIsPlaying] = useState(false)
+  const [currentTime, setCurrentTime] = useState(0)
+  const [duration, setDuration] = useState(product.duration)
+
+  const hasVideo = !!product.videoUrl
+
+  /** 播放/暂停 */
+  const handlePlayPause = useCallback(() => {
+    const video = videoRef.current
+    if (!video) return
+    if (isPlaying) {
+      video.pause()
+    } else {
+      video.play().catch(() => {})
+    }
+    setIsPlaying(!isPlaying)
+  }, [isPlaying])
+
+  /** 视频事件监听 */
+  useEffect(() => {
+    const video = videoRef.current
+    if (!video) return
+    const onTime = () => setCurrentTime(video.currentTime)
+    const onDur = () => setDuration(video.duration || product.duration)
+    const onEnd = () => setIsPlaying(false)
+    video.addEventListener("timeupdate", onTime)
+    video.addEventListener("loadedmetadata", onDur)
+    video.addEventListener("ended", onEnd)
+    return () => {
+      video.removeEventListener("timeupdate", onTime)
+      video.removeEventListener("loadedmetadata", onDur)
+      video.removeEventListener("ended", onEnd)
+    }
+  }, [product.duration])
+
+  /** 进度条点击 */
+  const handleProgressClick = (e: React.MouseEvent<HTMLDivElement>) => {
+    if (!progressRef.current) return
+    const rect = progressRef.current.getBoundingClientRect()
+    const percent = (e.clientX - rect.left) / rect.width
+    const newTime = percent * duration
+    setCurrentTime(newTime)
+    if (videoRef.current) videoRef.current.currentTime = newTime
+  }
+
+  /** ESC 关闭 */
+  useEffect(() => {
+    const handleKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose()
+    }
+    window.addEventListener("keydown", handleKey)
+    return () => window.removeEventListener("keydown", handleKey)
+  }, [onClose])
+
+  const progress = duration > 0 ? (currentTime / duration) * 100 : 0
+
+  return (
+    <div className="xx-player-overlay" onClick={onClose}>
+      <div className="xx-player-container" onClick={(e) => e.stopPropagation()}>
+        {/* 视频区域 */}
+        <div className="xx-player-video-wrap">
+          {hasVideo ? (
+            <video
+              ref={videoRef}
+              src={product.videoUrl}
+              style={{ width: "100%", height: "100%", objectFit: "contain" }}
+            />
+          ) : (
+            /* 无视频 URL 时用渐变占位 */
+            <div
+              style={{
+                width: "100%",
+                height: "100%",
+                background: product.gradient,
+                display: "grid",
+                placeItems: "center",
+                color: "rgba(255,255,255,0.3)",
+                fontSize: "64px",
+              }}
+            >
+              <VideoCameraOutlined />
+            </div>
+          )}
+
+          {/* 播放/暂停按钮 */}
+          <button className="xx-player-play-btn" onClick={handlePlayPause}>
+            {isPlaying ? <PauseCircleOutlined /> : <PlayCircleOutlined />}
+          </button>
+
+          {/* 关闭按钮 */}
+          <button className="xx-player-close" onClick={onClose}>
+            <CloseOutlined />
+          </button>
+
+          {/* 进度条 */}
+          <div className="xx-player-progress-wrap">
+            <div ref={progressRef} className="xx-player-progress" onClick={handleProgressClick}>
+              <div className="xx-player-progress-bar" style={{ width: `${progress}%` }} />
+            </div>
+            <div className="xx-player-time">
+              <span>{formatTime(currentTime)}</span>
+              <span>{formatTime(duration)}</span>
+            </div>
+          </div>
+        </div>
+
+        {/* 信息区 */}
+        <div className="xx-player-info">
+          <h3 className="xx-player-title">{product.name}</h3>
+          <div className="xx-player-details">
+            <div className="xx-player-detail-item">
+              <span className="xx-player-detail-label">分辨率：</span>
+              <span className="xx-player-detail-value">{product.resolution}</span>
+            </div>
+            <div className="xx-player-detail-item">
+              <span className="xx-player-detail-label">时长：</span>
+              <span className="xx-player-detail-value">{formatTime(product.duration)}</span>
+            </div>
+            <div className="xx-player-detail-item">
+              <span className="xx-player-detail-label">文件大小：</span>
+              <span className="xx-player-detail-value">{formatSize(product.fileSize)}</span>
+            </div>
+            <div className="xx-player-detail-item">
+              <span className="xx-player-detail-label">查重率：</span>
+              <span className="xx-player-detail-value">
+                {product.duplicateRate > 0 ? `${product.duplicateRate.toFixed(1)}%` : "-"}
+              </span>
+            </div>
+          </div>
+        </div>
+
+        {/* 底部操作 */}
+        <div className="xx-player-footer">
+          <Button
+            buttonType="ghost"
+            buttonSize="sm"
+            icon={<DownloadOutlined />}
+            onClick={() => onDownload(product)}
+            disabled={product.status !== "completed"}
+          >
+            下载视频
+          </Button>
+          <Button
+            buttonType="ghost"
+            buttonSize="sm"
+            icon={<ShareAltOutlined />}
+            onClick={() => onShare(product)}
+            disabled={product.status !== "completed"}
+          >
+            分享
+          </Button>
+          <Button
+            buttonType="ghost"
+            buttonSize="sm"
+            icon={<EyeOutlined />}
+            onClick={() => onViewDetail(product)}
+          >
+            查看详情
+          </Button>
+          <div style={{ flex: 1 }} />
+          <Button buttonType="primary" buttonSize="sm" onClick={onClose}>
+            关闭
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}
@@ -0,0 +1,34 @@
+import type { ReviewStatus } from "@/api/products"
+import type { ProductStatus } from "./types"
+
+/** 渐变色列表（按 id hash 选取） */
+export const GRADIENTS = [
+  "linear-gradient(135deg, #1e1b4b 0%, #4f46e5 50%, #818cf8 100%)",
+  "linear-gradient(135deg, #831843 0%, #db2777 50%, #f472b6 100%)",
+  "linear-gradient(135deg, #064e3b 0%, #059669 50%, #34d399 100%)",
+  "linear-gradient(135deg, #78350f 0%, #d97706 50%, #fbbf24 100%)",
+  "linear-gradient(135deg, #1e3a5f 0%, #2563eb 50%, #60a5fa 100%)",
+  "linear-gradient(135deg, #581c87 0%, #9333ea 50%, #c084fc 100%)",
+  "linear-gradient(135deg, #7f1d1d 0%, #dc2626 50%, #f87171 100%)",
+  "linear-gradient(135deg, #134e4a 0%, #0d9488 50%, #5eead4 100%)",
+  "linear-gradient(135deg, #1e1b4b 0%, #6366f1 50%, #a5b4fc 100%)",
+  "linear-gradient(135deg, #3b0764 0%, #7c3aed 50%, #a78bfa 100%)",
+  "linear-gradient(135deg, #052e16 0%, #16a34a 50%, #86efac 100%)",
+  "linear-gradient(135deg, #450a0e 0%, #e11d48 50%, #fb7185 100%)",
+]
+
+export const statusConfig: Record<ProductStatus, { text: string; className: string }> = {
+  completed: { text: "已完成", className: "completed" },
+  processing: { text: "处理中", className: "processing" },
+  review: { text: "待复核", className: "review" },
+  failed: { text: "失败", className: "failed" },
+}
+
+export const reviewStatusConfig: Record<ReviewStatus, { text: string; className: string }> = {
+  pending_review: { text: "待复核", className: "review-pending" },
+  approved: { text: "已通过", className: "review-approved" },
+  rejected: { text: "需修改", className: "review-rejected" },
+}
+
+/** 复核状态循环顺序 */
+export const REVIEW_STATUS_CYCLE: ReviewStatus[] = ["pending_review", "approved", "rejected"]
--- a/Show More
+++ b/Show More