fix(generate): 修复 usePlanConfigLoader 隐式any类型

fix(generate): 修复 useTitleCoverSync 缺少 CoverConfig 导入和隐式any
fix(generate): 修复 useTemplateSelection 缺少 queryFn 和类型定义
2026-07-29 19:03:55 +08:00 · 2026-07-29 19:03:53 +08:00 · 2026-07-29 19:03:52 +08:00 · 2026-07-29 19:03:52 +08:00 · 2026-07-29 18:39:20 +08:00 · 2026-07-29 18:31:41 +08:00
1031 changed files with 150638 additions and 40390 deletions
@@ -1,60 +1,198 @@
-# 小虾 SaaS 环境变量配置
+# ============================================================
+# 小虾 SaaS 环境变量完整配置
+# ============================================================
+# 本文件列出所有可配置的环境变量及默认值。
+# 复制为 .env 后按需修改；生产环境务必覆盖所有密钥类配置。
+#
+# 配置读取规则（pydantic-settings，大小写不敏感）：
+#   1. 系统环境变量（最高优先级）
+#   2. .env.{APP_ENV} 文件（如 .env.staging）
+#   3. .env 文件
+#   4. 代码中的默认值（最低优先级）
+# ============================================================

-# ==================== 应用配置 ====================
-APP_NAME=小虾 SaaS
-APP_BASE_URL=http://localhost:3000
+
+# ==================== 应用基本配置 ====================
+
+# 应用名称
+APP_NAME=xiaoxia-saas
+
+# 应用版本号（展示用，代码中已内置默认）
+APP_VERSION=0.1.61
+
+# 环境标识：development / staging / production
+# 决定读取 .env.{APP_ENV} 还是 .env，也影响部分配置的严格校验
 APP_ENV=development

-# ==================== 数据库配置 ====================
-DATABASE_URL=postgresql://xiaoxia_user:your_password@localhost:5432/xiaoxia_saas
-
-# 开发环境：使用内存数据库（不需要 PostgreSQL）
-USE_IN_MEMORY_DB=true
-
-# 生产环境：使用 PostgreSQL
-# USE_IN_MEMORY_DB=false
-
-# ==================== Redis 配置 ====================
-REDIS_URL=redis://localhost:6379/0
-
-# ==================== JWT 配置 ====================
-JWT_SECRET_KEY=your-super-secret-key-change-this-in-production-min-32-chars
-JWT_ALGORITHM=HS256
-JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
-JWT_REFRESH_TOKEN_EXPIRE_DAYS=30
-
-# ==================== 邮件配置 ====================
-SMTP_HOST=smtp.gmail.com
-SMTP_PORT=587
-SMTP_USER=your-email@gmail.com
-SMTP_PASSWORD=your-app-specific-password
-SMTP_FROM_EMAIL=noreply@xiaoxia-saas.com
-SMTP_FROM_NAME=小虾 SaaS
-
-# ==================== 环境配置 ====================
-ENVIRONMENT=development
+# 是否开启 Debug 模式（开发环境 true，生产环境 false）
 DEBUG=true

-# ==================== CORS 配置 ====================
-# 逗号分隔的域名列表（Settings 读取 CORS_ORIGINS_RAW）
-CORS_ORIGINS_RAW=http://localhost:3000,http://localhost:5173
+# 应用基础 URL，用于生成认证邮件、回调链接等
+APP_BASE_URL=http://localhost:3000
+
+# API 服务监听地址（容器内绑定，外部暴露由 Docker/Nginx 控制）
+API_HOST=0.0.0.0
+
+# API 服务监听端口
+API_PORT=8000
+
+# 是否自动创建数据库表结构（开发环境可开启，生产环境用 alembic migration）
+AUTO_CREATE_SCHEMA=false
+
+
+# ==================== 数据库配置 ====================
+
+# 数据库连接串（格式：postgresql+psycopg://user:password@host:port/dbname）
+DATABASE_URL=postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas
+
+# 连接池大小（常驻连接数）
+DATABASE_POOL_SIZE=20
+
+# 连接池最大溢出连接数（pool_size + max_overflow = 最大并发连接数）
+DATABASE_MAX_OVERFLOW=10
+
+# 获取连接超时时间（秒）
+DATABASE_POOL_TIMEOUT=30
+
+# 连接回收时间（秒），防止数据库端主动断开导致的死连接
+DATABASE_POOL_RECYCLE=3600
+
+# 是否使用内存数据库（SQLite，仅开发/测试可用；生产务必 false）
+USE_IN_MEMORY_DB=false
+
+
+# ==================== Redis 配置 ====================
+
+# Redis 连接 URL（格式：redis://[:password@]host:port/db）
+REDIS_URL=redis://localhost:6379/0
+
+# 是否使用 Redis 存储 Session（多实例部署时必须开启；开发可用内存存储）
+ENABLE_REDIS_SESSIONS=false
+
+
+# ==================== Celery 任务队列 ====================
+
+# Celery Broker（任务分发），默认用 Redis db0
+CELERY_BROKER_URL=redis://localhost:6379/0
+
+# Celery Result Backend（任务结果存储），默认用 Redis db1
+CELERY_RESULT_BACKEND=redis://localhost:6379/1
+
+
+# ==================== Worker 配置 ====================
+
+# Worker 进程名称
+WORKER_NAME=xiaoxia-saas-worker
+
+# Worker 并发数（同时执行的任务数）
+WORKER_CONCURRENCY=4
+
+# 每个子进程最多处理多少任务后重启（防止内存泄漏）
+WORKER_MAX_TASKS_PER_CHILD=1000
+
+
+# ==================== JWT 认证配置 ====================
+
+# JWT 签名密钥 — 生产环境必须设置为强随机字符串（至少32字符）
+# 内置不安全值会被拒绝：secret / changeme / password / your-secret-key 等
+JWT_SECRET_KEY=your-super-secret-key-change-this-in-production-min-32-chars
+
+# JWT 签名算法
+JWT_ALGORITHM=HS256
+
+# Access Token 过期时间（分钟）
+JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
+
+# Refresh Token 过期时间（天）
+JWT_REFRESH_TOKEN_EXPIRE_DAYS=30
+
+
+# ==================== 邮件配置 ====================
+
+# 是否启用邮件投递（关闭时邮件内容打印到日志，开发调试用）
+ENABLE_EMAIL_DELIVERY=false
+
+# SMTP 服务器地址
+SMTP_HOST=smtp.gmail.com
+
+# SMTP 端口
+SMTP_PORT=587
+
+# SMTP 用户名
+SMTP_USER=your-email@gmail.com
+
+# SMTP 密码 / 应用专用密码
+SMTP_PASSWORD=your-app-specific-password
+
+# 发件人邮箱
+SMTP_FROM_EMAIL=noreply@xiaoxia-saas.com
+
+# 发件人显示名称
+SMTP_FROM_NAME=小虾 SaaS
+
+# 是否启用 TLS
+SMTP_USE_TLS=true
+

 # ==================== 阿里云 OSS 配置 ====================
+
+# OSS 区域 endpoint
 OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
+
+# OSS Access Key ID — 非开发环境必须设置
 OSS_ACCESS_KEY_ID=your-access-key-id
+
+# OSS Access Key Secret — 非开发环境必须设置
 OSS_ACCESS_KEY_SECRET=your-access-key-secret
+
+# OSS Bucket 名称
 OSS_BUCKET_NAME=xiaoxia-autocut

-# ==================== CosyVoice 语音合成配置 ====================
-# 注意：base_url 只需写到 /api/v1，具体路径由代码拼接
-# 模型: cosyvoice-v3-flash (推荐，支持系统音色，性价比高)
-#       cosyvoice-v3-plus (高质量，系统音色少)
-#       cosyvoice-v3.5-flash / cosyvoice-v3.5-plus (仅支持克隆/设计音色，无系统音色)
-# 音色: v3系列系统音色带 _v3 后缀，如 longxiaochun_v3, longxiaoxia_v3, longanyang (无后缀)
-# 注意：COSYVOICE_* 变量由 packages/shared/config.py 的 SharedSettings 读取
+# 直传最大文件大小（MB）
+OSS_DIRECT_UPLOAD_MAX_MB=2000
+
+# 直传签名有效期（秒）
+OSS_DIRECT_UPLOAD_EXPIRE_SECONDS=900
+
+
+# ==================== CORS 配置 ====================
+
+# 允许跨域的前端域名列表，逗号分隔
+CORS_ORIGINS_RAW=http://localhost:3000,http://localhost:5173,http://localhost:8000
+
+
+# ==================== 渲染引擎配置 ====================
+
+# 渲染引擎选择：
+#   legacy   — 旧 VideoComposeService（稳定，功能完整）
+#   unified  — 新 UnifiedRenderService（新架构，部分场景仍在验证）
+RENDER_ENGINE=legacy
+
+
+# ==================== CosyVoice 语音合成 ====================
+# 阿里云百灵语音合成服务
+# 模型选择：
+#   cosyvoice-v3-flash  — 推荐，系统音色多，性价比高
+#   cosyvoice-v3-plus   — 高质量，系统音色少
+#   cosyvoice-v3.5-flash / cosyvoice-v3.5-plus — 仅支持克隆/设计音色，无系统音色
+# 音色：v3 系列系统音色带 _v3 后缀，如 longxiaochun_v3 / longxiaoxia_v3 / longanyang
+
 COSYVOICE_API_KEY=your-cosyvoice-api-key
 COSYVOICE_BASE_URL=https://dashscope.aliyuncs.com/api/v1
 COSYVOICE_MODEL=cosyvoice-v3-flash
 COSYVOICE_VOICE=longxiaochun_v3
 COSYVOICE_SAMPLE_RATE=22050
 COSYVOICE_FORMAT=mp3
+
+# 音色克隆模型名（固定为 voice-enrollment，通常不需修改）
+COSYVOICE_CLONE_MODEL=voice-enrollment
+
+
+# ==================== 豆包大模型（火山引擎方舟） ====================
+# 用于 AI 文案生成、智能剪辑等需要大模型能力的场景
+
+DOUBAO_API_KEY=your-doubao-api-key
+DOUBAO_MODEL=doubao-seed-1-6-250615
+DOUBAO_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
+DOUBAO_TIMEOUT=30
+DOUBAO_MAX_RETRIES=2
@@ -0,0 +1,161 @@
+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
+        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
+
+      # ====== 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
@@ -0,0 +1,78 @@
+name: CI Failure Monitor
+
+on:
+  schedule:
+    - cron: '0 */6 * * *'  # 每6小时检查一次
+  workflow_dispatch:
+    inputs:
+      days:
+        description: '统计最近N天的失败'
+        required: false
+        default: '7'
+      fail_threshold:
+        description: '失败次数阈值'
+        required: false
+        default: '3'
+      fail_rate_threshold:
+        description: '失败率阈值(%)'
+        required: false
+        default: '30'
+
+permissions:
+  contents: read
+
+jobs:
+  monitor:
+    name: CI重复失败检测
+    runs-on: ci-l2
+    timeout-minutes: 10
+
+    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: Run failure detection
+      shell: sh
+      env:
+        GITEA_API_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+        GITEA_URL: https://git.xiaoxiajianji.com
+        GITEA_REPO: xiaoxia/xiaoxia-saas
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+        FAIL_CHECK_DAYS: ${{ inputs.days || 7 }}
+        FAIL_THRESHOLD: ${{ inputs.fail_threshold || 3 }}
+        FAIL_RATE_THRESHOLD: ${{ inputs.fail_rate_threshold || 30 }}
+      run: |
+        set +e
+        python3 scripts/ci/ci_repeated_failure_detector.py
+        EXIT_CODE=$?
+        echo "检测完成，退出码: $EXIT_CODE"
+        # 0=无异常, 1=有警告, 2=有严重问题
+        # 监控脚本永远不fail，避免告警风暴
+        exit 0
+
+    - name: Job duration summary
+      if: always()
+      shell: sh
+      run: bash scripts/ci/step_timer_end.sh
+
+    - 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
@@ -1,19 +1,15 @@
 name: CI Health Daily Report
-
 on:
  schedule:
    - cron: '0 1 * * *'  # UTC 01:00 = 北京时间 09:00
  workflow_dispatch:
-
 permissions:
  contents: read
-
 jobs:
  ci-health-report:
    name: CI健康度每日巡检
-    runs-on: saas
-    timeout-minutes: 10
-
+    runs-on: ci-l2
+    timeout-minutes: 15
    steps:
    - name: Checkout code
      shell: sh
@@ -61,6 +57,34 @@ jobs:
                    tar.extract(member, '.')
        PY

+    - name: Generate CI Dashboard HTML
+      shell: sh
+      env:
+        GITEA_TOKEN: ${{ github.token }}
+      run: |
+        set +e
+        echo "=== 生成 CI 健康度 HTML 看板 ==="
+        echo "时间: $(date '+%Y-%m-%d %H:%M:%S')"
+        echo ""
+        python3 scripts/ci/ci_dashboard.py --days 7 --html --html-output ci_dashboard.html
+        EXIT_CODE=$?
+        if [ $EXIT_CODE -eq 0 ] && [ -f ci_dashboard.html ]; then
+            HTML_SIZE=$(wc -c < ci_dashboard.html)
+            echo ""
+            echo "✅ HTML 看板生成成功 (${HTML_SIZE} bytes)"
+            echo "路径: $(pwd)/ci_dashboard.html"
+            # 输出文件内容前几行，方便在 Actions 日志中确认
+            echo ""
+            echo "--- 看板预览 (前 5 行) ---"
+            head -5 ci_dashboard.html
+            echo "...（完整内容见产物文件）"
+        else
+            echo "❌ HTML 看板生成失败 (exit code: $EXIT_CODE)"
+        fi
+        echo ""
+        # 永远成功，看板生成失败不影响主流程
+        exit 0
+
    - name: Run CI health check and report
      shell: sh
      env:
@@ -71,10 +95,8 @@ jobs:
        echo "=== CI健康度每日巡检 ==="
        echo "时间: $(date '+%Y-%m-%d %H:%M:%S')"
        echo ""
-
        python3 scripts/ci/ci_health_report.py --limit 30
        EXIT_CODE=$?
-
        echo ""
        echo "巡检完成 (exit code: $EXIT_CODE)"
        # 永远成功，不影响CI状态（通知失败不应该标红）
@@ -10,6 +10,8 @@ on:
    branches:
    - main
    - develop
+  schedule:
+    - cron: '0 19 * * *'  # UTC 19:00 = 北京时间凌晨3:00，每日全量CI回归
  workflow_dispatch:
    inputs:
      reason:
@@ -20,7 +22,8 @@ permissions:
  contents: read
 concurrency:
  group: ci-pipeline-${{ gitea.event_name }}-${{ gitea.ref }}
-  cancel-in-progress: true
+  # PR事件取消进行中的旧run，push事件不取消（确保完整CI跑完）
+  cancel-in-progress: ${{ gitea.event_name == 'pull_request' }}
 jobs:
  check-frontend-only:
    name: Check if frontend-only change
@@ -76,18 +79,12 @@ jobs:
        [ -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

-  validate:
-    needs: check-frontend-only
-    if: always() && needs.check-frontend-only.outputs.skip_backend != 'true'
-    name: Validate Code Quality And Tests
+  validate-code-quality:
+    name: Validate - Code Quality
    runs-on: ci-l2
-    timeout-minutes: 10
+    timeout-minutes: 8
    permissions:
      contents: write
-    env:
-      DATABASE_URL: postgresql+psycopg://postgres:postgres@host.docker.internal:5432/xiaoxia_saas
-      USE_IN_MEMORY_DB: 'false'
-      CI_USE_SHARED_PG: 'true'
    steps:
    - name: Checkout code
      shell: sh
@@ -102,7 +99,6 @@ jobs:
      shell: sh
      run: |
        set -eu
-        # pip install 带重试（网络不稳定时自动重试）
        for i in 1 2 3; do
          python3 -m pip install -q -r requirements-base.txt && break
          echo "pip install requirements-base.txt 失败，重试 $i/3..."
@@ -127,16 +123,17 @@ jobs:
          [ $i -eq 3 ] && exit 1
          sleep 5
        done
-    - name: Run all quality checks
+    - name: Run code quality and security checks
      shell: bash
      env:
        GITHUB_TOKEN: ${{ github.token }}
-      run: bash scripts/ci/run_validate.sh
+      run: bash scripts/ci/validate_code_quality.sh
    - name: Auto-fix formatting (black + isort)
      if: failure()
      shell: sh
      env:
        GITHUB_TOKEN: ${{ github.token }}
+        REVIEW_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
      run: python3 scripts/ci/auto_fix_formatting.py
    - name: CI failure notification
      if: failure()
@@ -146,7 +143,7 @@ jobs:
        CI_WEBHOOK_URL: ${{ secrets.CI_WEBHOOK_URL }}
      run: |
        set +e
-        FAILED_JOB="Validate Code Quality And Tests" python3 scripts/ci_notify_failure.py
+        FAILED_JOB="Validate - Code Quality" python3 scripts/ci_notify_failure.py
    - name: Job duration summary
      if: always()
      shell: sh
@@ -159,7 +156,161 @@ jobs:
        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
      run: |
        set +e
-        NOTIFY_MODE=failure JOB_NAME="Validate Code Quality And Tests" python3 scripts/ci_notify.py
+        NOTIFY_MODE=failure JOB_NAME="Validate - Code Quality" 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
+
+  validate-type-check:
+    name: Validate - Type Check (mypy)
+    runs-on: ci-l2
+    timeout-minutes: 8
+    permissions:
+      contents: read
+    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: Install dependencies
+      shell: sh
+      run: |
+        set -eu
+        for i in 1 2 3; do
+          python3 -m pip install -q -r requirements-base.txt && break
+          echo "pip install requirements-base.txt 失败，重试 $i/3..."
+          [ $i -eq 3 ] && exit 1
+          sleep 5
+        done
+        for i in 1 2 3; do
+          python3 -m pip install -q -r requirements.txt && break
+          echo "pip install requirements.txt 失败，重试 $i/3..."
+          [ $i -eq 3 ] && exit 1
+          sleep 5
+        done
+        for i in 1 2 3; do
+          python3 -m pip install -q -r requirements-dev.txt && break
+          echo "pip install requirements-dev.txt 失败，重试 $i/3..."
+          [ $i -eq 3 ] && exit 1
+          sleep 5
+        done
+    - name: Run mypy type check
+      shell: bash
+      run: bash scripts/ci/validate_mypy.sh
+    - name: CI failure notification
+      if: failure()
+      shell: sh
+      env:
+        GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+        CI_WEBHOOK_URL: ${{ secrets.CI_WEBHOOK_URL }}
+      run: |
+        set +e
+        FAILED_JOB="Validate - Type Check (mypy)" python3 scripts/ci_notify_failure.py
+    - name: Job duration summary
+      if: always()
+      shell: sh
+      run: bash scripts/ci/step_timer_end.sh
+    - 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="Validate - Type Check (mypy)" 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
+
+  validate-migration:
+    name: Validate - Migration (alembic)
+    runs-on: ci-l2
+    timeout-minutes: 8
+    permissions:
+      contents: read
+    env:
+      DATABASE_URL: postgresql+psycopg://postgres:postgres@host.docker.internal:5432/xiaoxia_saas
+      USE_IN_MEMORY_DB: 'false'
+      CI_USE_SHARED_PG: 'true'
+    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: Install dependencies
+      shell: sh
+      run: |
+        set -eu
+        for i in 1 2 3; do
+          python3 -m pip install -q -r requirements-base.txt && break
+          echo "pip install requirements-base.txt 失败，重试 $i/3..."
+          [ $i -eq 3 ] && exit 1
+          sleep 5
+        done
+        for i in 1 2 3; do
+          python3 -m pip install -q -r requirements.txt && break
+          echo "pip install requirements.txt 失败，重试 $i/3..."
+          [ $i -eq 3 ] && exit 1
+          sleep 5
+        done
+        for i in 1 2 3; do
+          python3 -m pip install -q -r requirements-dev.txt && break
+          echo "pip install requirements-dev.txt 失败，重试 $i/3..."
+          [ $i -eq 3 ] && exit 1
+          sleep 5
+        done
+    - name: Run alembic migration validation
+      shell: bash
+      run: bash scripts/ci/validate_migration.sh
+    - name: CI failure notification
+      if: failure()
+      shell: sh
+      env:
+        GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+        CI_WEBHOOK_URL: ${{ secrets.CI_WEBHOOK_URL }}
+      run: |
+        set +e
+        FAILED_JOB="Validate - Migration (alembic)" python3 scripts/ci_notify_failure.py
+    - name: Job duration summary
+      if: always()
+      shell: sh
+      run: bash scripts/ci/step_timer_end.sh
+    - 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="Validate - Migration (alembic)" python3 scripts/ci_notify.py
    - name: Report CI trace
      if: always()
      shell: sh
@@ -244,7 +395,9 @@ jobs:
    if: always() && needs.check-frontend-only.outputs.skip_backend != 'true'
    needs:
      - check-frontend-only
-      - validate
+      - validate-code-quality
+      - validate-type-check
+      - validate-migration
    env:
      DATABASE_URL: postgresql+psycopg://postgres:postgres@host.docker.internal:5432/xiaoxia_saas
      USE_IN_MEMORY_DB: 'false'
@@ -305,6 +458,8 @@ jobs:
    name: Frontend Lint
    runs-on: ci-l2
    timeout-minutes: 10
+    needs: check-frontend-only
+    if: needs.check-frontend-only.outputs.skip_frontend != 'true'
    steps:
    - name: Checkout code
      shell: sh
@@ -423,7 +578,12 @@ jobs:
    name: PR Build ${{ matrix.service_display }} Image
    runs-on: runtime-builder
    timeout-minutes: ${{ matrix.timeout }}
-    if: github.event_name == 'pull_request'
+    needs: check-frontend-only
+    if: |
+      github.event_name == 'pull_request' && (
+        (matrix.service == 'web' && needs.check-frontend-only.outputs.skip_frontend != 'true') ||
+        (matrix.service != 'web' && needs.check-frontend-only.outputs.skip_backend != 'true')
+      )
    strategy:
      fail-fast: false
      matrix:
@@ -474,6 +634,60 @@ jobs:
          echo "Docker login failed ($i/3), retrying in 5s..."
          sleep 5
        done
+    - name: Pre-build worker base images (fallback if not exist)
+      if: matrix.service == 'worker'
+      id: prebuild
+      shell: sh
+      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模式）..."
+          
+          # 尝试用buildx构建，失败则回退到普通docker build（DooD模式下buildx builder偶发崩溃）
+          BUILDER_NAME="ci-pr-builder-${GITHUB_RUN_ID:-local}"
+          BUILDX_AVAILABLE=true
+          if ! docker buildx create --use --name "$BUILDER_NAME" --driver docker-container > /dev/null 2>&1; then
+            BUILDX_AVAILABLE=false
+          fi
+          if [ "$BUILDX_AVAILABLE" = true ] && ! docker buildx inspect --bootstrap > /dev/null 2>&1; then
+            BUILDX_AVAILABLE=false
+            docker buildx rm "$BUILDER_NAME" > /dev/null 2>&1 || true
+          fi
+          
+          build_base() {
+            local df="$1"
+            local tag="$2"
+            local name="$3"
+            if [ "$BUILDX_AVAILABLE" = true ]; then
+              echo "构建 $name（buildx）..."
+              if docker buildx build --load -f "$df" -t "$tag" . > /dev/null 2>&1; then
+                echo "$name 构建成功"
+                return 0
+              fi
+              echo "buildx失败，回退到普通docker build"
+              BUILDX_AVAILABLE=false
+              docker buildx rm "$BUILDER_NAME" > /dev/null 2>&1 || true
+            fi
+            echo "构建 $name（docker build）..."
+            docker build -f "$df" -t "$tag" .
+          }
+          
+          build_base infra/docker/worker-base-builder.Dockerfile "$BASE_BUILDER" "worker-base-builder"
+          build_base infra/docker/worker-base-runtime.Dockerfile "$BASE_RUNTIME" "worker-base-runtime"
+          
+          echo "fallback=true" >> $GITHUB_OUTPUT
+          echo "基础镜像本地构建完成"
+        fi
+
    - name: Build PR image (verify only, no push)
      shell: sh
      run: |
@@ -487,6 +701,18 @@ 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（基础镜像本地已构建）"
+          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"
+          exit 0
+        fi
+
        NO_CACHE_FLAG=""
        for i in 1 2 3; do
          echo "PR Build attempt $i/3"
@@ -859,18 +1085,28 @@ jobs:
      shell: sh
      run: bash scripts/ci/step_timer_start.sh
    - name: Run Playwright E2E on staging
-      shell: sh
+      shell: bash
      run: |
        set -eu
-        docker run --rm --ipc=host \
+        # DooD模式下不能用-v挂载（宿主机路径与CI容器路径不一致）
+        # 改用 docker create + docker cp 方式把代码拷进容器
+        CONTAINER_NAME="staging-e2e-$$"
+        # 强制清理可能残留的同名容器（上一次异常退出时未清理）
+        docker rm -f "$CONTAINER_NAME" 2>/dev/null || true
+        docker create --name "$CONTAINER_NAME" --ipc=host \
          -e E2E_BASE_URL=https://staging.xiaoxiajianji.com \
          -e E2E_API_BASE=https://staging-api.xiaoxiajianji.com/api/v1 \
          -e E2E_BROWSER_CHANNEL=chromium \
          -e PLAYWRIGHT_HEADLESS=1 \
-          -v "$PWD:/workspace" \
          -w /workspace/apps/web \
          git.xiaoxiajianji.com/xiaoxia/base/playwright:v1.45.0-jammy \
          sh -lc "npm ci && npx playwright test --reporter=line --project=chromium e2e/auth.spec.ts e2e/auth-guard.spec.ts e2e/core-upload.spec.ts e2e/core-generation.spec.ts"
+        docker cp apps "$CONTAINER_NAME:/workspace/"
+        docker cp package-lock.json "$CONTAINER_NAME:/workspace/" 2>/dev/null || true
+        docker start -a "$CONTAINER_NAME"
+        EXIT_CODE=$(docker wait "$CONTAINER_NAME")
+        docker rm "$CONTAINER_NAME" 2>/dev/null || true
+        exit $EXIT_CODE

    - name: Job duration summary
      if: always()
@@ -915,16 +1151,24 @@ 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
-        docker run --rm \
+        # DooD模式下不能用-v挂载（宿主机路径与CI容器路径不一致）
+        # 改用 docker create + docker cp 方式把代码拷进容器
+        CONTAINER_NAME="staging-api-tests-$$"
+        docker create --name "$CONTAINER_NAME" \
          -e E2E_BASE_URL=https://staging.xiaoxiajianji.com \
          -e E2E_API_BASE=https://staging-api.xiaoxiajianji.com/api/v1 \
-          -v "$PWD:/workspace" \
          -w /workspace/apps/web \
          git.xiaoxiajianji.com/xiaoxia/base/playwright:v1.45.0-jammy \
          sh -lc 'npm ci && npx playwright test --reporter=line e2e/test_auth.spec.ts e2e/test_asset.spec.ts e2e/test_project.spec.ts'
+        docker cp apps "$CONTAINER_NAME:/workspace/"
+        docker cp package-lock.json "$CONTAINER_NAME:/workspace/" 2>/dev/null || true
+        docker start -a "$CONTAINER_NAME"
+        EXIT_CODE=$(docker wait "$CONTAINER_NAME")
+        docker rm "$CONTAINER_NAME" 2>/dev/null || true
+        exit $EXIT_CODE

    - name: Job duration summary
      if: always()
@@ -957,7 +1201,12 @@ jobs:
    runs-on: runtime-builder
    timeout-minutes: ${{ matrix.timeout }}
    needs:
-    if: startsWith(github.ref, 'refs/tags/v')
+      - validate-code-quality
+      - validate-type-check
+      - unit-tests
+      - frontend-lint
+      - frontend-unit-test
+    if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'push' && github.ref_name == 'main')
    strategy:
      fail-fast: false
      matrix:
@@ -1030,14 +1279,20 @@ jobs:
        docker buildx inspect --bootstrap

    - name: Build and push production ${{ matrix.service_display }} image (with retry)
-      shell: sh
+      shell: bash
      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
@@ -1337,3 +1592,274 @@ jobs:
        [ -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

+  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
+
+  ci-gate:
+    name: CI Gate
+    runs-on: ci-l2
+    if: always() && github.event_name == 'pull_request'
+    needs:
+      - check-frontend-only
+      - validate-code-quality
+      - validate-type-check
+      - validate-migration
+      - unit-tests
+      - integration-tests
+      - frontend-lint
+      - frontend-unit-test
+      - build-pr
+    timeout-minutes: 3
+    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: Evaluate CI Gate
+        id: gate
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          RESULT_CHECK_FRONTEND: ${{ needs.check-frontend-only.result }}
+          RESULT_CODE_QUALITY: ${{ needs.validate-code-quality.result }}
+          RESULT_TYPE_CHECK: ${{ needs.validate-type-check.result }}
+          RESULT_MIGRATION: ${{ needs.validate-migration.result }}
+          RESULT_UNIT_TESTS: ${{ needs.unit-tests.result }}
+          RESULT_INTEGRATION: ${{ needs.integration-tests.result }}
+          RESULT_FRONTEND_LINT: ${{ needs.frontend-lint.result }}
+          RESULT_FRONTEND_UNIT: ${{ needs.frontend-unit-test.result }}
+          RESULT_BUILD_PR: ${{ needs.build-pr.result }}
+        run: |
+          set -eu
+          echo "=== CI Gate 评估 ==="
+          echo ""
+          echo "各job结果:"
+          echo "  check-frontend-only: $RESULT_CHECK_FRONTEND"
+          echo "  validate-code-quality: $RESULT_CODE_QUALITY"
+          echo "  validate-type-check: $RESULT_TYPE_CHECK"
+          echo "  validate-migration: $RESULT_MIGRATION"
+          echo "  unit-tests: $RESULT_UNIT_TESTS"
+          echo "  integration-tests: $RESULT_INTEGRATION"
+          echo "  frontend-lint: $RESULT_FRONTEND_LINT"
+          echo "  frontend-unit-test: $RESULT_FRONTEND_UNIT"
+          echo "  build-pr: $RESULT_BUILD_PR"
+
+          # 查询 AI Code Review 状态（跨workflow，读commit status）
+          AI_REVIEW_STATUS="pending"
+          AI_REVIEW_DESC=""
+          STATUS_JSON=$(curl -sH "Authorization: token $GITHUB_TOKEN" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/commits/${PR_HEAD_SHA}/status" 2>/dev/null || true)
+          if [ -n "$STATUS_JSON" ]; then
+            AI_STATUS=$(echo "$STATUS_JSON" | python3 -c "
+          import json,sys
+          try:
+              data=json.load(sys.stdin)
+              for s in data.get('statuses',[]):
+                  if 'AI Code Review' in s.get('context',''):
+                      print(s['state']+'|'+s.get('description',''))
+                      break
+          except: pass
+          " 2>/dev/null)
+            if [ -n "$AI_STATUS" ]; then
+              AI_REVIEW_STATUS="${AI_STATUS%%|*}"
+              AI_REVIEW_DESC="${AI_STATUS#*|}"
+            fi
+          fi
+          echo "  ai-code-review: $AI_REVIEW_STATUS ($AI_REVIEW_DESC)"
+
+          echo ""
+
+          # 判断PR类型
+          SKIP_BACKEND="${{ needs.check-frontend-only.outputs.skip_backend }}"
+          SKIP_FRONTEND="${{ needs.check-frontend-only.outputs.skip_frontend }}"
+          echo "PR类型: skip_backend=$SKIP_BACKEND, skip_frontend=$SKIP_FRONTEND"
+
+          # 必填检查项（根据PR类型决定）
+          # 通用检查（所有PR都必须过）
+          REQUIRED_GENERAL=(
+            "validate-code-quality:$RESULT_CODE_QUALITY"
+            "validate-type-check:$RESULT_TYPE_CHECK"
+            "validate-migration:$RESULT_MIGRATION"
+            "frontend-lint:$RESULT_FRONTEND_LINT"
+            "build-pr:$RESULT_BUILD_PR"
+            "ai-code-review:$AI_REVIEW_STATUS"
+          )
+
+          # 后端检查
+          REQUIRED_BACKEND=(
+            "unit-tests:$RESULT_UNIT_TESTS"
+          )
+
+          # 前端检查
+          REQUIRED_FRONTEND=(
+            "frontend-unit-test:$RESULT_FRONTEND_UNIT"
+          )
+
+          ALL_PASSED=true
+          FAILED_ITEMS=()
+
+          check_job() {
+            local name=$1
+            local result=$2
+            if [ "$result" = "success" ]; then
+              echo "  ✅ $name: success"
+            elif [ "$result" = "skipped" ]; then
+              echo "  ⏭️  $name: skipped（跳过，不影响）"
+            else
+              echo "  ❌ $name: $result"
+              ALL_PASSED=false
+              FAILED_ITEMS+=("$name=$result")
+            fi
+          }
+
+          echo ""
+          echo "=== 通用检查（所有PR必填）==="
+          for item in "${REQUIRED_GENERAL[@]}"; do
+            name="${item%%:*}"
+            result="${item##*:}"
+            # AI Code Review pending时不阻塞（可能还在跑），等它跑完自然会重跑Gate
+            if [ "$name" = "ai-code-review" ] && [ "$result" = "pending" ]; then
+              echo "  ⏳ $name: pending（审查中，暂不阻塞）"
+              continue
+            fi
+            check_job "$name" "$result"
+          done
+
+          if [ "$SKIP_BACKEND" != "true" ]; then
+            echo ""
+            echo "=== 后端检查 ==="
+            for item in "${REQUIRED_BACKEND[@]}"; do
+              name="${item%%:*}"
+              result="${item##*:}"
+              check_job "$name" "$result"
+            done
+          else
+            echo ""
+            echo "=== 后端检查（纯前端PR，跳过）==="
+          fi
+
+          if [ "$SKIP_FRONTEND" != "true" ]; then
+            echo ""
+            echo "=== 前端检查 ==="
+            for item in "${REQUIRED_FRONTEND[@]}"; do
+              name="${item%%:*}"
+              result="${item##*:}"
+              check_job "$name" "$result"
+            done
+          else
+            echo ""
+            echo "=== 前端检查（纯后端PR，跳过）==="
+          fi
+
+          echo ""
+          if [ "$ALL_PASSED" = "true" ]; then
+            echo "✅ CI Gate: PASSED"
+            echo "gate_result=success" >> $GITHUB_OUTPUT
+            exit 0
+          else
+            echo "❌ CI Gate: FAILED"
+            echo "失败项: ${FAILED_ITEMS[*]}"
+            echo "gate_result=failure" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ "${{ steps.gate.outputs.gate_result }}" = "success" ] || STATUS="error"
+          START_TIME=""
+          [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
@@ -16,15 +16,15 @@ permissions:
 jobs:
  monitor:
    name: Monitor CI Trigger Reliability
-    runs-on: ubuntu-latest
+    runs-on: ci-l2
    timeout-minutes: 5
    steps:
      - name: Checkout code
-        uses: actions/checkout@v3
-        # 网络波动自动重试2次
-        retry:
-          max_attempts: 2
-          retry_on: error
+        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: Check CI trigger status for all open PRs
        env:
@@ -15,20 +15,18 @@ concurrency:
 jobs:
  code-review:
    name: AI Code Review
-    runs-on: ubuntu-latest
+    runs-on: ci-l2
    # 跳过草稿 PR
    if: ${{ !gitea.event.pull_request.draft }}

    steps:
      # actions/checkout 由 runner 在宿主机层面处理，不受容器网络影响
      - name: Checkout code
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-        # 网络波动自动重试2次
-        retry:
-          max_attempts: 2
-          retry_on: error
+        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: Install dependencies
        run: |
@@ -50,6 +48,7 @@ jobs:
          GITEA_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
          REPO_NAME: ${{ gitea.repository }}
          PR_NUMBER: ${{ gitea.event.pull_request.number }}
+          PR_HEAD_SHA: ${{ gitea.event.pull_request.head.sha }}
          # LLM 提供商: coze (扣子原生Bot) / openai (OpenAI兼容)
          LLM_PROVIDER: "coze"
          # 扣子模式配置（默认国内站 api.coze.cn）
@@ -62,8 +61,9 @@ jobs:
          LLM_TIMEOUT: "120"
        run: |
          python3 scripts/ci_code_review.py
-        # 审查脚本异常不影响 CI 通过
-        continue-on-error: true
+        # 注意：脚本退出码决定job状态
+        # - 有阻塞级问题 → exit 1 → job失败 → 门禁拦截
+        # - 无阻塞级问题/LLM异常 → exit 0 → 通过（fail-open）

      - name: Report CI trace
        if: always()
@@ -1,4 +1,5 @@
 name: Daily Health Check
+# 注意：使用 curl step_checkout.sh 方式以兼容 docker runner

 on:
  schedule:
@@ -12,7 +13,7 @@ jobs:
  # ── 1. 生产环境冒烟测试 ─────────────────────────────────────────────
  production-smoke:
    name: Production Smoke Test
-    runs-on: saas
+    runs-on: ci-l2
    timeout-minutes: 8
    outputs:
      report: ${{ steps.smoke.outputs.report }}
@@ -23,47 +24,9 @@ jobs:
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
-          set -eu
-          python3 - <<'PY'
-          import io, os, tarfile, time, urllib.request, urllib.error
-          url = f"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz"
-          request = urllib.request.Request(url, headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}"})
-          last_err = None
-          for attempt in range(5):
-              try:
-                  with urllib.request.urlopen(request, timeout=120) as response:
-                      archive = response.read()
-                  break
-              except urllib.error.HTTPError as e:
-                  last_err = e
-                  if e.code >= 500 and attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-              except Exception as e:
-                  last_err = e
-                  if attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-          else:
-              raise last_err
-          with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
-              root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'
-              for member in tar.getmembers():
-                  name = member.name
-                  if name == root_prefix[:-1]:
-                      continue
-                  if name.startswith(root_prefix):
-                      member.name = name[len(root_prefix):]
-                  if member.name:
-                      tar.extract(member, '.')
-          PY
-
+          curl -sH "Authorization: token $GITHUB_TOKEN" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}" \
+            | bash
      - name: Production health check & smoke test
        id: smoke
        shell: sh
@@ -121,10 +84,10 @@ jobs:
  # ── 2. Staging API 集成测试 ─────────────────────────────────────────
  staging-api-tests:
    name: Staging API Integration Tests
-    runs-on: saas
+    runs-on: ci-l2
    timeout-minutes: 10
    outputs:
-      report: ${{ steps.smoke.outputs.report }}
+      report: ${{ steps.report.outputs.report }}

    steps:
      - name: Checkout code
@@ -132,50 +95,15 @@ jobs:
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
-          set -eu
-          python3 - <<'PY'
-          import io, os, tarfile, time, urllib.request, urllib.error
-          url = f"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz"
-          request = urllib.request.Request(url, headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}"})
-          last_err = None
-          for attempt in range(5):
-              try:
-                  with urllib.request.urlopen(request, timeout=120) as response:
-                      archive = response.read()
-                  break
-              except urllib.error.HTTPError as e:
-                  last_err = e
-                  if e.code >= 500 and attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-              except Exception as e:
-                  last_err = e
-                  if attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-          else:
-              raise last_err
-          with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
-              root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'
-              for member in tar.getmembers():
-                  name = member.name
-                  if name == root_prefix[:-1]:
-                      continue
-                  if name.startswith(root_prefix):
-                      member.name = name[len(root_prefix):]
-                  if member.name:
-                      tar.extract(member, '.')
-          PY
-
+          curl -sH "Authorization: token $GITHUB_TOKEN" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}" \
+            | bash
      - name: Run API smoke test on staging
        id: smoke
        shell: sh
+        env:
+          STAGING_TEST_USER: ${{ secrets.STAGING_TEST_USER }}
+          STAGING_TEST_PASSWORD: ${{ secrets.STAGING_TEST_PASSWORD }}
        run: |
          set +e
          START_TIME=$(date +%s)
@@ -183,8 +111,8 @@ jobs:
          docker run --rm \
            -e BASE_URL=https://staging-api.xiaoxiajianji.com \
            -e WEB_URL=https://staging.xiaoxiajianji.com \
-            -e TEST_USER=18314979086@163.com \
-            -e TEST_PASSWORD=Ying1234 \
+            -e TEST_USER="$STAGING_TEST_USER" \
+            -e TEST_PASSWORD="$STAGING_TEST_PASSWORD" \
            -e CLEANUP_ENABLED=1 \
            -e PERF_CHECK_ENABLED=1 \
            -e PERF_WARN_THRESHOLD_MS=500 \
@@ -270,10 +198,10 @@ jobs:
  # ── 3. Staging 浏览器 E2E ──────────────────────────────────────────
  staging-e2e:
    name: Staging Browser E2E
-    runs-on: saas
+    runs-on: ci-l2
    timeout-minutes: 15
    outputs:
-      report: ${{ steps.smoke.outputs.report }}
+      report: ${{ steps.e2e.outputs.report }}

    steps:
      - name: Checkout code
@@ -281,47 +209,9 @@ jobs:
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
-          set -eu
-          python3 - <<'PY'
-          import io, os, tarfile, time, urllib.request, urllib.error
-          url = f"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz"
-          request = urllib.request.Request(url, headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}"})
-          last_err = None
-          for attempt in range(5):
-              try:
-                  with urllib.request.urlopen(request, timeout=120) as response:
-                      archive = response.read()
-                  break
-              except urllib.error.HTTPError as e:
-                  last_err = e
-                  if e.code >= 500 and attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-              except Exception as e:
-                  last_err = e
-                  if attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-          else:
-              raise last_err
-          with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
-              root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'
-              for member in tar.getmembers():
-                  name = member.name
-                  if name == root_prefix[:-1]:
-                      continue
-                  if name.startswith(root_prefix):
-                      member.name = name[len(root_prefix):]
-                  if member.name:
-                      tar.extract(member, '.')
-          PY
-
+          curl -sH "Authorization: token $GITHUB_TOKEN" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}" \
+            | bash
      - name: Run Playwright E2E on staging
        id: e2e
        shell: sh
@@ -371,7 +261,7 @@ jobs:
  # ── 4. 性能基线巡检 ────────────────────────────────────────────────
  performance-check:
    name: Performance Baseline Check
-    runs-on: saas
+    runs-on: ci-l2
    timeout-minutes: 8
    outputs:
      report: ${{ steps.report.outputs.report }}
@@ -380,6 +270,9 @@ jobs:
      - name: Run performance baseline checks
        id: perf
        shell: sh
+        env:
+          STAGING_TEST_USER: ${{ secrets.STAGING_TEST_USER }}
+          STAGING_TEST_PASSWORD: ${{ secrets.STAGING_TEST_PASSWORD }}
        run: |
          set +e
          START_TIME=$(date +%s)
@@ -415,9 +308,10 @@ jobs:

          # 先登录获取 token
          echo "--- 准备: 获取测试 Token ---"
+          LOGIN_BODY="{\"email\":\"$STAGING_TEST_USER\",\"password\":\"$STAGING_TEST_PASSWORD\"}"
          AUTH_RESP=$(curl -s -w "\n%{http_code}" -X POST \
            -H "Content-Type: application/json" \
-            -d '{"email":"18314979086@163.com","password":"Ying1234"}' \
+            -d "$LOGIN_BODY" \
            "https://staging-api.xiaoxiajianji.com/api/v1/auth/login" \
            --max-time 10 2>&1)
          AUTH_CODE=$(echo "$AUTH_RESP" | tail -1)
@@ -447,7 +341,7 @@ jobs:
            # 构建 curl 命令
            CURL_ARGS="-s -o /dev/null -w '%{http_code} %{time_total}' --max-time 30"
            if [ "$method" = "POST" ]; then
-              CURL_ARGS="$CURL_ARGS -X POST -H 'Content-Type: application/json' -d '{\"email\":\"18314979086@163.com\",\"password\":\"Ying1234\"}'"
+              CURL_ARGS="$CURL_ARGS -X POST -H 'Content-Type: application/json' -d \"$LOGIN_BODY\""
            fi
            if [ -n "$TOKEN" ] && [ "$name" != "健康检查" ]; then
              CURL_ARGS="$CURL_ARGS -H 'Authorization: Bearer $TOKEN'"
@@ -495,6 +389,9 @@ jobs:
      - name: Generate performance report
        id: report
        shell: sh
+        env:
+          STAGING_TEST_USER: ${{ secrets.STAGING_TEST_USER }}
+          STAGING_TEST_PASSWORD: ${{ secrets.STAGING_TEST_PASSWORD }}
        run: |
          set +e
          echo ""
@@ -509,10 +406,11 @@ jobs:
          RESULTS=""
          START_TIME=$(date +%s)

+          LOGIN_BODY="{\"email\":\"$STAGING_TEST_USER\",\"password\":\"$STAGING_TEST_PASSWORD\"}"
          # 先登录获取 token
          AUTH_RESP=$(curl -s -w "\n%{http_code}" -X POST \
            -H "Content-Type: application/json" \
-            -d '{"email":"18314979086@163.com","password":"Ying1234"}' \
+            -d "$LOGIN_BODY" \
            "https://staging-api.xiaoxiajianji.com/api/v1/auth/login" \
            --max-time 10 2>&1)
          AUTH_CODE=$(echo "$AUTH_RESP" | tail -1)
@@ -528,7 +426,7 @@ jobs:

            local CURL_ARGS="-s -o /dev/null -w '%{http_code} %{time_total}' --max-time 30"
            if [ "$method" = "POST" ]; then
-              CURL_ARGS="$CURL_ARGS -X POST -H 'Content-Type: application/json' -d '{\"email\":\"18314979086@163.com\",\"password\":\"Ying1234\"}'"
+              CURL_ARGS="$CURL_ARGS -X POST -H 'Content-Type: application/json' -d \"$LOGIN_BODY\""
            fi
            if [ -n "$TOKEN" ] && [ "$name" != "健康检查" ]; then
              CURL_ARGS="$CURL_ARGS -H 'Authorization: Bearer $TOKEN'"
@@ -631,7 +529,7 @@ jobs:
  # ── 5. 每日巡检汇总报告 ────────────────────────────────────────────
  daily-report:
    name: Daily Check Report
-    runs-on: saas
+    runs-on: ci-l2
    timeout-minutes: 2
    if: always()
    needs:
@@ -0,0 +1,56 @@
+name: PR Auto Scan
+# 定时扫描所有open PR，对CI全绿的触发审批/合并
+# 作为短作业模式的兜底，防止事件驱动遗漏
+on:
+  schedule:
+    - cron: "*/5 * * * *"  # 每5分钟扫描一次
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  auto-scan:
+    name: Auto Scan Open PRs
+    runs-on: ci-check
+    timeout-minutes: 5
+    if: github.repository == 'xiaoxia/xiaoxia-saas'
+    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/pr_auto_scan.py?ref=develop"             -o /tmp/pr_auto_scan.py
+          python3 /tmp/pr_auto_scan.py --help > /dev/null 2>&1 || {
+            # fallback: checkout
+            echo "使用checkout方式"
+            curl -sH "Authorization: token $GITHUB_TOKEN"               "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=develop"               | bash
+          }
+
+      - name: Scan and auto process PRs
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          REVIEW_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+          MERGE_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+        run: |
+          set -eu
+          echo "=== 扫描所有open PR并自动处理 ==="
+          echo "时间: $(date)"
+          echo
+
+          python3 /tmp/pr_auto_scan.py             --token "$REVIEW_TOKEN"             --repo "$GITHUB_REPOSITORY"             --base develop             --approve             --merge             --dry-run false
+
+          echo ""
+          echo "✅ 扫描完成"
+
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ ${{ job.status }} = "success" ] || STATUS="error"
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "" || true
@@ -3,16 +3,22 @@ name: PR Automation
 on:
  pull_request:
    types: [synchronize, opened, ready_for_review, review_requested]
+  workflow_dispatch:

 permissions:
  contents: read

+
+concurrency:
+  group: pr-automation-${{ gitea.event.pull_request.number }}
+  cancel-in-progress: true
+
 jobs:
  auto-approve:
    name: Auto Approve on CI Green
    runs-on: ci-check
    if: github.event_name == 'pull_request' && !github.event.pull_request.draft
-    timeout-minutes: 20
+    timeout-minutes: 3  # 长等待模式：等CI全绿后自动合并，不遗漏任何PR
    steps:
      - name: Checkout code
        shell: sh
@@ -21,6 +27,15 @@ jobs:
        run: |
          curl -sH "Authorization: token $GITHUB_TOKEN"             "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}"             | bash

+      - name: "🔍 脚本语法自检"
+        shell: bash
+        run: |
+          ERROR=0
+          for f in scripts/ci/*.sh; do [ -f "$f" ] && bash -n "$f" 2>&1 || ERROR=$((ERROR+1)); done
+          for f in scripts/ci/*.py; do [ -f "$f" ] && python3 -m py_compile "$f" 2>&1 || ERROR=$((ERROR+1)); done
+          if [ "$ERROR" -ne 0 ]; then echo "❌ 语法自检失败 ($ERROR个)"; exit 1; fi
+          echo "✅ 脚本语法自检通过"
+
      - name: Auto approve when CI passes
        shell: bash
        env:
@@ -29,151 +44,7 @@ jobs:
          PR_NUMBER: ${{ github.event.pull_request.number }}
          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
-          set -eu
-
-          echo "PR #${PR_NUMBER} - 检查CI状态并自动审批"
-
-          # 检查是否纯前端改动
-          API_URL="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?limit=300"
-          FILES=$(curl -s -H "Authorization: token ${GITHUB_TOKEN}" "$API_URL" | python3 -c "import sys,json; [print(f['filename']) for f in json.load(sys.stdin)]")
-          FRONTEND_COUNT=$(echo "$FILES" | grep -c '^apps/web/' || true)
-          BACKEND_COUNT=$(echo "$FILES" | grep -cv '^apps/web/' || true)
-          TOTAL=$(echo "$FILES" | grep -cv '^$' || true)
-          echo "变更文件: ${TOTAL} 个 (前端: ${FRONTEND_COUNT}, 后端/公共: ${BACKEND_COUNT})"
-
-          if [ "$BACKEND_COUNT" = "0" ] && [ "$FRONTEND_COUNT" -gt "0" ]; then
-            SKIP_BACKEND=true
-            echo "✅ 纯前端改动，只检查Frontend Lint"
-          else
-            SKIP_BACKEND=false
-            echo "🔧 包含后端/公共变更，检查全部CI"
-          fi
-
-          # 定义需要检查的context
-          if [ "$SKIP_BACKEND" = "true" ]; then
-            CONTEXTS=("CI/CD Pipeline / Frontend Lint (pull_request)")
-          else
-            CONTEXTS=(
-              "CI/CD Pipeline / Validate Code Quality And Tests (pull_request)"
-              "CI/CD Pipeline / Frontend Lint (pull_request)"
-            )
-          fi
-
-          echo "需要通过的CI检查: ${#CONTEXTS[@]} 项（与分支保护required门禁一致）"
-          for ctx in "${CONTEXTS[@]}"; do
-            echo "  - $ctx"
-          done
-          echo
-
-          # 初始等待30秒，给CI启动写status的时间
-          echo "等待30秒让CI启动..."
-          sleep 30
-
-          # 轮询等待，最多20分钟（120次x10秒）
-          for attempt in $(seq 1 120); do
-            ALL_SUCCESS=true
-            ANY_FAILED=false
-            ANY_PENDING=false
-
-            echo "--- 第${attempt}次检查 ($(date '+%H:%M:%S')) ---"
-
-            # 调用辅助脚本检查每个context状态
-            for ctx in "${CONTEXTS[@]}"; do
-              STATE=$(python3 scripts/check_ci_status.py "$GITHUB_TOKEN" "$GITHUB_REPOSITORY" "$PR_HEAD_SHA" "$ctx")
-              echo "  $ctx: $STATE"
-
-              if [ "$STATE" != "success" ]; then
-                ALL_SUCCESS=false
-              fi
-              if [ "$STATE" = "failure" ] || [ "$STATE" = "error" ]; then
-                ANY_FAILED=true
-              fi
-              if [ "$STATE" = "pending" ] || [ "$STATE" = "null" ]; then
-                ANY_PENDING=true
-              fi
-            done
-
-            if [ "$ALL_SUCCESS" = "true" ]; then
-              echo
-              echo "✅ 所有CI检查通过，自动审批 PR #${PR_NUMBER}"
-
-              # 检查是否已有审批
-              EXISTING=$(curl -s -H "Authorization: token ${REVIEW_TOKEN}" \
-                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews" \
-                | python3 -c "import sys,json; reviews=json.load(sys.stdin); print('yes' if any(r.get('state')=='APPROVED' for r in reviews) else 'no')")
-
-              if [ "$EXISTING" = "yes" ]; then
-                echo "ℹ️  PR #${PR_NUMBER} 已有审批，跳过"
-                exit 0
-              fi
-
-              # 第一步：创建PENDING review
-              echo "创建review..."
-              REVIEW_CREATE=$(curl -s -X POST \
-                -H "Authorization: token ${REVIEW_TOKEN}" \
-                -H "Content-Type: application/json" \
-                -d '{"event": "PENDING", "body": "CI全绿，自动审批通过。"}' \
-                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews")
-              
-              REVIEW_ID=$(echo "$REVIEW_CREATE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))")
-              REVIEW_STATE=$(echo "$REVIEW_CREATE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('state',''))")
-              echo "创建结果: id=$REVIEW_ID state=$REVIEW_STATE"
-
-              if [ -z "$REVIEW_ID" ]; then
-                echo "❌ 创建review失败"
-                echo "$REVIEW_CREATE"
-                exit 1
-              fi
-
-              if [ "$REVIEW_STATE" = "APPROVED" ]; then
-                echo "✅ 自动审批成功（直接创建为APPROVED）"
-                exit 0
-              fi
-
-              # 第二步：submit review为APPROVED
-              echo "提交review审批..."
-              SUBMIT_CODE=$(curl -s -o /tmp/submit_resp.json -w "%{http_code}" \
-                -X POST \
-                -H "Authorization: token ${REVIEW_TOKEN}" \
-                -H "Content-Type: application/json" \
-                -d '{"event": "APPROVED", "body": "CI全绿，自动审批通过。"}' \
-                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews/${REVIEW_ID}")
-              
-              echo "提交API HTTP状态: $SUBMIT_CODE"
-              cat /tmp/submit_resp.json 2>/dev/null || true
-              echo
-
-              if [ "$SUBMIT_CODE" = "200" ] || [ "$SUBMIT_CODE" = "201" ]; then
-                FINAL_STATE=$(python3 -c "import json; print(json.load(open('/tmp/submit_resp.json')).get('state',''))" 2>/dev/null || echo "?")
-                echo "✅ 自动审批成功 (state: $FINAL_STATE)"
-                exit 0
-              else
-                echo "❌ 提交审批失败"
-                exit 1
-              fi
-            fi
-
-            # 还有CI在跑 → 继续等
-            if [ "$ANY_PENDING" = "true" ]; then
-              echo "⏳ CI仍在运行中，继续等待（第${attempt}/120次轮询）..."
-              sleep 10
-              continue
-            fi
-
-            # 所有CI都跑完了但有失败 → 退出
-            if [ "$ANY_FAILED" = "true" ]; then
-              echo
-              echo "❌ CI检查有失败项，不自动审批"
-              exit 0
-            fi
-
-            sleep 10
-          done
-
-          echo
-          echo "⏰ 等待超时（20分钟），CI尚未全部完成"
-          exit 0
-
+          bash scripts/ci/auto_approve.sh
      - name: Report CI trace
        if: always()
        shell: sh
@@ -190,7 +61,7 @@ jobs:
    name: Auto Merge on CI Green + Approved
    runs-on: ci-check
    if: github.event_name == 'pull_request' && !github.event.pull_request.draft && github.event.pull_request.base.ref == 'develop'
-    timeout-minutes: 30
+    timeout-minutes: 3  # 短作业模式：检查一次，不满足就退出，由pr-auto-scan每5分钟定时兜底
    steps:
      - name: Checkout code
        shell: sh
@@ -199,6 +70,31 @@ jobs:
        run: |
          curl -sH "Authorization: token $GITHUB_TOKEN"             "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}"             | bash

+      - name: "🔍 脚本语法自检（防止脚本bug导致所有PR挂掉）"
+        shell: bash
+        run: |
+          echo "=== CI脚本语法自检 ==="
+          ERROR=0
+          for f in scripts/ci/*.sh; do
+            [ -f "$f" ] || continue
+            if ! bash -n "$f" 2>&1; then
+              echo "FAIL: $f"
+              ERROR=1
+            fi
+          done
+          for f in scripts/ci/*.py; do
+            [ -f "$f" ] || continue
+            if ! python3 -m py_compile "$f" 2>&1; then
+              echo "FAIL: $f"
+              ERROR=1
+            fi
+          done
+          if [ "$ERROR" -ne 0 ]; then
+            echo "❌ 脚本语法自检失败"
+            exit 1
+          fi
+          echo "✅ 所有CI脚本语法自检通过"
+
      - name: Auto merge when CI passes and approved
        shell: bash
        env:
@@ -208,153 +104,7 @@ jobs:
          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          BASE_REF: ${{ github.event.pull_request.base.ref }}
        run: |
-          set -eu
-
-          echo "PR #${PR_NUMBER} - 检查CI状态+审批并自动合并到${BASE_REF}"
-          echo
-
-          # 只合develop分支
-          if [ "$BASE_REF" != "develop" ]; then
-            echo "Skip: 目标分支不是develop"
-            exit 0
-          fi
-
-          # 判断是否纯前端改动
-          FILES=$(curl -s -H "Authorization: token ${GITHUB_TOKEN}" \
-            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?limit=300" \
-            | python3 -c "import sys,json; [print(f['filename']) for f in json.load(sys.stdin)]")
-          TOTAL=$(echo "$FILES" | grep -cv '^$' || true)
-          FRONTEND_COUNT=$(echo "$FILES" | grep -c '^apps/web/' || true)
-          BACKEND_COUNT=$((TOTAL - FRONTEND_COUNT))
-          echo "变更文件: ${TOTAL} 个 (前端: ${FRONTEND_COUNT}, 后端/公共: ${BACKEND_COUNT})"
-
-          if [ "$BACKEND_COUNT" = "0" ] && [ "$FRONTEND_COUNT" -gt "0" ]; then
-            CONTEXTS=("CI/CD Pipeline / Frontend Lint (pull_request)")
-            echo "纯前端改动，只检查Frontend Lint"
-          else
-            CONTEXTS=(
-              "CI/CD Pipeline / Validate Code Quality And Tests (pull_request)"
-              "CI/CD Pipeline / Frontend Lint (pull_request)"
-              "CI/CD Pipeline / PR Build API Image (pull_request)"
-              "CI/CD Pipeline / PR Build Worker Image (pull_request)"
-              "CI/CD Pipeline / PR Build Web Image (pull_request)"
-            )
-            echo "检查required门禁（与分支保护一致）"
-          fi
-          echo
-
-          # 初始等待30秒，给CI启动写status的时间
-          echo "等待30秒让CI启动..."
-          sleep 30
-
-          # 405连续计数器
-          MERGE_405_COUNT=0
-          MAX_405_RETRIES=10
-
-          # 轮询等待，最多30分钟（180次x10秒）
-          for attempt in $(seq 1 180); do
-            ALL_SUCCESS=true
-            ANY_FAILED=false
-            ANY_PENDING=false
-
-            echo "--- 第${attempt}次检查 ($(date '+%H:%M:%S')) ---"
-
-            # 检查CI状态
-            for ctx in "${CONTEXTS[@]}"; do
-              STATE=$(python3 scripts/check_ci_status.py "$GITHUB_TOKEN" "$GITHUB_REPOSITORY" "$PR_HEAD_SHA" "$ctx")
-              echo "  CI: ${ctx##*/}: $STATE"
-              if [ "$STATE" != "success" ]; then
-                ALL_SUCCESS=false
-              fi
-              if [ "$STATE" = "failure" ] || [ "$STATE" = "error" ]; then
-                ANY_FAILED=true
-              fi
-              if [ "$STATE" = "pending" ]; then
-                ANY_PENDING=true
-              fi
-            done
-
-            # 检查审批状态
-            APPROVAL_RESULT=$(python3 scripts/check_pr_approval.py "$MERGE_TOKEN" "$GITHUB_REPOSITORY" "$PR_NUMBER" 1)
-            echo "  审批: $APPROVAL_RESULT"
-            HAS_APPROVAL=false
-            if echo "$APPROVAL_RESULT" | grep -q '^approved'; then
-              HAS_APPROVAL=true
-            fi
-
-            # 全部满足 → 合并
-            if [ "$ALL_SUCCESS" = "true" ] && [ "$HAS_APPROVAL" = "true" ]; then
-              echo
-              echo "CI全绿 + 审批通过，执行自动合并"
-              echo "等待60秒冷却，给Gitea内部状态同步时间..."
-              sleep 60
-
-              # 幂等检查：PR是否还是open
-              PR_STATE=$(curl -s -H "Authorization: token ${MERGE_TOKEN}" \
-                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" \
-                | python3 -c "import sys,json; print(json.load(sys.stdin).get('state',''))")
-
-              if [ "$PR_STATE" != "open" ]; then
-                echo "PR状态为 ${PR_STATE}，无需合并"
-                exit 0
-              fi
-
-              # 执行squash merge
-              HTTP_CODE=$(curl -s -o /tmp/merge_resp.json -w "%{http_code}" \
-                -X POST \
-                -H "Authorization: token ${MERGE_TOKEN}" \
-                -H "Content-Type: application/json" \
-                -d '{"do":"squash","merge_title_field":"","merge_message_field":"","delete_branch_after_merge":true,"force_merge":false}' \
-                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/merge")
-
-              echo "合并API HTTP状态: $HTTP_CODE"
-
-              if [ "$HTTP_CODE" = "200" ]; then
-                echo "自动合并成功"
-                exit 0
-              elif [ "$HTTP_CODE" = "405" ]; then
-                MERGE_405_COUNT=$((MERGE_405_COUNT + 1))
-                echo "⚠️  合并返回405（第${MERGE_405_COUNT}次），可能CI状态尚未同步或有未解决的门禁，继续等待重试..."
-                cat /tmp/merge_resp.json 2>/dev/null || true
-                echo
-                if [ "$MERGE_405_COUNT" -ge "$MAX_405_RETRIES" ]; then
-                  echo "⚠️  连续${MAX_405_RETRIES}次合并返回405，放弃自动合并（需人工确认，非代码问题）"
-                  curl -s -X POST \
-                    -H "Authorization: token ${MERGE_TOKEN}" \
-                    -H "Content-Type: application/json" \
-                    -d '{"body": "Auto merge skipped after multiple 405 errors: PR may have conflicts or unresolved checks. Please review manually. This is not a CI failure."}' \
-                    "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null 2>&1 || true
-                  exit 0
-                fi
-                sleep 30
-                continue
-              else
-                echo "自动合并失败 (HTTP $HTTP_CODE)"
-                cat /tmp/merge_resp.json 2>/dev/null || true
-                curl -s -X POST \
-                  -H "Authorization: token ${MERGE_TOKEN}" \
-                  -H "Content-Type: application/json" \
-                  -d "{\"body\": \"Auto merge failed (HTTP ${HTTP_CODE}), please check manually.\"}" \
-                  "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null 2>&1 || true
-                exit 1
-              fi
-            else
-              # 本轮不满足合并条件，重置405计数器
-              MERGE_405_COUNT=0
-            fi
-
-            if [ "$ANY_FAILED" = "true" ]; then
-              echo
-              echo "CI有失败项，不自动合并"
-              exit 0
-            fi
-
-            sleep 10
-          done
-
-          echo
-          echo "等待超时（30分钟）"
-          exit 0
+          bash scripts/ci/auto_merge.sh
      - name: Report CI trace
        if: always()
        shell: sh
@@ -120,7 +120,7 @@ jobs:
        PREVIEW_SSH_KEY: ${{ secrets.PREVIEW_SSH_KEY }}
      run: |
        set -eux
-        preview_host="${PREVIEW_SSH_HOST:-172.30.18.197}"
+        preview_host="${PREVIEW_SSH_HOST:-47.98.113.167}"
        preview_user="${PREVIEW_SSH_USER:-deploy}"
        preview_port="${PREVIEW_SSH_PORT:-22222}"
        preview_dir="/var/www/preview/pr-${PR_NUMBER}"
@@ -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 install 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,103 @@
+name: Worker Base Image Build
+
+on:
+  push:
+    branches:
+      - develop
+      - main
+    paths:
+      - 'requirements-base.txt'
+      - 'requirements-worker.txt'
+      - 'infra/docker/worker-base-builder.Dockerfile'
+      - 'infra/docker/worker-base-runtime.Dockerfile'
+  workflow_dispatch:  # 支持手动触发
+
+jobs:
+  build-worker-base:
+    name: Build Worker Base Images
+    runs-on: runtime-builder
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - name: builder
+          dockerfile: infra/docker/worker-base-builder.Dockerfile
+          image_name: worker-base-builder
+          cache_name: worker-base-builder-cache
+        - name: runtime
+          dockerfile: infra/docker/worker-base-runtime.Dockerfile
+          image_name: worker-base-runtime
+          cache_name: worker-base-runtime-cache
+    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: Docker login to Registry
+      shell: sh
+      env:
+        ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+        ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+        GITEA_REGISTRY_USER: xiaoxia
+        GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+      run: |
+        set -eu
+        for i in 1 2 3; do
+          echo "=== Docker login 尝试 $i/3 ==="
+          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
+            echo "✅ Docker login successful"
+            break
+          fi
+          echo "❌ Docker login 失败（尝试 $i/3），5s 后重试..."
+          sleep 5
+        done
+
+    - name: Setup buildx builder
+      shell: sh
+      run: |
+        set -eu
+        BUILDER_NAME="ci-builder-${GITHUB_RUN_ID}-${{ matrix.name }}"
+        if ! docker buildx inspect "$BUILDER_NAME" > /dev/null 2>&1; then
+          docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
+          echo "Created $BUILDER_NAME"
+        else
+          docker buildx use "$BUILDER_NAME"
+          echo "Using existing $BUILDER_NAME"
+        fi
+        docker buildx inspect --bootstrap
+
+    - name: Build and push base image
+      shell: sh
+      run: |
+        set -eu
+        REGISTRY="xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji"
+        IMAGE_TAG="${REGISTRY}/${{ matrix.image_name }}:latest"
+        SAFE_REF_NAME=$(echo "${GITHUB_REF_NAME}" | tr '/' '-')
+        CACHE_REF="${REGISTRY}/${{ matrix.cache_name }}:${SAFE_REF_NAME}"
+        
+        echo "=== Building ${{ matrix.name }} base image ==="
+        echo "Image: ${IMAGE_TAG}"
+        echo "Cache: ${CACHE_REF}"
+        
+        # 用通用构建脚本
+        bash scripts/ci/docker_build_push.sh           ${{ matrix.dockerfile }}           "${IMAGE_TAG}"           "${CACHE_REF}"
+        
+        # 同时推送到 Gitea Packages 作为备份（可选）
+        GITEA_IMAGE="git.xiaoxiajianji.com/xiaoxia-saas/${{ matrix.image_name }}:latest"
+        docker tag "${IMAGE_TAG}" "${GITEA_IMAGE}"
+        docker push "${GITEA_IMAGE}" || echo "Gitea Packages push failed (non-fatal)"
+        
+        echo ""
+        echo "✅ ${{ matrix.name }} base image built and pushed"
+
+    - name: Cleanup buildx builder
+      if: always()
+      shell: sh
+      run: |
+        docker buildx rm "ci-builder-${GITHUB_RUN_ID}-${{ matrix.name }}" 2>/dev/null || true
+        docker buildx prune -f 2>/dev/null || true
+        echo "Builder cleanup done"
@@ -1,4 +1,3 @@
-import os
 from logging.config import fileConfig

 from sqlalchemy import engine_from_config, pool
@@ -8,13 +7,17 @@ from alembic import context
 # Import your models' Base here
 from packages.adapters.sqlalchemy_impl.models import Base

+# 使用统一配置入口获取 database_url，而非直接读环境变量
+from packages.config import get_shared_settings
+
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
 config = context.config

-database_url = os.getenv("DATABASE_URL")
-if database_url:
-    config.set_main_option("sqlalchemy.url", database_url)
+# 从统一配置系统获取 database_url，确保与应用使用同一配置源
+settings = get_shared_settings()
+if settings.database_url:
+    config.set_main_option("sqlalchemy.url", settings.database_url)

 # Interpret the config file for Python logging.
 # This line sets up loggers basically.
@@ -0,0 +1,48 @@
+"""#P3-2 - 视频分享表 video_shares
+
+Revision ID: 050
+Revises: 049
+Create Date: 2026-07-22
+
+Changes:
+1. 新建 video_shares 表，支持视频匿名分享链接
+2. share_token 唯一索引，用于公开分享URL
+3. 支持密码保护、有效期、浏览/下载计数
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "050_video_shares"
+down_revision = "049_wechat_login_phone"
+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 to_regclass('public.video_shares')"))
+        if result.scalar() is not None:
+            return
+
+    op.create_table(
+        "video_shares",
+        sa.Column("id", sa.String(32), primary_key=True),
+        sa.Column("video_id", sa.String(32), nullable=False, index=True),
+        sa.Column("user_id", sa.String(32), nullable=False, index=True),
+        sa.Column("share_token", sa.String(16), nullable=False, unique=True),
+        sa.Column("password_hash", sa.String(255), nullable=True),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("view_count", sa.Integer, nullable=False, server_default="0"),
+        sa.Column("download_count", sa.Integer, nullable=False, server_default="0"),
+        sa.Column("is_active", sa.Boolean, nullable=False, server_default=sa.true()),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("video_shares")
@@ -0,0 +1,53 @@
+"""#632 - 一键生成输出分辨率可配置
+
+Revision ID: 051
+Revises: 050
+Create Date: 2026-07-23
+
+Changes:
+1. generation_tasks 表新增 resolution 字段，存储用户指定的输出分辨率（如 "1280x720"）
+2. 为空时使用默认值（1280x720）
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "051_generation_task_resolution"
+down_revision = "050_video_shares"
+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 = 'resolution'"
+            )
+        )
+        if result.scalar() is not None:
+            return
+
+    op.add_column(
+        "generation_tasks",
+        sa.Column("resolution", sa.String(20), nullable=False, server_default=""),
+    )
+
+
+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 = 'resolution'"
+            )
+        )
+        if result.scalar() is None:
+            return
+
+    op.drop_column("generation_tasks", "resolution")
@@ -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,3 +1,4 @@
+from app.api.routes.ai import router as ai_router
 from app.api.routes.asset_diagnosis import router as asset_diagnosis_router
 from app.api.routes.asset_libraries import router as asset_libraries_router
 from app.api.routes.assets import router as assets_router
@@ -11,6 +12,7 @@ from app.api.routes.health import router as health_check_router
 from app.api.routes.ingest_jobs import router as ingest_jobs_router
 from app.api.routes.internal_render import router as internal_render_router
 from app.api.routes.projects import router as projects_router
+from app.api.routes.share import router as share_router
 from app.api.routes.subscription import router as subscription_router
 from app.api.routes.tags import router as tags_router
 from app.api.routes.task_center import router as task_center_router
@@ -104,6 +106,10 @@ api_router.include_router(
    videos_router,
    tags=["VideoCenter"],
 )
+api_router.include_router(
+    share_router,
+    tags=["Share"],
+)
 api_router.include_router(
    duplication_router,
    prefix="/duplication",
@@ -129,6 +135,11 @@ api_router.include_router(
    prefix="/tts",
    tags=["TTS"],
 )
+api_router.include_router(
+    ai_router,
+    prefix="/ai",
+    tags=["AI"],
+)
 api_router.include_router(
    feature_flags_router,
    tags=["Internal"],
@@ -0,0 +1,136 @@
+"""AI 相关接口 — 智能标题、智能素材匹配等.
+
+基于豆包大模型的 AI 能力接口，未配置 API Key 时自动降级为本地模拟。
+"""
+
+from __future__ import annotations
+
+from typing import List, Literal
+
+from app.services.ai_service import TITLE_STYLES, generate_smart_titles, semantic_match_assets
+from fastapi import APIRouter
+from pydantic import BaseModel, Field
+
+router = APIRouter()
+
+
+# ── 请求/响应模型 ────────────────────────────────────────────────────────────
+
+
+class GenerateTitlesRequest(BaseModel):
+    """智能标题生成请求."""
+
+    description: str = Field(..., min_length=1, max_length=500, description="视频内容描述")
+    style: Literal["viral", "emotional", "informative"] = Field(
+        default="viral",
+        description="标题风格：viral爆款 / emotional情感 / informative信息",
+    )
+    count: int = Field(default=5, ge=3, le=10, description="生成数量，3-10个")
+
+
+class GenerateTitlesResponse(BaseModel):
+    """智能标题生成响应."""
+
+    titles: List[str] = Field(..., description="生成的标题列表")
+    style: str = Field(..., description="实际使用的风格")
+    source: str = Field(..., description="来源：doubao 或 fallback")
+    description: str = Field(..., description="原始描述")
+
+
+class TitleStyleInfo(BaseModel):
+    """标题风格信息."""
+
+    key: str
+    name: str
+    description: str
+
+
+# ── 素材语义匹配 ────────────────────────────────────────────────────────────
+
+
+class AssetMatchItem(BaseModel):
+    """待匹配素材项."""
+
+    id: str = Field(..., description="素材ID")
+    name: str = Field(default="", description="素材名称")
+    tags: List[str] = Field(default_factory=list, description="标签列表")
+    description: str = Field(default="", description="素材描述")
+
+
+class SemanticMatchRequest(BaseModel):
+    """语义匹配请求."""
+
+    description: str = Field(..., min_length=1, max_length=500, description="目标视频内容描述")
+    assets: List[AssetMatchItem] = Field(..., min_length=1, max_length=100, description="待匹配素材列表")
+    top_k: int = Field(default=0, ge=0, le=100, description="返回前K个，0返回全部")
+
+
+class SemanticMatchResultItem(AssetMatchItem):
+    """匹配结果项."""
+
+    match_score: float = Field(..., description="匹配度评分 0-1")
+    match_reason: str = Field(..., description="匹配方式：doubao_semantic / fallback_keyword / fallback_default")
+
+
+class SemanticMatchResponse(BaseModel):
+    """语义匹配响应."""
+
+    matches: List[SemanticMatchResultItem] = Field(..., description="按匹配度降序排列的素材列表")
+    source: str = Field(..., description="来源：doubao / fallback")
+    description: str = Field(..., description="原始描述")
+    total: int = Field(..., description="输入素材总数")
+
+
+# ── 路由 ────────────────────────────────────────────────────────────────────
+
+
+@router.post("/titles/generate", response_model=GenerateTitlesResponse)
+def generate_titles(request: GenerateTitlesRequest):
+    """生成智能标题.
+
+    根据视频描述生成指定风格的标题，支持爆款、情感、信息三种风格。
+    未配置豆包 API Key 时自动降级为本地规则生成。
+    """
+    result = generate_smart_titles(
+        description=request.description,
+        style=request.style,
+        count=request.count,
+    )
+    return GenerateTitlesResponse(**result)
+
+
+@router.get("/titles/styles", response_model=List[TitleStyleInfo])
+def list_title_styles():
+    """获取支持的标题风格列表."""
+    return [
+        TitleStyleInfo(key=key, name=info["name"], description=info["description"])
+        for key, info in TITLE_STYLES.items()
+    ]
+
+
+@router.post("/assets/match", response_model=SemanticMatchResponse)
+def match_assets(request: SemanticMatchRequest):
+    """智能素材语义匹配.
+
+    根据用户描述，对素材列表做语义匹配并按匹配度排序。
+    未配置豆包 API Key 时自动降级为关键词匹配。
+
+    - 支持最多 100 个素材同时匹配
+    - 返回 match_score (0-1)，按降序排列
+    - top_k 可限制返回数量
+    """
+    # 转为 dict 传给服务层
+    assets_dict = [asset.model_dump() for asset in request.assets]
+
+    result = semantic_match_assets(
+        description=request.description,
+        assets=assets_dict,
+        top_k=request.top_k,
+    )
+
+    return SemanticMatchResponse(
+        matches=[SemanticMatchResultItem(**m) for m in result["matches"]],
+        source=result["source"],
+        description=result["description"],
+        total=result["total"],
+    )
@@ -59,6 +59,8 @@ def _to_generation_task_response(task) -> GenerationTaskResponse:
        asset_select_mode=getattr(task, "asset_select_mode", ""),
        batch_id=getattr(task, "batch_id", ""),
        video_title=getattr(task, "video_title", ""),
+        resolution=getattr(task, "resolution", ""),
+        bgm_config=getattr(task, "bgm_config", {}) or {},
        logs=getattr(task, "logs", "[]"),
        status=task.status,
        progress=task.progress,
@@ -104,7 +106,7 @@ def _select_assets_from_library(

    Args:
        assets: 素材库中所有素材（Asset 实体列表）
-        mode: 选取模式 — all=全部, random=随机, smart=按质量评分
+        mode: 选取模式 — all=全部, random=随机, smart=智能匹配（多维度评分+多样性）
        count: 选取数量，0 表示全部（仅 random/smart 模式有效）

    Returns:
@@ -122,17 +124,19 @@ def _select_assets_from_library(
        return [a.id for a in selected]

    if mode == "smart":
-        # 按质量分降序排列（质量分高的优先），质量分相同时按时长降序
-        sorted_assets = sorted(
+        # 智能匹配：按质量分降序 + 时长降序作为tiebreaker
+        # 注意：这里使用简单的 quality_score 排序保持向后兼容
+        # 更复杂的4维评分+多样性策略由 SmartAssetSelector 服务提供（用于 AI 精选等场景）
+        scored_assets = sorted(
            ready_video_assets,
            key=lambda a: (
-                a.quality_score if a.quality_score is not None else 0.0,
-                a.duration if a.duration is not None else 0.0,
+                -(a.quality_score if a.quality_score is not None else 0.0),
+                -(getattr(a, "duration", 0.0) or 0.0),
            ),
-            reverse=True,
        )
-        selected = sorted_assets if count <= 0 else sorted_assets[:count]
-        return [a.id for a in selected]
+        if count > 0:
+            scored_assets = scored_assets[:count]
+        return [a.id for a in scored_assets]

    # 默认 all 模式：返回全部 ready 视频素材
    return [a.id for a in ready_video_assets]
@@ -223,6 +227,20 @@ def create_generation_task(
                mode=request.asset_select_mode,
                count=request.asset_select_count,
            )
+    elif project_id and not resolved_asset_ids and request.asset_select_mode in ("random", "smart"):
+        # 项目级模式：未指定 asset_ids 且选择了 random/smart 模式时，也自动选取
+        assets = asset_repository.find_by_project(project_id)
+        if assets:
+            resolved_asset_ids = _select_assets_from_library(
+                assets,
+                mode=request.asset_select_mode,
+                count=request.asset_select_count,
+            )
+            if not resolved_asset_ids:
+                raise HTTPException(
+                    status_code=422,
+                    detail="当前项目没有符合条件的视频素材，请先上传并等待导入完成后再生成。",
+                )

    use_case = CreateGenerationTaskUseCase(generation_task_repository)
    count = request.count
@@ -270,6 +288,8 @@ def create_generation_task(
                    asset_select_mode=request.asset_select_mode,
                    batch_id=batch_id,
                    video_title=request.video_title,
+                    resolution=request.resolution,
+                    bgm_config=request.bgm_config,
                    auto_retry_enabled=request.auto_retry_enabled,
                    auto_retry_max=request.auto_retry_max,
                )
@@ -408,6 +428,7 @@ def retry_generation_task(
            source_edit_plan_id=task.source_edit_plan_id or "",
            asset_select_mode=getattr(task, "asset_select_mode", ""),
            video_title=getattr(task, "video_title", ""),
+            resolution=getattr(task, "resolution", ""),
        )
    )
    try:
@@ -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,298 @@
+"""视频分享 API 路由."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from app.api.routes._helpers import format_utc_datetime
+from app.auth import AuthenticatedUser, get_current_user
+from app.core.storage import OSSStorageService, get_storage_service
+from app.dependencies import get_db_session, get_generated_video_repository
+from app.schemas.video_share import (
+    CreateShareRequest,
+    ShareAccessResponse,
+    ShareListResponse,
+    ShareMetaResponse,
+    ShareResponse,
+    UpdateShareRequest,
+    VerifySharePasswordRequest,
+)
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.video_share_repository import (
+    SQLAlchemyVideoShareRepository,
+)
+from packages.application.video_share.commands import (
+    CreateShareCommand,
+    UpdateShareCommand,
+)
+from packages.application.video_share.use_cases import (
+    AccessShareUseCase,
+    CreateShareUseCase,
+    GetShareByTokenUseCase,
+    InvalidPasswordError,
+    ListSharesByUserUseCase,
+    ListSharesByVideoUseCase,
+    NotFoundError,
+    PasswordRequiredError,
+    RecordShareDownloadUseCase,
+    RevokeShareUseCase,
+    ShareExpiredError,
+    UpdateShareUseCase,
+    VideoNotFoundError,
+)
+from packages.ports.generated_video_repository import GeneratedVideoRepository
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _get_share_repository(
+    session: Session = Depends(get_db_session),
+) -> SQLAlchemyVideoShareRepository:
+    return SQLAlchemyVideoShareRepository(session)
+
+
+def _to_share_response(share) -> ShareResponse:
+    return ShareResponse(
+        id=share.id,
+        video_id=share.video_id,
+        share_token=share.share_token,
+        has_password=share.has_password,
+        expires_at=share.expires_at,
+        view_count=share.view_count,
+        download_count=share.download_count,
+        is_active=share.is_active,
+        created_at=format_utc_datetime(share.created_at),
+        updated_at=format_utc_datetime(share.updated_at),
+    )
+
+
+# ── 用户侧：创建/管理分享 ──────────────────────────────────
+
+
+@router.post("/videos/{video_id}/share", response_model=ShareResponse)
+def create_share(
+    video_id: str,
+    request: CreateShareRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+    video_repo: GeneratedVideoRepository = Depends(get_generated_video_repository),
+) -> ShareResponse:
+    """为视频创建分享链接."""
+    use_case = CreateShareUseCase(share_repo, video_repo)
+    try:
+        share = use_case.execute(
+            CreateShareCommand(
+                video_id=video_id,
+                user_id=authenticated_user.user.id,
+                password=request.password,
+                expires_at=request.expires_at,
+            )
+        )
+    except VideoNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+    logger.info(
+        "Share created: video_id=%s share_id=%s token=%s user=%s",
+        video_id,
+        share.id,
+        share.share_token,
+        authenticated_user.user.id,
+    )
+    return _to_share_response(share)
+
+
+@router.get("/videos/{video_id}/shares", response_model=ShareListResponse)
+def list_video_shares(
+    video_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+) -> ShareListResponse:
+    """获取某个视频的所有分享记录."""
+    use_case = ListSharesByVideoUseCase(share_repo)
+    items = use_case.execute(video_id, authenticated_user.user.id)
+    return ShareListResponse(
+        items=[_to_share_response(s) for s in items],
+        total=len(items),
+        skip=0,
+        limit=len(items),
+    )
+
+
+@router.get("/shares", response_model=ShareListResponse)
+def list_user_shares(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(20, ge=1, le=100),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+) -> ShareListResponse:
+    """获取用户创建的所有分享记录."""
+    use_case = ListSharesByUserUseCase(share_repo)
+    items, total = use_case.execute(authenticated_user.user.id, skip=skip, limit=limit)
+    return ShareListResponse(
+        items=[_to_share_response(s) for s in items],
+        total=total,
+        skip=skip,
+        limit=limit,
+    )
+
+
+@router.patch("/shares/{share_id}", response_model=ShareResponse)
+def update_share(
+    share_id: str,
+    request: UpdateShareRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+) -> ShareResponse:
+    """更新分享配置（密码、有效期等）."""
+    use_case = UpdateShareUseCase(share_repo)
+    try:
+        share = use_case.execute(
+            UpdateShareCommand(
+                share_id=share_id,
+                user_id=authenticated_user.user.id,
+                password=request.password,
+                expires_at=request.expires_at,
+            )
+        )
+    except NotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+    return _to_share_response(share)
+
+
+@router.delete(
+    "/shares/{share_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    response_model=None,
+    response_class=Response,
+)
+def revoke_share(
+    share_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+) -> Response:
+    """撤销/删除分享链接."""
+    use_case = RevokeShareUseCase(share_repo)
+    try:
+        use_case.execute(share_id, authenticated_user.user.id)
+    except NotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+# ── 公开侧：访问分享内容（无需登录） ──────────────────────
+
+
+@router.get("/share/{token}/meta", response_model=ShareMetaResponse)
+def get_share_meta(
+    token: str,
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+    video_repo: GeneratedVideoRepository = Depends(get_generated_video_repository),
+    storage: OSSStorageService = Depends(get_storage_service),
+) -> ShareMetaResponse:
+    """获取分享元信息（不需要密码，用于分享页加载前判断）。"""
+    use_case = GetShareByTokenUseCase(share_repo)
+    try:
+        share = use_case.execute(token)
+    except (NotFoundError, ShareExpiredError) as e:
+        raise HTTPException(status_code=404, detail="分享链接不存在或已失效") from e
+
+    video = video_repo.get(share.video_id)
+    video_name = video.name if video else ""
+    video_duration = video.duration if video else 0.0
+    thumbnail_url = None
+    if video and video.thumbnail_url:
+        try:
+            thumbnail_url = storage.get_download_url(video.thumbnail_url)
+        except Exception:
+            thumbnail_url = video.thumbnail_url
+
+    return ShareMetaResponse(
+        share_token=share.share_token,
+        has_password=share.has_password,
+        is_expired=share.is_expired,
+        is_active=share.is_active,
+        video_name=video_name,
+        video_duration=video_duration,
+        thumbnail_url=thumbnail_url,
+        created_at=format_utc_datetime(share.created_at),
+    )
+
+
+@router.post("/share/{token}/access", response_model=ShareAccessResponse)
+def access_share(
+    token: str,
+    request: Optional[VerifySharePasswordRequest] = None,
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+    video_repo: GeneratedVideoRepository = Depends(get_generated_video_repository),
+    storage: OSSStorageService = Depends(get_storage_service),
+) -> ShareAccessResponse:
+    """访问分享内容（验证密码后返回视频信息+播放/下载地址）。"""
+    use_case = AccessShareUseCase(share_repo, video_repo)
+    password = request.password if request else None
+    try:
+        result = use_case.execute(token, password=password)
+    except NotFoundError as e:
+        raise HTTPException(status_code=404, detail="分享链接不存在或已失效") from e
+    except ShareExpiredError as e:
+        raise HTTPException(status_code=410, detail="分享链接已过期或已撤销") from e
+    except PasswordRequiredError as e:
+        raise HTTPException(status_code=403, detail="需要访问密码") from e
+    except InvalidPasswordError as e:
+        raise HTTPException(status_code=403, detail="密码错误") from e
+    except VideoNotFoundError as e:
+        raise HTTPException(status_code=404, detail="视频不存在") from e
+
+    # 生成下载URL
+    download_url = None
+    if result.video.file_url:
+        try:
+            download_url = storage.get_download_url(result.video.file_url)
+        except Exception:
+            download_url = result.video.file_url
+
+    # 缩略图URL
+    thumbnail_url = None
+    if result.video.thumbnail_url:
+        try:
+            thumbnail_url = storage.get_download_url(result.video.thumbnail_url)
+        except Exception:
+            thumbnail_url = result.video.thumbnail_url
+
+    return ShareAccessResponse(
+        share=_to_share_response(result.share),
+        video_name=result.video.name,
+        video_duration=result.video.duration,
+        video_size=result.video.file_size,
+        thumbnail_url=thumbnail_url,
+        download_url=download_url,
+        password_verified=result.password_verified,
+    )
+
+
+@router.post("/share/{token}/download")
+def record_share_download(
+    token: str,
+    request: Optional[VerifySharePasswordRequest] = None,
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+) -> dict:
+    """记录分享下载（下载计数+1）。"""
+    use_case = RecordShareDownloadUseCase(share_repo)
+    password = request.password if request else None
+    try:
+        use_case.execute(token, password=password)
+    except NotFoundError as e:
+        raise HTTPException(status_code=404, detail="分享链接不存在或已失效") from e
+    except ShareExpiredError as e:
+        raise HTTPException(status_code=410, detail="分享链接已过期或已撤销") from e
+    except InvalidPasswordError as e:
+        raise HTTPException(status_code=403, detail="密码错误") from e
+    return {"success": True}
@@ -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,
+    )
@@ -6,6 +6,7 @@ import logging
 from typing import Optional

 from app.auth import AuthenticatedUser, get_current_user
+from app.core.celery_app import celery_app
 from app.dependencies import (
    get_audio_url_signer,
    get_cosyvoice_service,
@@ -181,13 +182,9 @@ def synthesize(

        try:
            if is_segment:
-                from worker_app.tasks import process_tts_segment_synthesis
-
-                process_tts_segment_synthesis.delay(job.id)
+                celery_app.send_task("worker.process_tts_segment_synthesis", args=[job.id])
            else:
-                from worker_app.tasks import process_tts_synthesis
-
-                process_tts_synthesis.delay(job.id)
+                celery_app.send_task("worker.process_tts_synthesis", args=[job.id])
        except Exception as e:
            # Celery 调度失败，标记 job 为 failed
            try:
@@ -6,6 +6,7 @@ import logging
 from typing import Optional

 from app.auth import AuthenticatedUser, get_current_user
+from app.core.celery_app import celery_app
 from app.dependencies import get_cosyvoice_service, get_voice_clone_profile_repository
 from app.schemas.voice_clone import (
    CreateVoiceCloneRequest,
@@ -97,9 +98,7 @@ def create_voice_clone(
    task_id = (profile.metadata or {}).get("cosyvoice_task_id", "")
    if profile.status == "processing" and task_id:
        try:
-            from worker_app.tasks import process_voice_clone
-
-            process_voice_clone.delay(profile.id)
+            celery_app.send_task("worker.process_voice_clone", args=[profile.id])
            logger.info(f"Celery task dispatched for voice clone {profile.id}")
        except Exception as e:
            logger.error(f"Failed to dispatch Celery task: {e}")
@@ -213,9 +212,7 @@ def retry_voice_clone(
    task_id = (profile.metadata or {}).get("cosyvoice_task_id", "")
    if profile.status == "processing" and task_id:
        try:
-            from worker_app.tasks import process_voice_clone
-
-            process_voice_clone.delay(profile.id)
+            celery_app.send_task("worker.process_voice_clone", args=[profile.id])
            logger.info(f"Celery task dispatched for voice clone retry {profile.id}")
        except Exception as e:
            logger.error(f"Failed to dispatch Celery task: {e}")
@@ -1,171 +1,28 @@
-import os
-from typing import Optional
+"""API 服务配置（向后兼容层）。

-from pydantic import AliasChoices, Field, field_validator
-from pydantic_settings import BaseSettings, SettingsConfigDict
+统一配置已迁移到 packages.config.api_settings。
+新代码请使用：
+    from packages.config import APISettings, get_api_settings

+本文件保留 Settings 类名、get_settings() 函数、settings 模块级单例，
+确保所有旧的 import 路径仍然有效。
+"""

-class Settings(BaseSettings):
-    APP_NAME: str = "xiaoxia-saas"
-    APP_VERSION: str = "0.1.61"
-    ENVIRONMENT: str = "development"
-    DEBUG: bool = True
-
-    # 应用基础 URL，用于生成认证邮件中的链接
-    # 开发环境默认 http://localhost:3000
-    # 生产环境应通过环境变量 APP_BASE_URL 设置
-    APP_BASE_URL: str = "http://localhost:3000"
-
-    # Container bind address; external expose is controlled by Docker/Nginx.
-    API_HOST: str = "0.0.0.0"  # nosec: B104
-    API_PORT: int = 8000
-
-    DATABASE_URL: str = "postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas"
-    DATABASE_POOL_SIZE: int = 20
-    DATABASE_MAX_OVERFLOW: int = 10  # 调整为合理值：pool_size(20) + max_overflow(10) = 最大30连接
-    DATABASE_POOL_TIMEOUT: int = 30
-    DATABASE_POOL_RECYCLE: int = 3600
-    USE_IN_MEMORY_DB: bool = False
-    AUTO_CREATE_SCHEMA: bool = False
-
-    REDIS_URL: str = "redis://localhost:6379/0"
-    ENABLE_REDIS_SESSIONS: bool = False
-
-    # JWT secret key - MUST be set via environment variable, no default allowed
-    JWT_SECRET_KEY: Optional[str] = None
-
-    # JWT 算法与过期时间（与 .env.example 对齐）
-    JWT_ALGORITHM: str = "HS256"
-    JWT_ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
-    JWT_REFRESH_TOKEN_EXPIRE_DAYS: int = 30
-
-    @field_validator("JWT_SECRET_KEY", mode="before")
-    @classmethod
-    def validate_jwt_secret_key(cls, v):
-        if v is None or v == "":
-            raise ValueError(
-                "JWT_SECRET_KEY must be set via environment variable. " "Do not use default value in production!"
-            )
-        # Block known insecure default values
-        insecure_defaults = [
-            "your-secret-key-change-in-production",
-            "your-secret-key",
-            "secret",
-            "changeme",
-            "password",
-        ]
-        if v.lower() in [d.lower() for d in insecure_defaults]:
-            raise ValueError(
-                f"JWT_SECRET_KEY '{v}' is insecure. " "Please set a strong random secret via environment variable."
-            )
-        return v
-
-    ENABLE_EMAIL_DELIVERY: bool = False
-    SMTP_HOST: str = "smtp.gmail.com"
-    SMTP_PORT: int = 587
-    SMTP_USER: str = ""
-    SMTP_PASSWORD: str = ""
-    SMTP_FROM_EMAIL: str = ""
-    SMTP_FROM_NAME: str = "小虾 SaaS"
-    SMTP_USE_TLS: bool = True
-
-    CELERY_BROKER_URL: str = "redis://localhost:6379/0"
-    CELERY_RESULT_BACKEND: str = "redis://localhost:6379/1"
-
-    # OSS 七牛云相关
-    OSS_ENDPOINT: str = "oss-cn-hangzhou.aliyuncs.com"
-    OSS_ACCESS_KEY_ID: str = ""
-    OSS_ACCESS_KEY_SECRET: str = ""
-    OSS_BUCKET_NAME: str = "xiaoxia-autocut"
-
-    @field_validator("OSS_ACCESS_KEY_ID", mode="before")
-    @classmethod
-    def validate_oss_access_key_id(cls, v):
-        if (v is None or v == "") and os.getenv("APP_ENV", "development") != "development":
-            raise ValueError(
-                "OSS_ACCESS_KEY_ID must be set via environment variable in non-development environments. "
-                "Check the server .env file (e.g. /var/lib/xiaoxia-saas-staging/.env)."
-            )
-        return v or ""
-
-    @field_validator("OSS_ACCESS_KEY_SECRET", mode="before")
-    @classmethod
-    def validate_oss_access_key_secret(cls, v):
-        if (v is None or v == "") and os.getenv("APP_ENV", "development") != "development":
-            raise ValueError(
-                "OSS_ACCESS_KEY_SECRET must be set via environment variable in non-development environments. "
-                "Check the server .env file (e.g. /var/lib/xiaoxia-saas-staging/.env)."
-            )
-        return v or ""
-
-    OSS_DIRECT_UPLOAD_MAX_MB: int = Field(
-        default=2000,
-        validation_alias=AliasChoices("OSS_DIRECT_UPLOAD_MAX_MB", "MAX_UPLOAD_SIZE_MB"),
-    )
-    OSS_DIRECT_UPLOAD_EXPIRE_SECONDS: int = 900
-
-    CORS_ORIGINS_RAW: str = "http://localhost:3000,http://localhost:5173,http://localhost:8000"
-
-    # 渲染引擎选择：legacy=旧VideoComposeService，unified=新UnifiedRenderService
-    RENDER_ENGINE: str = "legacy"
-
-    model_config = SettingsConfigDict(
-        env_file=".env",
-        env_file_encoding="utf-8",
-        case_sensitive=False,
-        extra="ignore",
-    )
-
-    @property
-    def CORS_ORIGINS(self) -> list[str]:
-        return [origin.strip() for origin in self.CORS_ORIGINS_RAW.split(",") if origin.strip()]
-
-    @property
-    def database_url(self) -> str:
-        return self.DATABASE_URL
-
-    @property
-    def redis_url(self) -> str:
-        return self.REDIS_URL
-
-    @property
-    def celery_broker_url(self) -> str:
-        return self.CELERY_BROKER_URL
-
-    @property
-    def celery_result_backend(self) -> str:
-        return self.CELERY_RESULT_BACKEND
-
-    @property
-    def oss_endpoint(self) -> str:
-        return self.OSS_ENDPOINT
-
-    @property
-    def oss_access_key_id(self) -> str:
-        return self.OSS_ACCESS_KEY_ID
-
-    @property
-    def oss_access_key_secret(self) -> str:
-        return self.OSS_ACCESS_KEY_SECRET
-
-    @property
-    def oss_bucket_name(self) -> str:
-        return self.OSS_BUCKET_NAME
-
-
-_settings: Optional[Settings] = None
-
-
-def get_settings() -> Settings:
-    global _settings
-    if _settings is None:
-        env = os.getenv("APP_ENV", "development")
-        env_file = f".env.{env}" if env != "development" else ".env"
-        if os.path.exists(env_file):
-            _settings = Settings(_env_file=env_file)
-        else:
-            _settings = Settings()
-    return _settings
-
+from packages.config import APISettings as Settings
+from packages.config import get_api_settings as get_settings
+from packages.config import reload_settings_cache

+# 模块级单例（向后兼容）
 settings = get_settings()
+
+
+# 暴露旧的 reload_settings 函数名
+def reload_settings():
+    """重新加载配置（测试用）。"""
+    reload_settings_cache()
+    global settings
+    settings = get_settings()
+    return settings
+
+
+__all__ = ["Settings", "get_settings", "settings", "reload_settings"]
@@ -1,19 +1,20 @@
-"""Compatibility layer for the canonical API settings module.
+"""向后兼容层 — 配置已统一到 packages.config。

-Use `app.config` as the single source of truth for API configuration.
-This module remains only for older imports during migration.
+新代码请使用：
+    from packages.config import get_api_settings, APISettings
 """

-from app.config import Settings as AppSettings
-from app.config import get_settings, settings
+from packages.config import APISettings as AppSettings
+from packages.config import get_api_settings as get_settings
+from packages.config import reload_settings_cache


 def reload_settings() -> AppSettings:
-    """Reload settings for tests and legacy callers."""
-    import app.config as canonical_config
+    """重新加载配置（测试用）。"""
+    reload_settings_cache()
+    return get_settings()

-    canonical_config.settings = canonical_config.get_settings()
-    return canonical_config.settings

+settings = get_settings()

 __all__ = ["AppSettings", "get_settings", "reload_settings", "settings"]
@@ -46,6 +46,16 @@ class CreateGenerationTaskRequest(BaseModel):
        le=5,
        description="最大自动重试次数，0表示不自动重试，最大5次",
    )
+    # ── 输出分辨率 ──
+    resolution: str = Field(
+        default="",
+        description="输出分辨率，格式为 WIDTHxHEIGHT，如 1280x720、1080x1920。为空使用默认 1280x720",
+    )
+    # ── 自定义 BGM ──
+    bgm_config: dict = Field(
+        default_factory=dict,
+        description="自定义BGM配置，覆盖模板BGM设置。支持 enabled/source/asset_id/preset_id/audio_url/volume 等字段",
+    )

    @model_validator(mode="after")
    def _check_at_least_one_mode(self) -> "CreateGenerationTaskRequest":
@@ -74,6 +84,8 @@ class GenerationTaskResponse(BaseModel):
    asset_select_mode: str = ""
    batch_id: str = ""
    video_title: str = ""
+    resolution: str = ""
+    bgm_config: dict = Field(default_factory=dict)
    status: str
    progress: float
    result_count: int
@@ -0,0 +1,92 @@
+"""视频分享相关 schemas."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class CreateShareRequest(BaseModel):
+    """创建分享请求."""
+
+    password: Optional[str] = Field(
+        None,
+        description="访问密码（可选，不设置则无需密码）",
+        min_length=0,
+        max_length=50,
+    )
+    expires_at: Optional[datetime] = Field(
+        None,
+        description="过期时间（可选，不设置则永久有效）",
+    )
+
+
+class UpdateShareRequest(BaseModel):
+    """更新分享配置请求."""
+
+    password: Optional[str] = Field(
+        None,
+        description="新密码（传空字符串清除密码，不传则不修改）",
+        max_length=50,
+    )
+    expires_at: Optional[datetime] = Field(
+        None,
+        description="新的过期时间（不传则不修改）",
+    )
+
+
+class VerifySharePasswordRequest(BaseModel):
+    """验证分享密码请求."""
+
+    password: str = Field(..., description="访问密码")
+
+
+class ShareResponse(BaseModel):
+    """分享记录响应."""
+
+    id: str
+    video_id: str
+    share_token: str
+    has_password: bool = False
+    expires_at: Optional[datetime] = None
+    view_count: int = 0
+    download_count: int = 0
+    is_active: bool = True
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+
+class ShareListResponse(BaseModel):
+    """分享列表响应."""
+
+    items: List[ShareResponse]
+    total: int = 0
+    skip: int = 0
+    limit: int = 20
+
+
+class ShareAccessResponse(BaseModel):
+    """分享访问成功响应（含视频信息）."""
+
+    share: ShareResponse
+    video_name: str
+    video_duration: float = 0.0
+    video_size: int = 0
+    thumbnail_url: Optional[str] = None
+    download_url: Optional[str] = None
+    password_verified: bool = True
+
+
+class ShareMetaResponse(BaseModel):
+    """分享元信息响应（访问前获取，用于判断是否需要密码）。"""
+
+    share_token: str
+    has_password: bool = False
+    is_expired: bool = False
+    is_active: bool = True
+    video_name: str = ""
+    video_duration: float = 0.0
+    thumbnail_url: Optional[str] = None
+    created_at: Optional[datetime] = None
@@ -0,0 +1,348 @@
+"""统一 AI 服务层 — 豆包大模型接入.
+
+提供基于字节跳动豆包大模型的 AI 能力：
+- 智能标题生成（爆款/情感/信息三种风格）
+- 后续扩展：智能素材匹配、AI 推荐片段编排等
+
+设计原则：
+1. 无 API Key 或调用失败时自动降级为本地模拟，不阻塞主流程
+2. 统一的客户端封装，新增能力只需加方法
+3. 所有模型相关配置集中在 Settings
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from packages.domain.ai_parsing import generate_titles_fallback as _generate_titles_fallback_base
+from packages.domain.ai_parsing import keyword_match_fallback as _semantic_match_fallback_base
+from packages.domain.ai_parsing import parse_semantic_match_response as _parse_semantic_match_base
+from packages.domain.ai_parsing import parse_titles_from_response as _parse_titles_from_response
+from packages.shared.ai_client import get_doubao_client
+
+logger = logging.getLogger(__name__)
+
+
+# ── 智能标题风格定义 ─────────────────────────────────────────────────────────
+
+TITLE_STYLES = {
+    "viral": {
+        "name": "爆款",
+        "description": "吸引点击、引发好奇的爆款标题，带有数字、疑问或反差感",
+        "examples": [
+            "3个方法让你效率翻倍，第2个最绝",
+            "为什么越努力越穷？真相扎心了",
+            "看完这个，我删掉了手机里一半的APP",
+        ],
+    },
+    "emotional": {
+        "name": "情感",
+        "description": "触动人心、引发共鸣的情感向标题",
+        "examples": [
+            "那些年我们一起追过的梦想",
+            "生活不易，但请相信光",
+            "致每一个在城市里打拼的你",
+        ],
+    },
+    "informative": {
+        "name": "信息",
+        "description": "清晰直白、传递核心信息的干货标题",
+        "examples": [
+            "2026年最新个税政策解读，一文讲透",
+            "新手剪辑入门：从0到1完整指南",
+            "产品对比：10款热门手机深度评测",
+        ],
+    },
+}
+
+
+# ── 智能标题生成 ─────────────────────────────────────────────────────────────
+
+
+def _generate_titles_fallback(
+    description: str,
+    style: str = "viral",
+    count: int = 5,
+) -> List[str]:
+    """本地降级：基于模板规则生成标题（薄包装，转发到 ai_parsing 模块）."""
+    style_info = TITLE_STYLES.get(style, TITLE_STYLES["viral"])
+    return _generate_titles_fallback_base(description, style_info, count)
+
+
+def generate_smart_titles(
+    description: str,
+    style: str = "viral",
+    count: int = 5,
+) -> Dict[str, Any]:
+    """生成智能标题.
+
+    Args:
+        description: 视频内容描述
+        style: 标题风格 viral/emotional/informative
+        count: 生成数量（5-10）
+
+    Returns:
+        {
+            "titles": [...],
+            "style": "viral",
+            "source": "doubao" | "fallback",  # 实际来源
+            "description": "...",
+        }
+    """
+    # 参数校验与边界处理
+    if style not in TITLE_STYLES:
+        style = "viral"
+    count = max(3, min(10, count))  # 3-10 个
+    description = (description or "").strip()
+
+    client = get_doubao_client()
+    if not client.is_available:
+        logger.info("豆包API未配置，使用本地降级生成标题")
+        titles = _generate_titles_fallback(description, style, count)
+        return {
+            "titles": titles,
+            "style": style,
+            "source": "fallback",
+            "description": description,
+        }
+
+    style_info = TITLE_STYLES[style]
+    system_prompt = (
+        f"你是一个专业的短视频标题创作专家，擅长根据视频内容生成吸引人的标题。\n"
+        f"请根据以下视频描述，生成{count}个{style_info['name']}风格的标题。\n"
+        f"风格说明：{style_info['description']}\n"
+        f"要求：\n"
+        f"1. 每个标题控制在8-25字之间\n"
+        f"2. 直接返回JSON数组格式，不要其他文字\n"
+        f"3. 标题要贴合内容，有吸引力"
+    )
+
+    user_prompt = f"视频描述：{description}\n\n请生成标题："
+
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_prompt},
+    ]
+
+    result = client.chat_completion(
+        messages=messages,
+        temperature=0.8,
+        max_tokens=512,
+    )
+
+    if result:
+        titles = _parse_titles_from_response(result)
+        if len(titles) >= 2:  # 至少解析出2个才算成功
+            titles = titles[:count]
+            logger.info(
+                "豆包智能标题生成成功: style=%s count=%d description=%s...",
+                style,
+                len(titles),
+                description[:20],
+            )
+            return {
+                "titles": titles,
+                "style": style,
+                "source": "doubao",
+                "description": description,
+            }
+        logger.warning("豆包返回内容解析失败，降级到本地生成: %s", result[:100])
+
+    # 降级到本地生成
+    titles = _generate_titles_fallback(description, style, count)
+    return {
+        "titles": titles,
+        "style": style,
+        "source": "fallback",
+        "description": description,
+    }
+
+
+# ── 智能素材语义匹配 ───────────────────────────────────────────────────────────
+
+
+def _semantic_match_fallback(
+    description: str,
+    assets: List[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
+    """本地降级：基于关键词的简单匹配（薄包装，转发到 ai_parsing 模块）."""
+    return _semantic_match_fallback_base(description, assets)
+
+
+def _parse_semantic_match_response(
+    content: str,
+    asset_ids: List[str],
+) -> Optional[Dict[str, float]]:
+    """从模型返回中解析素材匹配度（薄包装，转发到 ai_parsing 模块）."""
+    result = _parse_semantic_match_base(content, asset_ids)
+    if result is None:
+        return None
+    return dict(result)
+
+
+def semantic_match_assets(
+    description: str,
+    assets: List[Dict[str, Any]],
+    top_k: int = 0,
+) -> Dict[str, Any]:
+    """智能素材语义匹配.
+
+    根据用户描述，评估每个素材的语义匹配度并排序。
+
+    Args:
+        description: 用户描述的目标视频内容
+        assets: 素材列表，每个素材需含 id/name/tags/description 等字段
+        top_k: 返回前K个，0表示返回全部
+
+    Returns:
+        {
+            "matches": [{"asset_id": ..., "match_score": ..., ...}],
+            "source": "doubao" | "fallback",
+            "description": "...",
+            "total": 总数,
+        }
+    """
+    description = (description or "").strip()
+    if not assets:
+        return {"matches": [], "source": "fallback", "description": description, "total": 0}
+
+    client = get_doubao_client()
+    if not client.is_available:
+        logger.info("豆包API未配置，使用本地降级做素材语义匹配")
+        matched = _semantic_match_fallback(description, assets)
+        if top_k > 0:
+            matched = matched[:top_k]
+        return {
+            "matches": matched,
+            "source": "fallback",
+            "description": description,
+            "total": len(assets),
+        }
+
+    # 构建素材信息（控制 token 数量）
+    asset_summaries = []
+    for asset in assets[:50]:  # 最多传50个素材给模型
+        aid = asset.get("id", "")
+        name = asset.get("name", "")[:50]
+        tags = asset.get("tags", [])
+        tags_str = ",".join(str(t) for t in tags[:5])
+        desc = str(asset.get("description", ""))[:80]
+        asset_summaries.append(f"ID:{aid} | 名称:{name} | 标签:[{tags_str}] | 描述:{desc}")
+
+    asset_ids = [str(a.get("id", "")) for a in assets[:50]]
+
+    system_prompt = (
+        "你是一个专业的视频素材匹配助手。"
+        "根据用户的视频目标描述，评估每个素材的匹配程度。\n"
+        "评分规则：\n"
+        "- 0.0-0.3: 完全不相关\n"
+        "- 0.3-0.6: 有一定关联但不够匹配\n"
+        "- 0.6-0.8: 比较匹配，适合使用\n"
+        "- 0.8-1.0: 高度匹配，非常适合\n"
+        "只返回JSON对象，key为素材ID，value为匹配分数（0-1之间的小数）。"
+        "不要其他文字说明。"
+    )
+
+    user_prompt = (
+        f"目标视频描述：{description}\n\n"
+        f"素材列表：\n" + "\n".join(asset_summaries) + "\n\n请返回每个素材的匹配分数JSON："
+    )
+
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_prompt},
+    ]
+
+    result = client.chat_completion(
+        messages=messages,
+        temperature=0.3,
+        max_tokens=1024,
+    )
+
+    if result:
+        scores = _parse_semantic_match_response(result, asset_ids)
+        if scores:
+            # 把评分填回素材
+            matched = []
+            for asset in assets:
+                aid = str(asset.get("id", ""))
+                score = scores.get(aid, 0.3)  # 没评分的给默认偏低分
+                matched.append(
+                    {
+                        **asset,
+                        "match_score": round(score, 3),
+                        "match_reason": "doubao_semantic",
+                    }
+                )
+            matched.sort(key=lambda x: x["match_score"], reverse=True)
+
+            logger.info(
+                "豆包语义匹配完成: assets=%d top_score=%.2f description=%s...",
+                len(matched),
+                matched[0]["match_score"] if matched else 0,
+                description[:20],
+            )
+
+            if top_k > 0:
+                matched = matched[:top_k]
+
+            return {
+                "matches": matched,
+                "source": "doubao",
+                "description": description,
+                "total": len(assets),
+            }
+        logger.warning("豆包语义匹配返回解析失败，降级到本地: %s", result[:100])
+
+    # 降级
+    matched = _semantic_match_fallback(description, assets)
+    if top_k > 0:
+        matched = matched[:top_k]
+    return {
+        "matches": matched,
+        "source": "fallback",
+        "description": description,
+        "total": len(assets),
+    }
+
+
+# ── 单例入口 ─────────────────────────────────────────────────────────────────
+
+
+def get_ai_service() -> "AIService":
+    """获取 AI 服务单例."""
+    global _ai_service
+    if _ai_service is None:
+        _ai_service = AIService()
+    return _ai_service
+
+
+_ai_service: Optional["AIService"] = None
+
+
+class AIService:
+    """AI 服务统一入口，便于后续扩展更多能力."""
+
+    def __init__(self) -> None:
+        self._client = get_doubao_client()
+
+    @property
+    def is_available(self) -> bool:
+        return self._client.is_available
+
+    def generate_titles(
+        self,
+        description: str,
+        style: str = "viral",
+        count: int = 5,
+    ) -> Dict[str, Any]:
+        return generate_smart_titles(description, style, count)
+
+    def semantic_match(
+        self,
+        description: str,
+        assets: List[Dict[str, Any]],
+        top_k: int = 0,
+    ) -> Dict[str, Any]:
+        return semantic_match_assets(description, assets, top_k)
@@ -16,6 +16,11 @@ from packages.adapters.sqlalchemy_impl import (
    SQLAlchemyEditPlanRepository,
    SQLAlchemyGenerationTaskRepository,
 )
+from packages.domain.clip_operations import calculate_merge as _calc_merge
+from packages.domain.clip_operations import calculate_shift_orders as _calc_shift_orders
+from packages.domain.clip_operations import calculate_split as _calc_split
+from packages.domain.clip_operations import validate_merge_clips as _validate_merge
+from packages.domain.clip_operations import validate_split_time as _validate_split
 from packages.domain.edit_plan import EditPlan, EditPlanStatus
 from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus

@@ -384,36 +389,45 @@ class EditPlanService:
        clip = self.get_clip_or_raise(clip_id)
        plan_id = clip.plan_id

-        if split_time <= 0 or split_time >= clip.duration:
-            raise ValueError(f"分割时间必须在 (0, {clip.duration:.3f}) 范围内，当前: {split_time}")
+        # 纯逻辑：校验 + 计算
+        _validate_split(split_time, clip.duration)
+        split = _calc_split(
+            duration=clip.duration,
+            split_time=split_time,
+            start_time=clip.start_time,
+        )

        self._auto_resume_editing(plan_id)

-        original_duration = clip.duration
-        left_duration = round(split_time, 3)
-        right_duration = round(original_duration - split_time, 3)
        original_order = clip.order

        # 更新左半部分（原片段）
-        clip.duration = left_duration
+        clip.duration = split.left_duration
        left_clip = self._clip_repo.update(clip)

        # 后面片段的 order 全部 +1（给右半部分腾位置）
        all_clips = self._clip_repo.list_by_plan(plan_id)
-        for c in all_clips:
-            if c.order > original_order and c.id != clip_id:
-                c.order += 1
-                self._clip_repo.update(c)
+        shifts = _calc_shift_orders(
+            all_clips,
+            threshold_order=original_order,
+            shift=1,
+            excluded_ids={clip_id},
+            id_attr="id",
+            order_attr="order",
+        )
+        for c, new_order in shifts:
+            c.order = new_order
+            self._clip_repo.update(c)

        # 创建右半部分新片段（继承原片段的大部分属性）
        right_config = dict(clip.config) if clip.config else {}
        # 素材裁剪信息
        if clip.asset_id:
            # 右半部分从 split_time 开始播放
-            right_config["trim_start"] = left_duration
+            right_config["trim_start"] = split.right_trim_start
            # 左半部分在 split_time 处结束
            left_config = dict(left_clip.config) if left_clip.config else {}
-            left_config["trim_end"] = right_duration
+            left_config["trim_end"] = split.left_trim_end
            left_clip.config = left_config
            left_clip = self._clip_repo.update(left_clip)

@@ -424,8 +438,8 @@ class EditPlanService:
            template_clip_config_id=clip.template_clip_config_id,
            asset_id=clip.asset_id,
            text_content=clip.text_content,
-            start_time=clip.start_time + left_duration,
-            duration=right_duration,
+            start_time=split.right_start_time,
+            duration=split.right_duration,
            transition_effect=clip.transition_effect,
            transition_duration=clip.transition_duration,
            playback_speed=clip.playback_speed,
@@ -438,8 +452,8 @@ class EditPlanService:
            clip_id,
            plan_id,
            split_time,
-            left_duration,
-            right_duration,
+            split.left_duration,
+            split.right_duration,
        )

        return {
@@ -468,70 +482,45 @@ class EditPlanService:
            clip = self.get_clip_or_raise(cid)
            clips.append(clip)

-        # 校验：同一计划
-        plan_id = clips[0].plan_id
-        for c in clips[1:]:
-            if c.plan_id != plan_id:
-                raise ValueError("只能合并同一计划下的片段")
-
-        # 按 order 排序
-        clips.sort(key=lambda c: c.order)
-
-        # 校验：order 连续
-        for i in range(1, len(clips)):
-            if clips[i].order != clips[i - 1].order + 1:
-                raise ValueError(f"片段不连续：order {clips[i-1].order} → {clips[i].order}")
-
-        # 校验：类型一致
-        clip_type = clips[0].clip_type
-        for c in clips[1:]:
-            if c.clip_type != clip_type:
-                raise ValueError("只能合并相同类型的片段")
+        # 纯逻辑：校验 + 计算
+        plan_id, first_order = _validate_merge(clips)
+        merge = _calc_merge(clips)

        self._auto_resume_editing(plan_id)

-        # 计算合并后的属性
-        first_clip = clips[0]
-        total_duration = round(sum(c.duration for c in clips), 3)
-        first_order = first_clip.order
-
-        # 合并文案（用换行连接）
-        merged_text = "\n".join(c.text_content for c in clips if c.text_content.strip())
-
-        # 合并 config（后面的覆盖前面的）
-        merged_config: Dict[str, Any] = {}
-        for c in clips:
-            if c.config:
-                merged_config.update(c.config)
-        # 清理 trim 相关字段（合并后就是完整片段了）
-        merged_config.pop("trim_start", None)
-        merged_config.pop("trim_end", None)
-
        # 更新第一个片段（保留它作为合并结果）
-        first_clip.duration = total_duration
-        first_clip.text_content = merged_text
-        first_clip.config = merged_config
+        first_clip = sorted(clips, key=lambda c: c.order)[0]
+        first_clip.duration = merge.total_duration
+        first_clip.text_content = merge.merged_text
+        first_clip.config = merge.merged_config
        # 转场保留第一个的（合并后的入点转场）
        # playback_speed 取第一个的
        merged_clip = self._clip_repo.update(first_clip)

        # 删除其余片段
-        for c in clips[1:]:
-            self._clip_repo.delete(c.id)
+        rest_ids = [c.id for c in clips if c.id != merged_clip.id]
+        for cid in rest_ids:
+            self._clip_repo.delete(cid)

        # 后面的片段 order 前移 (len - 1) 位
-        shift = len(clips) - 1
        all_clips = self._clip_repo.list_by_plan(plan_id)
-        for c in all_clips:
-            if c.order > first_order and c.id != merged_clip.id:
-                c.order -= shift
-                self._clip_repo.update(c)
+        shifts = _calc_shift_orders(
+            all_clips,
+            threshold_order=first_order,
+            shift=-merge.shift_amount,
+            excluded_ids={merged_clip.id},
+            id_attr="id",
+            order_attr="order",
+        )
+        for c, new_order in shifts:
+            c.order = new_order
+            self._clip_repo.update(c)

        logger.info(
            "合并片段: plan_id=%s count=%d total_duration=%.3fs",
            plan_id,
            len(clips),
-            total_duration,
+            merge.total_duration,
        )

        return merged_clip
@@ -23,6 +23,13 @@ from packages.domain.template_clip_config import (
    TemplateClipConfig,
    TransitionEffect,
 )
+from packages.domain.template_clip_converter import (
+    clip_configs_to_snapshots,
+    clips_to_template_clip_configs,
+    filter_plan_config_to_template,
+    snapshots_to_template_clip_configs,
+    validate_template_name,
+)

 logger = logging.getLogger(__name__)

@@ -121,9 +128,7 @@ class EditTemplateService:
            ValueError: 名称为空或重复
        """
        # 名称校验
-        clean_name = name.strip()
-        if not clean_name:
-            raise ValueError("模板名称不能为空")
+        clean_name = validate_template_name(name)

        # 名称重复检查
        existing = self._template_repo.list_all(skip=0, limit=1000)
@@ -471,12 +476,7 @@ class EditTemplateService:
                raise ValueError(f"模板名称已存在: {clean_name}")

        # 从计划 config 中提取模板级配置，去掉运行时/素材相关字段
-        plan_config = plan.config or {}
-        template_config: dict[str, Any] = {}
-        for key, value in plan_config.items():
-            # 跳过明显的运行时/实例字段，保留风格/模式类配置
-            if key not in {"asset_ids", "source_edit_plan_id", "generation_task_id"}:
-                template_config[key] = value
+        template_config = filter_plan_config_to_template(plan.config)

        template = EditTemplate.create(
            name=clean_name,
@@ -497,40 +497,7 @@ class EditTemplateService:

        # 5. 转换每个片段为模板片段配置
        created_configs: List[TemplateClipConfig] = []
-        for clip in clips:
-            clip_config: dict[str, Any] = {}
-            # 播放速度存入 config
-            if clip.playback_speed and clip.playback_speed != 1.0:
-                clip_config["playback_speed"] = clip.playback_speed
-            # 片段自有 config 合并（优先级：clip.config 覆盖上面的）
-            if clip.config:
-                clip_config.update(clip.config)
-            # 去掉素材相关字段
-            clip_config.pop("asset_info", None)
-            clip_config.pop("source_asset_id", None)
-
-            # 转场效果兼容校验
-            try:
-                transition = TransitionEffect(clip.transition_effect)
-            except ValueError:
-                transition = TransitionEffect.CUT
-
-            # 片段类型兼容校验
-            try:
-                clip_type = ClipType(clip.clip_type)
-            except ValueError:
-                clip_type = ClipType.MAIN
-
-            clip_config_obj = TemplateClipConfig.create(
-                template_id=created_template.id,
-                clip_type=clip_type,
-                order=clip.order,
-                min_duration=clip.duration,
-                max_duration=clip.duration,
-                text_template=clip.text_content or "",
-                transition_effect=transition,
-                config=clip_config,
-            )
+        for clip_config_obj in clips_to_template_clip_configs(created_template.id, clips):
            created = self._clip_config_repo.create(clip_config_obj)
            created_configs.append(created)

@@ -679,8 +646,6 @@ class EditTemplateService:
        Raises:
            ValueError: 模板/草稿不存在，或草稿不属于该模板
        """
-        from packages.domain.template_clip_config import TemplateClipConfig
-
        # 1. 校验模板和草稿
        template = self.get_template_or_raise(template_id)
        draft = self._plan_repo.get(draft_plan_id)
@@ -700,39 +665,14 @@ class EditTemplateService:
        editing_mode = config.get("editing_mode", "one_take")

        # 4. 提取模板配置（去掉草稿/运行时字段）
-        draft_config = draft.config or {}
-        template_config: dict[str, Any] = {}
-        skip_keys = {
-            "is_template_draft",
-            "asset_ids",
-            "source_edit_plan_id",
-            "generation_task_id",
-        }
-        for key, value in draft_config.items():
-            if key not in skip_keys:
-                template_config[key] = value
+        template_config = filter_plan_config_to_template(draft.config)

        # 5. 事务更新
        try:
            # 5.0 先保存旧版快照（发布前的状态），用于回滚
            old_version = template.version or 1
            old_clip_configs = self._clip_config_repo.list_by_template(template_id)
-            old_clip_snapshots = [
-                {
-                    "clip_type": cfg.clip_type.value if hasattr(cfg.clip_type, "value") else cfg.clip_type,
-                    "order": cfg.order,
-                    "min_duration": cfg.min_duration,
-                    "max_duration": cfg.max_duration,
-                    "text_template": cfg.text_template or "",
-                    "transition_effect": (
-                        cfg.transition_effect.value
-                        if hasattr(cfg.transition_effect, "value")
-                        else cfg.transition_effect
-                    ),
-                    "config": cfg.config or {},
-                }
-                for cfg in old_clip_configs
-            ]
+            old_clip_snapshots = clip_configs_to_snapshots(old_clip_configs)

            from packages.domain.template_version import EditTemplateVersion

@@ -759,46 +699,7 @@ class EditTemplateService:

            # 创建新的片段配置
            created_configs: list[TemplateClipConfig] = []
-            for clip in draft_clips:
-                clip_config: dict[str, Any] = {}
-                # 播放速度存入 config
-                if clip.playback_speed and clip.playback_speed != 1.0:
-                    clip_config["playback_speed"] = clip.playback_speed
-                # 片段自有 config 合并
-                if clip.config:
-                    clip_config.update(clip.config)
-                # 去掉素材相关字段
-                clip_config.pop("asset_info", None)
-                clip_config.pop("source_asset_id", None)
-
-                # 转场效果兼容校验
-                try:
-                    from packages.domain.template_clip_config import (
-                        TransitionEffect,
-                    )
-
-                    transition = TransitionEffect(clip.transition_effect)
-                except (ValueError, ImportError):
-                    transition = TransitionEffect.CUT  # type: ignore
-
-                # 片段类型兼容校验
-                try:
-                    from packages.domain.template_clip_config import ClipType
-
-                    clip_type = ClipType(clip.clip_type)
-                except (ValueError, ImportError):
-                    clip_type = ClipType.MAIN  # type: ignore
-
-                config_obj = TemplateClipConfig.create(
-                    template_id=template_id,
-                    clip_type=clip_type,
-                    order=clip.order,
-                    min_duration=clip.duration,
-                    max_duration=clip.duration,
-                    text_template=clip.text_content or "",
-                    transition_effect=transition,
-                    config=clip_config,
-                )
+            for config_obj in clips_to_template_clip_configs(template_id, draft_clips):
                created = self._clip_config_repo.create(config_obj)
                created_configs.append(created)

@@ -843,8 +744,6 @@ class EditTemplateService:
        Raises:
            ValueError: 模板/版本不存在
        """
-        from packages.domain.template_clip_config import TemplateClipConfig
-
        template = self.get_template_or_raise(template_id)

        # 1. 读取目标版本快照
@@ -857,22 +756,7 @@ class EditTemplateService:
        try:
            # 2. 先保存当前状态快照（当前版本号），确保回滚可撤销
            old_clip_configs = self._clip_config_repo.list_by_template(template_id)
-            old_clip_snapshots = [
-                {
-                    "clip_type": cfg.clip_type.value if hasattr(cfg.clip_type, "value") else cfg.clip_type,
-                    "order": cfg.order,
-                    "min_duration": cfg.min_duration,
-                    "max_duration": cfg.max_duration,
-                    "text_template": cfg.text_template or "",
-                    "transition_effect": (
-                        cfg.transition_effect.value
-                        if hasattr(cfg.transition_effect, "value")
-                        else cfg.transition_effect
-                    ),
-                    "config": cfg.config or {},
-                }
-                for cfg in old_clip_configs
-            ]
+            old_clip_snapshots = clip_configs_to_snapshots(old_clip_configs)

            from packages.domain.template_version import EditTemplateVersion

@@ -905,37 +789,7 @@ class EditTemplateService:
                synchronize_session=False
            )

-            for clip_snap in target_version.clip_configs:
-                # 转场效果兼容校验
-                try:
-                    from packages.domain.template_clip_config import TransitionEffect
-
-                    transition = TransitionEffect(clip_snap.get("transition_effect", "cut"))
-                except (ValueError, ImportError):
-                    from packages.domain.template_clip_config import TransitionEffect
-
-                    transition = TransitionEffect.CUT
-
-                # 片段类型兼容校验
-                try:
-                    from packages.domain.template_clip_config import ClipType
-
-                    clip_type = ClipType(clip_snap.get("clip_type", "main"))
-                except (ValueError, ImportError):
-                    from packages.domain.template_clip_config import ClipType
-
-                    clip_type = ClipType.MAIN
-
-                config_obj = TemplateClipConfig.create(
-                    template_id=template_id,
-                    clip_type=clip_type,
-                    order=clip_snap.get("order", 0),
-                    min_duration=clip_snap.get("min_duration", 0.0),
-                    max_duration=clip_snap.get("max_duration", 0.0),
-                    text_template=clip_snap.get("text_template", ""),
-                    transition_effect=transition,
-                    config=clip_snap.get("config", {}) or {},
-                )
+            for config_obj in snapshots_to_template_clip_configs(template_id, target_version.clip_configs):
                self._clip_config_repo.create(config_obj)

            self._db.commit()
@@ -26,7 +26,13 @@ from packages.domain.edit_plan import EditPlan
 from packages.domain.edit_plan_clip import EditPlanClip
 from packages.domain.edit_template import EditTemplate
 from packages.domain.editing_mode import EditingMode
-from packages.domain.template_clip_config import ClipType, TemplateClipConfig
+from packages.domain.plan_generator_utils import (
+    create_clips_from_configs,
+    distribute_assets,
+    generate_default_clips,
+    map_clip_types_for_mode,
+)
+from packages.domain.template_clip_config import TemplateClipConfig

 logger = logging.getLogger(__name__)

@@ -163,83 +169,18 @@ class PlanGeneratorService:
        plan_id: str,
        clip_configs: List[TemplateClipConfig],
    ) -> List[EditPlanClip]:
-        """从 TemplateClipConfig 列表创建 EditPlanClip 列表（未持久化）"""
-        clips: List[EditPlanClip] = []
-        # 按 order 排序
-        sorted_configs = sorted(clip_configs, key=lambda c: c.order)
+        """从 TemplateClipConfig 列表创建 EditPlanClip 列表（未持久化）.

-        for cfg in sorted_configs:
-            # 计算时长：取 min_duration 和 max_duration 的中间值
-            if cfg.min_duration > 0 and cfg.max_duration > 0:
-                duration = (cfg.min_duration + cfg.max_duration) / 2
-            elif cfg.min_duration > 0:
-                duration = cfg.min_duration
-            elif cfg.max_duration > 0:
-                duration = cfg.max_duration
-            else:
-                duration = _DEFAULT_CLIP_DURATION
-
-            # clip_type 可能是枚举或字符串
-            clip_type = cfg.clip_type.value if hasattr(cfg.clip_type, "value") else cfg.clip_type
-
-            # transition_effect 可能是枚举或字符串
-            transition = (
-                cfg.transition_effect.value if hasattr(cfg.transition_effect, "value") else cfg.transition_effect
-            )
-
-            # 从 clip config 中解析 playback_speed（兼容 speed_ratio 字段名）
-            clip_cfg = cfg.config or {}
-            playback_speed = clip_cfg.get("playback_speed", clip_cfg.get("speed_ratio", 1.0)) or 1.0
-
-            clip = EditPlanClip.create(
-                plan_id=plan_id,
-                clip_type=clip_type,
-                order=cfg.order,
-                template_clip_config_id=cfg.id,
-                text_content=getattr(cfg, "text_template", "") or "",
-                duration=duration,
-                transition_effect=transition or "cut",
-                playback_speed=playback_speed,
-                config=clip_cfg,
-            )
-            clips.append(clip)
-
-        return clips
+        委托给 plan_generator_utils.create_clips_from_configs 纯函数。
+        """
+        return create_clips_from_configs(plan_id, clip_configs)

    def _map_clip_types_for_mode(self, clips: List[EditPlanClip], editing_mode: str) -> None:
-        """将模板 clip_config 生成的 MAIN 类型片段，按 editing_mode 映射为对应角色类型。
+        """将 MAIN 类型片段按 editing_mode 映射为对应角色类型.

-        模板的 clip_config 使用 ClipType 枚举（main/intro/outro 等），
-        但 PIP / VOICE_PIP 模式的素材分配和渲染分层依赖特定的 clip_type 命名
-        （overlay / background / corner_voice / b_roll）。
-
-        映射规则（仅修改 MAIN 类型片段，非 MAIN 片段保持原类型）：
-        - PIP: 第1个 MAIN → main（背景），其余 MAIN → overlay（画中画）
-        - VOICE_PIP: 第1个 → background，第2个 → corner_voice，第3+个 → b_roll
-        - ONE_TAKE / VOICE_OVER: 保持 main 不变
+        委托给 plan_generator_utils.map_clip_types_for_mode 纯函数。
        """
-        from packages.domain.template_clip_config import ClipType
-
-        main_clips = [c for c in clips if c.clip_type == ClipType.MAIN.value]
-        if not main_clips:
-            return
-
-        if editing_mode == EditingMode.PIP.value:
-            # 第1个 main 保持（背景层），其余改为 overlay（画中画层）
-            for i, clip in enumerate(main_clips):
-                if i > 0:
-                    clip.clip_type = "overlay"
-
-        elif editing_mode == EditingMode.VOICE_PIP.value:
-            for i, clip in enumerate(main_clips):
-                if i == 0:
-                    clip.clip_type = "background"
-                elif i == 1:
-                    clip.clip_type = "corner_voice"
-                else:
-                    clip.clip_type = "b_roll"
-
-        # ONE_TAKE / VOICE_OVER: 保持 main 不变，无需处理
+        map_clip_types_for_mode(clips, editing_mode)

    def _generate_default_clips(
        self,
@@ -247,101 +188,11 @@ class PlanGeneratorService:
        editing_mode: str,
        asset_count: int,
    ) -> List[EditPlanClip]:
-        """无 clip_configs 时，根据 editing_mode 生成默认 clip 结构
+        """无 clip_configs 时，根据 editing_mode 生成默认 clip 结构.

-        - ONE_TAKE: N 个 main clips（N = asset_count，至少1个）
-        - PIP: 1 个 main + (N-1) 个 overlay（N = asset_count）
-        - VOICE_OVER: N 个 main clips + 标记需要配音
-        - VOICE_PIP: 1 个 background + 1 个 corner_voice + (N-2) 个 b_roll
+        委托给 plan_generator_utils.generate_default_clips 纯函数。
        """
-        n = max(asset_count, 1)
-        clips: List[EditPlanClip] = []
-        order = 0
-
-        if editing_mode == EditingMode.PIP.value:
-            # 1 个 main（全屏背景）
-            clips.append(
-                EditPlanClip.create(
-                    plan_id=plan_id,
-                    clip_type=ClipType.MAIN.value,
-                    order=order,
-                    duration=_DEFAULT_CLIP_DURATION,
-                )
-            )
-            order += 1
-            # 剩余为 overlay
-            for _ in range(1, n):
-                clips.append(
-                    EditPlanClip.create(
-                        plan_id=plan_id,
-                        clip_type="overlay",
-                        order=order,
-                        duration=_DEFAULT_CLIP_DURATION,
-                    )
-                )
-                order += 1
-
-        elif editing_mode == EditingMode.VOICE_OVER.value:
-            # N 个 main clips（B-roll）
-            for _ in range(n):
-                clips.append(
-                    EditPlanClip.create(
-                        plan_id=plan_id,
-                        clip_type=ClipType.MAIN.value,
-                        order=order,
-                        duration=_DEFAULT_CLIP_DURATION,
-                        config={"role": "b_roll"},
-                    )
-                )
-                order += 1
-
-        elif editing_mode == EditingMode.VOICE_PIP.value:
-            # 1 个 background
-            clips.append(
-                EditPlanClip.create(
-                    plan_id=plan_id,
-                    clip_type="background",
-                    order=order,
-                    duration=_DEFAULT_CLIP_DURATION,
-                )
-            )
-            order += 1
-            # 1 个 corner_voice
-            clips.append(
-                EditPlanClip.create(
-                    plan_id=plan_id,
-                    clip_type="corner_voice",
-                    order=order,
-                    duration=_DEFAULT_CLIP_DURATION,
-                )
-            )
-            order += 1
-            # 剩余为 b_roll
-            for _ in range(2, n):
-                clips.append(
-                    EditPlanClip.create(
-                        plan_id=plan_id,
-                        clip_type="b_roll",
-                        order=order,
-                        duration=_DEFAULT_CLIP_DURATION,
-                    )
-                )
-                order += 1
-
-        else:
-            # ONE_TAKE: N 个 main clips
-            for _ in range(n):
-                clips.append(
-                    EditPlanClip.create(
-                        plan_id=plan_id,
-                        clip_type=ClipType.MAIN.value,
-                        order=order,
-                        duration=_DEFAULT_CLIP_DURATION,
-                    )
-                )
-                order += 1
-
-        return clips
+        return generate_default_clips(plan_id, editing_mode, asset_count)

    def _distribute_assets(
        self,
@@ -349,89 +200,8 @@ class PlanGeneratorService:
        asset_ids: List[str],
        editing_mode: str,
    ) -> None:
-        """按 editing_mode 将素材分配到 clips（就地修改，未持久化）
+        """按 editing_mode 将素材分配到 clips（就地修改，未持久化）.

-        分配策略:
-        - ONE_TAKE: 素材按顺序依次分配给 main 类型 clips
-        - PIP: 第1个素材→main(全屏背景)，其余→交替分配给 overlay clips
-        - VOICE_OVER: 素材→main clips (B-roll)
-        - VOICE_PIP: 第1个→background, 第2个→corner_voice, 其余→b_roll
+        委托给 plan_generator_utils.distribute_assets 纯函数。
        """
-        if not asset_ids or not clips:
-            return
-
-        if editing_mode == EditingMode.ONE_TAKE.value:
-            self._distribute_one_take(clips, asset_ids)
-        elif editing_mode == EditingMode.PIP.value:
-            self._distribute_pip(clips, asset_ids)
-        elif editing_mode == EditingMode.VOICE_OVER.value:
-            self._distribute_voice_over(clips, asset_ids)
-        elif editing_mode == EditingMode.VOICE_PIP.value:
-            self._distribute_voice_pip(clips, asset_ids)
-        else:
-            # 未知模式，退化为 one_take
-            self._distribute_one_take(clips, asset_ids)
-
-    def _distribute_one_take(
-        self,
-        clips: List[EditPlanClip],
-        asset_ids: List[str],
-    ) -> None:
-        """ONE_TAKE: 素材按顺序依次分配给 main 类型 clips"""
-        main_clips = [c for c in clips if c.clip_type == ClipType.MAIN.value]
-        for i, clip in enumerate(main_clips):
-            if i < len(asset_ids):
-                clip.assign_asset(asset_ids[i])
-
-    def _distribute_pip(
-        self,
-        clips: List[EditPlanClip],
-        asset_ids: List[str],
-    ) -> None:
-        """PIP: 第1个素材→main(全屏背景)，其余→overlay clips"""
-        # 第1个素材 → main clip
-        main_clips = [c for c in clips if c.clip_type == ClipType.MAIN.value]
-        if main_clips and asset_ids:
-            main_clips[0].assign_asset(asset_ids[0])
-
-        # 其余素材 → overlay clips
-        overlay_clips = [c for c in clips if c.clip_type == "overlay"]
-        remaining = asset_ids[1:]
-        for i, clip in enumerate(overlay_clips):
-            if i < len(remaining):
-                clip.assign_asset(remaining[i])
-
-    def _distribute_voice_over(
-        self,
-        clips: List[EditPlanClip],
-        asset_ids: List[str],
-    ) -> None:
-        """VOICE_OVER: 素材→main clips (B-roll)"""
-        main_clips = [c for c in clips if c.clip_type == ClipType.MAIN.value]
-        for i, clip in enumerate(main_clips):
-            if i < len(asset_ids):
-                clip.assign_asset(asset_ids[i])
-
-    def _distribute_voice_pip(
-        self,
-        clips: List[EditPlanClip],
-        asset_ids: List[str],
-    ) -> None:
-        """VOICE_PIP: 第1个→background, 第2个→corner_voice, 其余→b_roll"""
-        bg_clips = [c for c in clips if c.clip_type == "background"]
-        corner_clips = [c for c in clips if c.clip_type == "corner_voice"]
-        broll_clips = [c for c in clips if c.clip_type == "b_roll"]
-
-        # 第1个素材 → background
-        if bg_clips and len(asset_ids) > 0:
-            bg_clips[0].assign_asset(asset_ids[0])
-
-        # 第2个素材 → corner_voice
-        if corner_clips and len(asset_ids) > 1:
-            corner_clips[0].assign_asset(asset_ids[1])
-
-        # 其余素材 → b_roll
-        remaining = asset_ids[2:]
-        for i, clip in enumerate(broll_clips):
-            if i < len(remaining):
-                clip.assign_asset(remaining[i])
+        distribute_assets(clips, asset_ids, editing_mode)
@@ -0,0 +1,164 @@
+"""SmartAssetSelector — 智能素材选择服务.
+
+根据多维度评分从素材库中自动选择最优视频素材，
+用于一键生成等需要自动选取素材的场景。
+
+评分维度（加权求和，总分 0-1）：
+  - 质量分（quality_score）：权重 0.5 — 来自人工或AI的质量评分
+  - 分辨率适配：权重 0.2 — 分辨率越接近 1080p 得分越高
+  - 时长合理性：权重 0.2 — 3-30 秒区间最佳，过短/过长扣分
+  - 码率质量：权重 0.1 — 用文件大小/时长估算，码率适中得分高
+
+特性：
+  - 最低质量分门槛：自动过滤低质量素材
+  - 时长多样性：保证选出的素材时长分布均匀（短/中/长各占一定比例）
+  - 兼容全部模式：素材库模式和项目模式都可用
+
+纯逻辑部分已抽离到 packages.domain.asset_scoring。
+"""
+
+from __future__ import annotations
+
+import logging
+
+from packages.domain.asset_scoring import MEDIUM_BUCKET_MAX as _MEDIUM_BUCKET_MAX  # noqa: F401 - re-export for tests
+from packages.domain.asset_scoring import SHORT_BUCKET_MAX as _SHORT_BUCKET_MAX  # noqa: F401 - re-export for tests
+from packages.domain.asset_scoring import (
+    AssetScoreDetail,
+    SmartSelectResult,
+    diverse_selection,
+    filter_candidates,
+    score_asset_detail,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SmartAssetSelector:
+    """智能素材选择器.
+
+    从一组素材中按综合评分选择最优的 N 个，
+    同时保证时长分布的多样性。
+    """
+
+    def __init__(
+        self,
+        min_quality_score: float = 30.0,
+        target_width: int = 1920,
+        target_height: int = 1080,
+    ):
+        self.min_quality_score = min_quality_score
+        self.target_width = target_width
+        self.target_height = target_height
+
+    # ── 公开方法 ──────────────────────────────────────────────────────────────
+
+    def select(
+        self,
+        assets: list,
+        count: int = 0,
+        *,
+        ensure_diversity: bool = True,
+    ) -> SmartSelectResult:
+        """从素材列表中智能选择最优素材.
+
+        Args:
+            assets: Asset 实体列表（需要有 id/quality_score/width/height/duration/file_size 属性）
+            count: 选取数量，0 表示全部符合条件的
+            ensure_diversity: 是否保证时长多样性（默认开启）
+
+        Returns:
+            SmartSelectResult 选择结果
+        """
+        # 1. 过滤：只保留 ready 状态的视频素材 + 最低质量分门槛
+        candidates, filtered_out = filter_candidates(assets, self.min_quality_score)
+
+        if not candidates:
+            return SmartSelectResult(
+                selected_ids=[],
+                total_candidates=0,
+                filtered_out=filtered_out,
+                avg_score=0.0,
+                details=[],
+            )
+
+        # 2. 对每个候选素材评分
+        scored: list[AssetScoreDetail] = []
+        for asset in candidates:
+            detail = score_asset_detail(
+                asset_id=asset.id,
+                quality=getattr(asset, "quality_score", None),
+                width=getattr(asset, "width", None),
+                height=getattr(asset, "height", None),
+                duration=getattr(asset, "duration", None),
+                file_size=getattr(asset, "file_size", 0) or 0,
+                target_width=self.target_width,
+                target_height=self.target_height,
+            )
+            scored.append(detail)
+
+        # 3. 按总分降序排列
+        scored.sort(key=lambda d: d.total_score, reverse=True)
+
+        # 4. 多样性选择（如果需要且数量有限制）
+        if ensure_diversity and count > 0 and len(scored) > count:
+            selected = diverse_selection(scored, count)
+        else:
+            # 无数量限制或不要求多样性，直接按排名取
+            selected = scored if count <= 0 else scored[:count]
+
+        avg_score = sum(d.total_score for d in selected) / len(selected) if selected else 0.0
+
+        result = SmartSelectResult(
+            selected_ids=[d.asset_id for d in selected],
+            total_candidates=len(candidates),
+            filtered_out=filtered_out,
+            avg_score=avg_score,
+            details=selected,
+        )
+
+        logger.info(
+            "智能素材选择完成: 候选=%d, 过滤=%d, 选中=%d, 平均分=%.3f",
+            result.total_candidates,
+            result.filtered_out,
+            len(result.selected_ids),
+            result.avg_score,
+        )
+        return result
+
+    # ── 向后兼容：私有方法别名（委托给 asset_scoring 纯函数） ────────────────
+
+    def _score_asset(self, asset) -> AssetScoreDetail:
+        """对单个素材进行多维度评分（向后兼容）."""
+        return score_asset_detail(
+            asset_id=asset.id,
+            quality=getattr(asset, "quality_score", None),
+            width=getattr(asset, "width", None),
+            height=getattr(asset, "height", None),
+            duration=getattr(asset, "duration", None),
+            file_size=getattr(asset, "file_size", 0) or 0,
+            target_width=self.target_width,
+            target_height=self.target_height,
+        )
+
+    def _score_resolution(self, width: int | None, height: int | None) -> float:
+        """分辨率评分（向后兼容）."""
+        from packages.domain.asset_scoring import score_resolution
+
+        return score_resolution(width, height, self.target_width, self.target_height)
+
+    def _score_duration(self, duration: float | None) -> float:
+        """时长评分（向后兼容）."""
+        from packages.domain.asset_scoring import score_duration
+
+        return score_duration(duration)
+
+    def _score_bitrate(self, file_size: int, duration: float | None) -> float:
+        """码率评分（向后兼容）."""
+        from packages.domain.asset_scoring import score_bitrate
+
+        return score_bitrate(file_size, duration)
+
+    def _diverse_selection(self, scored: list[AssetScoreDetail], count: int) -> list[AssetScoreDetail]:
+        """多样性选择（向后兼容）."""
+        return diverse_selection(scored, count)
@@ -29,47 +29,33 @@ from packages.adapters.sqlalchemy_impl.edit_plan_repository import (
 )
 from packages.domain.edit_plan import EditPlanStatus
 from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
-from packages.domain.template_clip_config import TransitionEffect
+from packages.domain.video_filter_builder import (
+    DEFAULT_FPS,
+    DEFAULT_OUTPUT_HEIGHT,
+    DEFAULT_OUTPUT_WIDTH,
+    DEFAULT_TRANSITION_DURATION,
+    ClipFilterChain,
+    build_clip_filter,
+)
+from packages.domain.video_filter_builder import build_concat_filter as _build_concat_filter_func
+from packages.domain.video_filter_builder import build_filter_complex as _build_filter_complex
+from packages.domain.video_filter_builder import build_xfade_filter as _build_xfade_filter_func
+from packages.domain.video_filter_builder import chain_filters as _chain_filters_func
+from packages.domain.video_filter_builder import has_audio as _has_audio_func

 logger = logging.getLogger(__name__)

-# ── 常量 ──────────────────────────────────────────────────────────────────────
+# ── 常量（向后兼容别名） ──────────────────────────────────────────────────────
+# 实际定义已迁移至 packages/domain/video_filter_builder.py

-DEFAULT_OUTPUT_WIDTH = 1280
-DEFAULT_OUTPUT_HEIGHT = 720
-DEFAULT_FPS = 25
 DEFAULT_CODEC = "libx264"
 DEFAULT_CRF = 23
 DEFAULT_PRESET = "medium"

-# xfade 转场映射：TransitionEffect → FFmpeg xfade transition 名称
-_XFADE_TRANSITION_MAP: dict[str, str] = {
-    TransitionEffect.FADE: "fade",
-    TransitionEffect.SLIDE_LEFT: "slideleft",
-    TransitionEffect.SLIDE_RIGHT: "slideright",
-    TransitionEffect.DISSOLVE: "dissolve",
-    TransitionEffect.WIPE: "wipeleft",
-}
-
-# 转场默认时长（秒）
-DEFAULT_TRANSITION_DURATION = 0.5
-

 # ── 数据结构 ──────────────────────────────────────────────────────────────────


-@dataclass(frozen=True)
-class ClipFilterChain:
-    """单个片段的滤镜链描述。"""
-
-    clip_id: str
-    input_index: int
-    video_label: str
-    audio_label: str | None
-    filters: list[str]
-    duration: float
-
-
@dataclass(frozen=True)
 class ComposeCommand:
    """完整的 FFmpeg 合成命令描述。"""
@@ -401,62 +387,8 @@ class VideoComposeService:
        output_height: int,
        fps: int,
    ) -> ClipFilterChain:
-        """为单个片段构建滤镜链。
-
-        滤镜顺序：
-        1. scale — 等比缩放到目标分辨率（保证覆盖）
-        2. crop — 居中裁剪到目标分辨率
-        3. fps — 统一输出帧率（concat 要求所有输入帧率一致）
-        4. setpts — 重置时间戳 + 偏移
-        5. trim — 视频时长裁剪
-        6. atrim — 音频时长裁剪（如有音频流）
-        """
-        duration = clip.duration if clip.duration > 0 else 5.0  # 默认 5 秒
-        start = clip.start_time
-
-        filters: list[str] = []
-
-        # 1. scale: 等比缩放（保持比例，不裁剪）
-        filters.append(f"scale={output_width}:{output_height}" f":force_original_aspect_ratio=decrease")
-
-        # 2. pad: 居中+留黑边到目标分辨率（保持原始比例，不裁剪内容）
-        filters.append(f"pad={output_width}:{output_height}:(ow-iw)/2:(oh-ih)/2:black")
-
-        # 3. format: 统一像素格式为 yuv420p（H.264 标准格式，concat 要求所有输入像素格式一致）
-        # 不同素材可能是 yuv420p / yuv422p / yuv444p / nv12 等，必须统一
-        filters.append("format=yuv420p")
-
-        # 4. fps: 统一帧率（concat 要求所有输入帧率一致）
-        # 放在 pad 之后、setpts 之前，确保分辨率和帧率都已统一
-        if fps and fps > 0:
-            filters.append(f"fps={fps}")
-
-        # 3. setpts: 重置时间戳
-        if start > 0:
-            filters.append(f"setpts=PTS-STARTPTS+{start}/TB")
-        else:
-            filters.append("setpts=PTS-STARTPTS")
-
-        # 4. trim: 视频时长
-        filters.append(f"trim=0:{duration}")
-        filters.append("setpts=PTS-STARTPTS")  # trim 后需要重置 PTS
-
-        video_label = f"v{input_index}"
-
-        # 5. 音频标签：仅当片段类型可能有音频时才设置
-        # title/subtitle 是纯文字/图片卡片，没有音频流
-        clip_type = clip.clip_type.lower() if clip.clip_type else ""
-        has_audio_stream = clip_type not in ("title", "subtitle")
-        audio_label = f"a{input_index}" if has_audio_stream else None
-
-        return ClipFilterChain(
-            clip_id=clip.id,
-            input_index=input_index,
-            video_label=video_label,
-            audio_label=audio_label,
-            filters=filters,
-            duration=duration,
-        )
+        """向后兼容：委托给 video_filter_builder.build_clip_filter。"""
+        return build_clip_filter(clip, input_index, output_width, output_height, fps)

    @staticmethod
    def _build_filter_complex(
@@ -466,102 +398,30 @@ class VideoComposeService:
        transition_duration: float,
        transitions: list[str],
    ) -> tuple[str, float]:
-        """构建完整的 filter_complex 字符串。
-
-        策略：
-        - 单片段：直接输出
-        - 多片段 + 全 cut：使用 concat 滤镜（高效）
-        - 多片段 + 有转场：使用 xfade 滤镜链
-
-        返回 (filter_complex_string, estimated_total_duration)。
-        """
-        n = len(clip_chains)
-
-        if n == 0:
-            return "", 0.0
-
-        # ── 单片段 ─────────────────────────────────────────────────────
-        if n == 1:
-            chain = clip_chains[0]
-            filter_str = _chain_filters(chain.filters, chain.video_label)
-            # 音频
-            if chain.audio_label:
-                filter_str += f";[0:a]{chain.audio_label}"
-            total_duration = chain.duration
-            return filter_str, total_duration
-
-        # ── 检查是否有转场 ─────────────────────────────────────────────
-        has_transitions = any(t != TransitionEffect.CUT and t != "cut" for t in transitions)
-
-        if not has_transitions:
-            return _build_concat_filter(clip_chains)
-
-        # ── 有转场：使用 xfade ─────────────────────────────────────────
-        return _build_xfade_filter(
-            clip_chains=clip_chains,
-            transition_duration=transition_duration,
-            transitions=transitions,
-        )
+        """向后兼容：委托给 video_filter_builder.build_filter_complex。"""
+        return _build_filter_complex(clip_chains, output_width, output_height, transition_duration, transitions)

    @staticmethod
    def _has_audio(clip_chains: list[ClipFilterChain]) -> bool:
-        """是否有任何片段包含音频流。"""
-        return any(c.audio_label is not None for c in clip_chains)
+        """向后兼容：委托给 video_filter_builder.has_audio。"""
+        return _has_audio_func(clip_chains)


-# ── 模块级辅助函数 ────────────────────────────────────────────────────────────
+# ── 模块级辅助函数（向后兼容别名） ──────────────────────────────────────────
+# 实际实现已迁移至 packages/domain/video_filter_builder.py
+# 保留此处别名以兼容现有测试与调用方


 def _chain_filters(filters: list[str], output_label: str) -> str:
-    """将滤镜列表串联为 FFmpeg 滤镜字符串。"""
-    filter_body = ",".join(filters)
-    return f"[0:v]{filter_body}[{output_label}]"
+    """向后兼容：委托给 video_filter_builder.chain_filters。"""
+    return _chain_filters_func(filters, output_label)


 def _build_concat_filter(
    clip_chains: list[ClipFilterChain],
 ) -> tuple[str, float]:
-    """构建 concat 滤镜（无转场，高效拼接）。
-
-    格式：
-    [0:v]filters[v0]; [1:v]filters[v1]; ...
-    [v0][v1]...[vN]concat=n=N:v=1:a=0[outv]
-    """
-    n = len(clip_chains)
-    parts: list[str] = []
-    total_duration = 0.0
-
-    # 每个片段的滤镜链
-    for idx, chain in enumerate(clip_chains):
-        filter_body = ",".join(chain.filters)
-        parts.append(f"[{idx}:v]{filter_body}[{chain.video_label}]")
-        total_duration += chain.duration
-
-    # concat 滤镜
-    concat_inputs = "".join(f"[{c.video_label}]" for c in clip_chains)
-    concat_filter = f"{concat_inputs}concat=n={n}:v=1:a=0[outv]"
-    parts.append(concat_filter)
-
-    # 音频 concat（如果有）— 先统一音频格式再拼接，否则不同采样率/声道会导致concat失败
-    audio_parts: list[str] = []
-    for idx, chain in enumerate(clip_chains):
-        if chain.audio_label:
-            # aformat: 统一采样率48000Hz + 双声道stereo + fltp采样格式（AAC标准格式）
-            audio_filters = [
-                "aformat=sample_rates=48000:channel_layouts=stereo:sample_fmts=fltp",
-                f"atrim=0:{chain.duration}",
-                "asetpts=PTS-STARTPTS",
-            ]
-            audio_parts.append(f"[{idx}:a]{','.join(audio_filters)}[{chain.audio_label}]")
-
-    if audio_parts:
-        parts.extend(audio_parts)
-        audio_inputs = "".join(f"[{c.audio_label}]" for c in clip_chains if c.audio_label)
-        audio_count = sum(1 for c in clip_chains if c.audio_label)
-        if audio_count > 0:
-            parts.append(f"{audio_inputs}concat=n={audio_count}:v=0:a=1[outa]")
-
-    return ";".join(parts), total_duration
+    """向后兼容：委托给 video_filter_builder.build_concat_filter。"""
+    return _build_concat_filter_func(clip_chains)


 def _build_xfade_filter(
@@ -569,80 +429,5 @@ def _build_xfade_filter(
    transition_duration: float,
    transitions: list[str],
 ) -> tuple[str, float]:
-    """构建 xfade 转场滤镜链。
-
-    每两个相邻片段之间插入 xfade 转场。
-    offset = 前一个片段的累积时长 - 转场时长。
-
-    格式（2 片段）：
-    [0:v]filters[v0]; [1:v]filters[v1];
-    [v0][v1]xfade=transition=fade:duration=0.5:offset=4.5[outv]
-
-    格式（3+ 片段）：
-    [v0][v1]xfade=...[tmp1]; [tmp1][v2]xfade=...[outv]
-    """
-    n = len(clip_chains)
-    parts: list[str] = []
-    total_duration = 0.0
-
-    # 每个片段的滤镜链
-    for idx, chain in enumerate(clip_chains):
-        filter_body = ",".join(chain.filters)
-        parts.append(f"[{idx}:v]{filter_body}[{chain.video_label}]")
-        total_duration += chain.duration
-
-    # xfade 链
-    if n == 1:
-        # 单片段不需要 xfade
-        parts.append(f"[{clip_chains[0].video_label}]copy[outv]")
-        return ";".join(parts), total_duration
-
-    # 计算每个转场的 offset
-    cumulative = 0.0
-    prev_label = clip_chains[0].video_label
-
-    for i in range(1, n):
-        cumulative += clip_chains[i - 1].duration
-        offset = max(0.0, cumulative - transition_duration * i)
-
-        # 获取转场类型
-        transition = transitions[i] if i < len(transitions) else "cut"
-        xfade_transition = _XFADE_TRANSITION_MAP.get(transition, "fade")
-
-        if i == n - 1:
-            # 最后一个转场，输出到 [outv]
-            out_label = "outv"
-        else:
-            out_label = f"xf{i}"
-
-        parts.append(
-            f"[{prev_label}][{clip_chains[i].video_label}]"
-            f"xfade=transition={xfade_transition}"
-            f":duration={transition_duration}"
-            f":offset={offset:.3f}"
-            f"[{out_label}]"
-        )
-        prev_label = out_label
-
-    # 总时长需要减去转场重叠部分
-    total_duration -= transition_duration * (n - 1)
-
-    # 音频：先 aformat 归一化再 concat（不同采样率/声道/采样格式会导致concat失败）
-    audio_chains_with_label = [(c, c.audio_label) for c in clip_chains if c.audio_label]
-    if len(audio_chains_with_label) >= 2:
-        normalized_audio_labels: list[str] = []
-        for chain, _ in audio_chains_with_label:
-            norm_label = f"anorm_{chain.video_label}"
-            audio_filters = [
-                "aformat=sample_rates=48000:channel_layouts=stereo:sample_fmts=fltp",
-                f"atrim=0:{chain.duration}",
-                "asetpts=PTS-STARTPTS",
-            ]
-            parts.append(f"[{chain.audio_label}]{','.join(audio_filters)}[{norm_label}]")
-            normalized_audio_labels.append(norm_label)
-        audio_inputs = "".join(f"[{label}]" for label in normalized_audio_labels)
-        parts.append(f"{audio_inputs}concat=n={len(normalized_audio_labels)}:v=0:a=1[outa]")
-    elif len(audio_chains_with_label) == 1:
-        parts.append(f"[{audio_chains_with_label[0][0].audio_label}]acopy[outa]")
-
-    return ";".join(parts), max(0.0, total_duration)
+    """向后兼容：委托给 video_filter_builder.build_xfade_filter。"""
+    return _build_xfade_filter_func(clip_chains, transition_duration, transitions)
@@ -1,8 +0,0 @@
-from fastapi import APIRouter
-
-router = APIRouter()
-
-
-@router.get("/health")
-def health():
-    return {"ok": True, "service": "api"}
@@ -1,443 +0,0 @@
-/**
- * 素材相关 API
- * Phase 1 重构：去掉 project_id，素材直接归属用户
- */
-import apiClient from "./client"
-import { getOrCreateDefaultProject } from "./projects"
-
-/** 素材元数据 */
-export interface AssetMetadata {
-  /** 时长（秒） */
-  duration?: number
-  /** 宽度（像素） */
-  width?: number
-  /** 高度（像素） */
-  height?: number
-  /** 比特率（bps） */
-  bitrate?: number
-  /** 编码格式 */
-  codec?: string
-  /** 帧率 */
-  fps?: number
-  /** 采样率（Hz） */
-  sample_rate?: number
-  /** 声道数 */
-  channels?: number
-  /** 其他扩展字段 */
-  [key: string]: unknown
-}
-
-/** 素材分类状态 */
-export type AssetClassificationStatus = "pending" | "processing" | "completed" | "failed"
-
-/** 素材条目 */
-export interface AssetItem {
-  id: string
-  library_id: string
-  name: string
-  storage_key: string
-  mime_type: string
-  metadata: AssetMetadata
-  file_size?: number
-  file_url?: string
-  thumbnail_url?: string
-  /** 时长（秒），视频/音频素材由后端从 metadata 提取到顶层 */
-  duration?: number
-  status?: string
-  classification_status?: AssetClassificationStatus | null
-  quality_score?: number | null
-  tag_ids?: string[]
-  created_at?: string
-}
-
-/** 素材库 */
-export interface AssetLibraryItem {
-  id: string
-  name: string
-  kind: "video" | "voice" | "image"
-  asset_count?: number
-  total_size?: number
-  created_at?: string
-}
-
-/** 入库任务 */
-export interface IngestJob {
-  id: string
-  library_id: string
-  storage_key: string
-  status: "pending" | "processing" | "completed" | "failed"
-  error_message: string
-  result_asset_id: string
-}
-
-/** 分类任务 */
-export interface ClassificationJob {
-  id: string
-  asset_id: string
-  status: "pending" | "processing" | "completed" | "failed"
-  classification: string
-  confidence: number
-  error_message: string
-}
-
-/** 素材诊断信息 */
-export interface AssetDiagnosis {
-  readiness_score: number
-  readiness_label: string
-  total_assets: number
-  ready_assets: number
-  video_assets: number
-  image_assets: number
-  voice_assets: number
-  total_duration_seconds: number
-  estimated_video_count: number
-  used_assets: number
-  unused_assets: number
-  pending_review_assets: number
-  smart_views: Array<{
-    key: string
-    label: string
-    count: number
-    description: string
-  }>
-  gaps: Array<{
-    key: string
-    severity: "critical" | "warning" | "info"
-    message: string
-    recommendation: string
-  }>
-}
-
-// ─── 素材诊断 ──────────────────────────────────────────────
-
-/** 获取素材诊断信息（可选 asset_id 查单素材，否则全局诊断） */
-export const getAssetDiagnosis = async (assetId?: string): Promise<AssetDiagnosis> => {
-  const params: Record<string, string> = {}
-  if (assetId) params.asset_id = assetId
-  const response = await apiClient.get("/asset-diagnosis", { params })
-  return response.data
-}
-
-// ─── 素材库 ────────────────────────────────────────────────
-
-/** 获取当前用户的所有素材库 */
-export const getAssetLibraries = async (): Promise<AssetLibraryItem[]> => {
-  const response = await apiClient.get("/asset-libraries")
-  return response.data.items || []
-}
-
-/** 创建素材库（自动获取或创建默认项目以提供 project_id） */
-export const createAssetLibrary = async (data: {
-  name: string
-  kind: "video" | "voice" | "image"
-}): Promise<AssetLibraryItem> => {
-  // 后端要求 project_id，前端自动管理默认项目
-  const project = await getOrCreateDefaultProject()
-  const response = await apiClient.post("/asset-libraries", {
-    project_id: project.id,
-    ...data,
-  })
-  return response.data
-}
-
-/** 确保项目下指定 kind 的默认素材库存在（不存在则自动创建） */
-export const ensureDefaultLibrary = async (data: {
-  project_id: string
-  kind: "video" | "voice" | "image"
-}): Promise<AssetLibraryItem> => {
-  const response = await apiClient.post("/asset-libraries/ensure-default", data)
-  return response.data
-}
-
-/** 删除素材库 */
-export const deleteAssetLibrary = async (libraryId: string): Promise<void> => {
-  await apiClient.delete(`/asset-libraries/${libraryId}`)
-}
-
-// ─── 素材 ──────────────────────────────────────────────────
-
-/** 获取素材库下的所有素材 */
-export const getAssets = async (
-  libraryId: string,
-  options?: { status?: string; page?: number; page_size?: number },
-): Promise<{ items: AssetItem[]; total: number }> => {
-  const params: Record<string, string | number> = { library_id: libraryId }
-  // 默认拉取所有非删除状态的素材（ready/ingesting/processing/uploading/error/failed）
-  // 让用户能看到"处理中"的素材，不会以为上传失败了
-  if (options?.status) {
-    params.status = options.status
-  }
-  if (options?.page) params.page = options.page
-  if (options?.page_size) params.page_size = options.page_size
-  const response = await apiClient.get("/assets", { params })
-  const data = response.data || {}
-  const items: AssetItem[] = data.items || []
-  const total: number = typeof data.total === "number" ? data.total : items.length
-  return { items, total }
-}
-
-/** 按类型获取素材（如 voice/video/image），支持可选筛选 */
-export const getAssetsByKind = async (
-  kind: string,
-  filters?: {
-    keyword?: string
-    gender?: string
-    style?: string
-    tag_ids?: string[]
-    limit?: number
-    page?: number
-    page_size?: number
-  },
-): Promise<AssetItem[]> => {
-  const params: Record<string, string | number> = { kind }
-  if (filters?.keyword) params.keyword = filters.keyword
-  if (filters?.gender) params.gender = filters.gender
-  if (filters?.style) params.style = filters.style
-  if (filters?.tag_ids?.length) params.tag_ids = filters.tag_ids.join(",")
-  if (filters?.limit) params.limit = filters.limit
-  if (filters?.page) params.page = filters.page
-  if (filters?.page_size) params.page_size = filters.page_size
-  const response = await apiClient.get("/assets", { params })
-  return response.data.items || []
-}
-
-/** 创建素材（上传文件后调用，附带 metadata） */
-export const createAsset = async (data: {
-  library_id: string
-  name: string
-  storage_key: string
-  mime_type: string
-  metadata?: AssetMetadata
-}): Promise<AssetItem> => {
-  const response = await apiClient.post("/assets", data)
-  return response.data
-}
-
-/** 更新素材（名称、metadata 等） */
-export const updateAsset = async (
-  assetId: string,
-  data: { name?: string; metadata?: AssetMetadata },
-): Promise<AssetItem> => {
-  const response = await apiClient.put(`/assets/${assetId}`, data)
-  return response.data
-}
-
-/** 更新素材审核状态 */
-export const updateAssetReviewStatus = async (
-  assetId: string,
-  reviewStatus: "pending_review" | "approved" | "rejected",
-): Promise<AssetItem> => {
-  const response = await apiClient.patch(`/assets/${assetId}/review`, {
-    review_status: reviewStatus,
-  })
-  return response.data
-}
-
-/** 删除素材 */
-export const deleteAsset = async (assetId: string): Promise<void> => {
-  await apiClient.delete(`/assets/${assetId}`)
-}
-
-// ─── 上传 ──────────────────────────────────────────────────
-
-/** 表单上传素材（小文件） */
-export const uploadAsset = async (
-  formData: FormData,
-): Promise<{ storage_key: string; ingest_job_id: string; url: string }> => {
-  const response = await apiClient.post("/upload", formData, {
-    headers: { "Content-Type": "multipart/form-data" },
-    timeout: 30 * 60 * 1000,
-  })
-  return response.data
-}
-
-/** 预签名直传准备 */
-export const prepareDirectUpload = async (data: {
-  project_id: string
-  library_id: string
-  filename: string
-  content_type: string
-  file_size: number
-}): Promise<{
-  upload_url: string
-  method: string
-  storage_key: string
-  expires_at: string
-  fields: Record<string, string>
-  max_size_bytes: number
-}> => {
-  const response = await apiClient.post("/upload/direct/prepare", data)
-  return response.data
-}
-
-/** 直传完成确认 */
-export const completeDirectUpload = async (data: {
-  project_id: string
-  library_id: string
-  storage_key: string
-}): Promise<{ storage_key: string; ingest_job_id: string }> => {
-  const response = await apiClient.post("/upload/direct/complete", data)
-  return response.data
-}
-
-/** 直传上传（大文件推荐），支持可选进度回调 */
-export const uploadAssetDirect = async (data: {
-  file: File
-  library_id: string
-  onProgress?: (percent: number) => void
-}): Promise<{ storage_key: string; ingest_job_id: string }> => {
-  // 后端要求 project_id，前端自动获取默认项目
-  const project = await getOrCreateDefaultProject()
-
-  const prepared = await prepareDirectUpload({
-    project_id: project.id,
-    library_id: data.library_id,
-    filename: data.file.name,
-    content_type: data.file.type || "application/octet-stream",
-    file_size: data.file.size,
-  })
-
-  const directForm = new FormData()
-  Object.entries(prepared.fields).forEach(([key, value]) => directForm.append(key, value))
-  directForm.append("file", data.file)
-
-  // 使用 XMLHttpRequest 以获取上传进度 + 超时控制 + 详细错误诊断
-  await new Promise<void>((resolve, reject) => {
-    const xhr = new XMLHttpRequest()
-    xhr.open(prepared.method, prepared.upload_url)
-
-    // 超时 10 分钟
-    xhr.timeout = 10 * 60 * 1000
-
-    xhr.upload.onprogress = (e) => {
-      if (e.lengthComputable && data.onProgress) {
-        data.onProgress(Math.round((e.loaded / e.total) * 100))
-      }
-    }
-    xhr.onload = () => {
-      if (xhr.status >= 200 && xhr.status < 300) {
-        resolve()
-      } else {
-        // 解析 OSS 返回的 XML 错误信息
-        let ossError = ""
-        try {
-          const codeMatch = xhr.responseText.match(/<Code>([^<]+)<\/Code>/)
-          const msgMatch = xhr.responseText.match(/<Message>([^<]+)<\/Message>/)
-          if (codeMatch || msgMatch) {
-            ossError = ` [OSS: ${codeMatch?.[1] || "unknown"} - ${msgMatch?.[1] || "unknown"}]`
-          }
-        } catch {
-          // 无法解析响应体
-        }
-        const detail = `OSS 直传失败: HTTP ${xhr.status} ${xhr.statusText}${ossError}`
-        console.error("[OSS Upload] 直传失败:", {
-          url: prepared.upload_url,
-          storage_key: prepared.storage_key,
-          status: xhr.status,
-          statusText: xhr.statusText,
-        })
-        reject(new Error(detail))
-      }
-    }
-    xhr.onerror = () => {
-      console.error("[OSS Upload] 网络错误:", {
-        url: prepared.upload_url,
-        storage_key: prepared.storage_key,
-      })
-      reject(new Error("OSS 上传网络错误，请检查网络连接"))
-    }
-    xhr.ontimeout = () => {
-      console.error("[OSS Upload] 上传超时:", {
-        url: prepared.upload_url,
-        storage_key: prepared.storage_key,
-      })
-      reject(new Error("OSS 上传超时（10分钟），请检查网络或尝试更小的文件"))
-    }
-    xhr.send(directForm)
-  })
-
-  return completeDirectUpload({
-    project_id: project.id,
-    library_id: data.library_id,
-    storage_key: prepared.storage_key,
-  })
-}
-
-// ─── 入库 / 分类任务 ───────────────────────────────────────
-
-/** 查询入库任务状态 */
-export const getIngestJob = async (jobId: string): Promise<IngestJob> => {
-  const response = await apiClient.get(`/ingest-jobs/${jobId}`)
-  return response.data
-}
-
-/** 提交素材分类任务 */
-export const submitClassificationJob = async (data: {
-  asset_id: string
-}): Promise<ClassificationJob> => {
-  const response = await apiClient.post("/classification-jobs", data)
-  return response.data
-}
-
-/** 查询分类任务状态 */
-export const getClassificationJob = async (jobId: string): Promise<ClassificationJob> => {
-  const response = await apiClient.get(`/classification-jobs/${jobId}`)
-  return response.data
-}
-
-// ─── 批量操作 ───────────────────────────────────────────────
-
-/** 批量操作结果 */
-export interface BatchOperationResult {
-  succeeded: string[]
-  failed: string[]
-  total: number
-  success_count: number
-  failure_count: number
-}
-
-/** 统一批量操作结果归一化，防御后端字段缺失或格式不一致 */
-const normalizeBatchResult = (raw: Record<string, unknown>): BatchOperationResult => {
-  const succeeded = Array.isArray(raw.succeeded) ? (raw.succeeded as string[]) : []
-  const failed = Array.isArray(raw.failed) ? (raw.failed as string[]) : []
-  const success_count = typeof raw.success_count === "number" ? raw.success_count : succeeded.length
-  const failure_count = typeof raw.failure_count === "number" ? raw.failure_count : failed.length
-  const total = typeof raw.total === "number" ? raw.total : success_count + failure_count
-  return { succeeded, failed, total, success_count, failure_count }
-}
-
-/** 批量删除素材 */
-export const batchDeleteAssets = async (assetIds: string[]): Promise<BatchOperationResult> => {
-  const response = await apiClient.post("/assets/batch-delete", {
-    asset_ids: assetIds,
-  })
-  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
-}
-
-/** 批量打标签 */
-export const batchTagAssets = async (data: {
-  asset_ids: string[]
-  tags: string[]
-  mode: "add" | "replace"
-}): Promise<BatchOperationResult> => {
-  const response = await apiClient.post("/assets/batch-tag", data)
-  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
-}
-
-/** 批量改分类 */
-export const batchClassifyAssets = async (data: {
-  asset_ids: string[]
-  category: string
-}): Promise<BatchOperationResult> => {
-  const response = await apiClient.post("/assets/batch-classify", data)
-  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
-}
-
-/** 批量智能标记 */
-export const batchMarkAssets = async (data: {
-  asset_ids: string[]
-  smart_view: "recommended" | "caution" | "high_risk"
-}): Promise<BatchOperationResult> => {
-  const response = await apiClient.post("/assets/batch-mark", data)
-  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
-}
@@ -0,0 +1,87 @@
+/**
+ * 素材 CRUD API
+ */
+import apiClient from "../client"
+import type { AssetItem, AssetMetadata } from "./types"
+
+/** 获取素材库下的所有素材 */
+export const getAssets = async (
+  libraryId: string,
+  options?: {
+    status?: string
+    page?: number
+    page_size?: number
+  },
+): Promise<{ items: AssetItem[]; total: number }> => {
+  const params: Record<string, string | number> = { library_id: libraryId }
+  if (options?.status) params.status = options.status
+  if (options?.page) params.page = options.page
+  if (options?.page_size) params.page_size = options.page_size
+  const response = await apiClient.get("/assets", { params })
+  const data = response.data || {}
+  const items: AssetItem[] = data.items || []
+  const total: number = typeof data.total === "number" ? data.total : items.length
+  return { items, total }
+}
+
+/** 按类型获取素材（如 voice/video/image），支持可选筛选 */
+export const getAssetsByKind = async (
+  kind: string,
+  filters?: {
+    keyword?: string
+    gender?: string
+    style?: string
+    tag_ids?: string[]
+    limit?: number
+    page?: number
+    page_size?: number
+  },
+): Promise<AssetItem[]> => {
+  const params: Record<string, string | number> = { kind }
+  if (filters?.keyword) params.keyword = filters.keyword
+  if (filters?.gender) params.gender = filters.gender
+  if (filters?.style) params.style = filters.style
+  if (filters?.tag_ids?.length) params.tag_ids = filters.tag_ids.join(",")
+  if (filters?.limit) params.limit = filters.limit
+  if (filters?.page) params.page = filters.page
+  if (filters?.page_size) params.page_size = filters.page_size
+  const response = await apiClient.get("/assets", { params })
+  return response.data.items || []
+}
+
+/** 创建素材（上传文件后调用，附带 metadata） */
+export const createAsset = async (data: {
+  library_id: string
+  name: string
+  storage_key: string
+  mime_type: string
+  metadata?: AssetMetadata
+}): Promise<AssetItem> => {
+  const response = await apiClient.post("/assets", data)
+  return response.data
+}
+
+/** 更新素材（名称、metadata 等） */
+export const updateAsset = async (
+  assetId: string,
+  data: { name?: string; metadata?: AssetMetadata },
+): Promise<AssetItem> => {
+  const response = await apiClient.put(`/assets/${assetId}`, data)
+  return response.data
+}
+
+/** 更新素材审核状态 */
+export const updateAssetReviewStatus = async (
+  assetId: string,
+  reviewStatus: "pending_review" | "approved" | "rejected",
+): Promise<AssetItem> => {
+  const response = await apiClient.patch(`/assets/${assetId}/review`, {
+    review_status: reviewStatus,
+  })
+  return response.data
+}
+
+/** 删除素材 */
+export const deleteAsset = async (assetId: string): Promise<void> => {
+  await apiClient.delete(`/assets/${assetId}`)
+}
@@ -0,0 +1,51 @@
+/**
+ * 素材批量操作 API
+ */
+import apiClient from "../client"
+import type { BatchOperationResult } from "./types"
+
+/** 统一批量操作结果归一化，防御后端字段缺失或格式不一致 */
+export const normalizeBatchResult = (raw: Record<string, unknown>): BatchOperationResult => {
+  const succeeded = Array.isArray(raw.succeeded) ? (raw.succeeded as string[]) : []
+  const failed = Array.isArray(raw.failed) ? (raw.failed as string[]) : []
+  const success_count = typeof raw.success_count === "number" ? raw.success_count : succeeded.length
+  const failure_count = typeof raw.failure_count === "number" ? raw.failure_count : failed.length
+  const total = typeof raw.total === "number" ? raw.total : success_count + failure_count
+  return { succeeded, failed, total, success_count, failure_count }
+}
+
+/** 批量删除素材 */
+export const batchDeleteAssets = async (assetIds: string[]): Promise<BatchOperationResult> => {
+  const response = await apiClient.post("/assets/batch-delete", {
+    asset_ids: assetIds,
+  })
+  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
+}
+
+/** 批量打标签 */
+export const batchTagAssets = async (data: {
+  asset_ids: string[]
+  tags: string[]
+  mode: "add" | "replace"
+}): Promise<BatchOperationResult> => {
+  const response = await apiClient.post("/assets/batch-tag", data)
+  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
+}
+
+/** 批量改分类 */
+export const batchClassifyAssets = async (data: {
+  asset_ids: string[]
+  category: string
+}): Promise<BatchOperationResult> => {
+  const response = await apiClient.post("/assets/batch-classify", data)
+  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
+}
+
+/** 批量智能标记 */
+export const batchMarkAssets = async (data: {
+  asset_ids: string[]
+  smart_view: "recommended" | "caution" | "high_risk"
+}): Promise<BatchOperationResult> => {
+  const response = await apiClient.post("/assets/batch-mark", data)
+  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
+}
@@ -0,0 +1,13 @@
+/**
+ * 素材诊断 API
+ */
+import apiClient from "../client"
+import type { AssetDiagnosis } from "./types"
+
+/** 获取素材诊断信息（可选 asset_id 查单素材，否则全局诊断） */
+export const getAssetDiagnosis = async (assetId?: string): Promise<AssetDiagnosis> => {
+  const params: Record<string, string> = {}
+  if (assetId) params.asset_id = assetId
+  const response = await apiClient.get("/asset-diagnosis", { params })
+  return response.data
+}
@@ -0,0 +1,55 @@
+/**
+ * 素材相关 API — 按模块拆分后的统一入口
+ * 保持与原 assets.ts 相同的导出结构，向后兼容
+ */
+
+// 类型
+export type {
+  AssetMetadata,
+  AssetClassificationStatus,
+  AssetItem,
+  AssetLibraryItem,
+  IngestJob,
+  ClassificationJob,
+  AssetDiagnosis,
+  BatchOperationResult,
+  UploadResult,
+  DirectUploadPrepareResult,
+  DirectUploadCompleteResult,
+} from "./types"
+
+// 素材诊断
+export { getAssetDiagnosis } from "./diagnosis"
+
+// 素材库
+export {
+  getAssetLibraries,
+  createAssetLibrary,
+  ensureDefaultLibrary,
+  deleteAssetLibrary,
+} from "./libraries"
+
+// 素材 CRUD
+export {
+  getAssets,
+  getAssetsByKind,
+  createAsset,
+  updateAsset,
+  updateAssetReviewStatus,
+  deleteAsset,
+} from "./assets"
+
+// 上传
+export { uploadAsset, prepareDirectUpload, completeDirectUpload, uploadAssetDirect } from "./upload"
+
+// 任务
+export { getIngestJob, submitClassificationJob, getClassificationJob } from "./jobs"
+
+// 批量操作
+export {
+  normalizeBatchResult,
+  batchDeleteAssets,
+  batchTagAssets,
+  batchClassifyAssets,
+  batchMarkAssets,
+} from "./batch"
@@ -0,0 +1,25 @@
+/**
+ * 入库任务 & 分类任务 API
+ */
+import apiClient from "../client"
+import type { IngestJob, ClassificationJob } from "./types"
+
+/** 查询入库任务状态 */
+export const getIngestJob = async (jobId: string): Promise<IngestJob> => {
+  const response = await apiClient.get(`/ingest-jobs/${jobId}`)
+  return response.data
+}
+
+/** 提交素材分类任务 */
+export const submitClassificationJob = async (data: {
+  asset_id: string
+}): Promise<ClassificationJob> => {
+  const response = await apiClient.post("/classification-jobs", data)
+  return response.data
+}
+
+/** 查询分类任务状态 */
+export const getClassificationJob = async (jobId: string): Promise<ClassificationJob> => {
+  const response = await apiClient.get(`/classification-jobs/${jobId}`)
+  return response.data
+}
@@ -0,0 +1,39 @@
+/**
+ * 素材库 API
+ */
+import apiClient from "../client"
+import { getOrCreateDefaultProject } from "../projects"
+import type { AssetLibraryItem } from "./types"
+
+/** 获取当前用户的所有素材库 */
+export const getAssetLibraries = async (): Promise<AssetLibraryItem[]> => {
+  const response = await apiClient.get("/asset-libraries")
+  return response.data.items || []
+}
+
+/** 创建素材库（自动获取或创建默认项目以提供 project_id） */
+export const createAssetLibrary = async (data: {
+  name: string
+  kind: "video" | "voice" | "image"
+}): Promise<AssetLibraryItem> => {
+  const project = await getOrCreateDefaultProject()
+  const response = await apiClient.post("/asset-libraries", {
+    project_id: project.id,
+    ...data,
+  })
+  return response.data
+}
+
+/** 确保项目下指定 kind 的默认素材库存在 */
+export const ensureDefaultLibrary = async (data: {
+  project_id: string
+  kind: "video" | "voice" | "image"
+}): Promise<AssetLibraryItem> => {
+  const response = await apiClient.post("/asset-libraries/ensure-default", data)
+  return response.data
+}
+
+/** 删除素材库 */
+export const deleteAssetLibrary = async (libraryId: string): Promise<void> => {
+  await apiClient.delete(`/asset-libraries/${libraryId}`)
+}
@@ -0,0 +1,138 @@
+/**
+ * 素材相关类型定义
+ */
+
+/** 素材元数据 */
+export interface AssetMetadata {
+  /** 时长（秒） */
+  duration?: number
+  /** 宽度（像素） */
+  width?: number
+  /** 高度（像素） */
+  height?: number
+  /** 比特率（bps） */
+  bitrate?: number
+  /** 编码格式 */
+  codec?: string
+  /** 帧率 */
+  fps?: number
+  /** 采样率（Hz） */
+  sample_rate?: number
+  /** 声道数 */
+  channels?: number
+  /** 其他扩展字段 */
+  [key: string]: unknown
+}
+
+/** 素材分类状态 */
+export type AssetClassificationStatus = "pending" | "processing" | "completed" | "failed"
+
+/** 素材条目 */
+export interface AssetItem {
+  id: string
+  library_id: string
+  name: string
+  storage_key: string
+  mime_type: string
+  metadata: AssetMetadata
+  file_size?: number
+  file_url?: string
+  thumbnail_url?: string
+  /** 时长（秒），视频/音频素材由后端从 metadata 提取到顶层 */
+  duration?: number
+  status?: string
+  classification_status?: AssetClassificationStatus | null
+  quality_score?: number | null
+  tag_ids?: string[]
+  created_at?: string
+}
+
+/** 素材库 */
+export interface AssetLibraryItem {
+  id: string
+  name: string
+  kind: "video" | "voice" | "image"
+  asset_count?: number
+  total_size?: number
+  created_at?: string
+}
+
+/** 入库任务 */
+export interface IngestJob {
+  id: string
+  library_id: string
+  storage_key: string
+  status: "pending" | "processing" | "completed" | "failed"
+  error_message: string
+  result_asset_id: string
+}
+
+/** 分类任务 */
+export interface ClassificationJob {
+  id: string
+  asset_id: string
+  status: "pending" | "processing" | "completed" | "failed"
+  classification: string
+  confidence: number
+  error_message: string
+}
+
+/** 素材诊断信息 */
+export interface AssetDiagnosis {
+  readiness_score: number
+  readiness_label: string
+  total_assets: number
+  ready_assets: number
+  video_assets: number
+  image_assets: number
+  voice_assets: number
+  total_duration_seconds: number
+  estimated_video_count: number
+  used_assets: number
+  unused_assets: number
+  pending_review_assets: number
+  smart_views: Array<{
+    key: string
+    label: string
+    count: number
+    description: string
+  }>
+  gaps: Array<{
+    key: string
+    severity: "critical" | "warning" | "info"
+    message: string
+    recommendation: string
+  }>
+}
+
+/** 批量操作结果 */
+export interface BatchOperationResult {
+  succeeded: string[]
+  failed: string[]
+  total: number
+  success_count: number
+  failure_count: number
+}
+
+/** 上传返回 */
+export interface UploadResult {
+  storage_key: string
+  ingest_job_id: string
+  url: string
+}
+
+/** 预签名直传准备返回 */
+export interface DirectUploadPrepareResult {
+  upload_url: string
+  method: string
+  storage_key: string
+  expires_at: string
+  fields: Record<string, string>
+  max_size_bytes: number
+}
+
+/** 直传完成确认返回 */
+export interface DirectUploadCompleteResult {
+  storage_key: string
+  ingest_job_id: string
+}
@@ -0,0 +1,119 @@
+/**
+ * 上传相关 API（表单上传 + OSS 直传）
+ */
+import apiClient from "../client"
+import { getOrCreateDefaultProject } from "../projects"
+import type { UploadResult, DirectUploadPrepareResult, DirectUploadCompleteResult } from "./types"
+
+/** 表单上传素材（小文件） */
+export const uploadAsset = async (formData: FormData): Promise<UploadResult> => {
+  const response = await apiClient.post("/upload", formData, {
+    headers: { "Content-Type": "multipart/form-data" },
+    timeout: 30 * 60 * 1000,
+  })
+  return response.data
+}
+
+/** 预签名直传准备 */
+export const prepareDirectUpload = async (data: {
+  project_id: string
+  library_id: string
+  filename: string
+  content_type: string
+  file_size: number
+}): Promise<DirectUploadPrepareResult> => {
+  const response = await apiClient.post("/upload/direct/prepare", data)
+  return response.data
+}
+
+/** 直传完成确认 */
+export const completeDirectUpload = async (data: {
+  project_id: string
+  library_id: string
+  storage_key: string
+}): Promise<DirectUploadCompleteResult> => {
+  const response = await apiClient.post("/upload/direct/complete", data)
+  return response.data
+}
+
+/** 直传上传（大文件推荐），支持可选进度回调 */
+export const uploadAssetDirect = async (data: {
+  file: File
+  library_id: string
+  onProgress?: (percent: number) => void
+}): Promise<DirectUploadCompleteResult> => {
+  const project = await getOrCreateDefaultProject()
+
+  const prepared = await prepareDirectUpload({
+    project_id: project.id,
+    library_id: data.library_id,
+    filename: data.file.name,
+    content_type: data.file.type || "application/octet-stream",
+    file_size: data.file.size,
+  })
+
+  const directForm = new FormData()
+  Object.entries(prepared.fields).forEach(([key, value]) => directForm.append(key, value))
+  directForm.append("file", data.file)
+
+  // 使用 XMLHttpRequest 以获取上传进度 + 超时控制 + 详细错误诊断
+  await new Promise<void>((resolve, reject) => {
+    const xhr = new XMLHttpRequest()
+    xhr.open(prepared.method, prepared.upload_url)
+
+    // 超时 10 分钟
+    xhr.timeout = 10 * 60 * 1000
+
+    xhr.upload.onprogress = (e) => {
+      if (e.lengthComputable && data.onProgress) {
+        data.onProgress(Math.round((e.loaded / e.total) * 100))
+      }
+    }
+    xhr.onload = () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        resolve()
+      } else {
+        // 解析 OSS 返回的 XML 错误信息
+        let ossError = ""
+        try {
+          const codeMatch = xhr.responseText.match(/<Code>([^<]+)<\/Code>/)
+          const msgMatch = xhr.responseText.match(/<Message>([^<]+)<\/Message>/)
+          if (codeMatch || msgMatch) {
+            ossError = ` [OSS: ${codeMatch?.[1] || "unknown"} - ${msgMatch?.[1] || "unknown"}]`
+          }
+        } catch {
+          // 无法解析响应体
+        }
+        const detail = `OSS 直传失败: HTTP ${xhr.status} ${xhr.statusText}${ossError}`
+        console.error("[OSS Upload] 直传失败:", {
+          url: prepared.upload_url,
+          storage_key: prepared.storage_key,
+          status: xhr.status,
+          statusText: xhr.statusText,
+        })
+        reject(new Error(detail))
+      }
+    }
+    xhr.onerror = () => {
+      console.error("[OSS Upload] 网络错误:", {
+        url: prepared.upload_url,
+        storage_key: prepared.storage_key,
+      })
+      reject(new Error("OSS 上传网络错误，请检查网络连接"))
+    }
+    xhr.ontimeout = () => {
+      console.error("[OSS Upload] 上传超时:", {
+        url: prepared.upload_url,
+        storage_key: prepared.storage_key,
+      })
+      reject(new Error("OSS 上传超时（10分钟），请检查网络或尝试更小的文件"))
+    }
+    xhr.send(directForm)
+  })
+
+  return completeDirectUpload({
+    project_id: project.id,
+    library_id: data.library_id,
+    storage_key: prepared.storage_key,
+  })
+}
@@ -147,13 +147,14 @@ export interface SendVerificationCodeRequest {
 }

 export interface BindContactRequest {
-  target: "email" | "phone"
-  value: string
-  code: string
+  email?: string
+  email_code?: string
+  phone?: string
+  phone_code?: string
 }

 export interface BindContactResponse {
-  message: string
+  success: boolean
  user: User
 }

@@ -1,68 +0,0 @@
-/**
- * BGM 预设音乐 API
- * 对接后端 BGM 混音能力：预设列表查询（按风格分类 + 关键词搜索）
- */
-import apiClient from "./client"
-
-/* ──────────── 类型 ──────────── */
-
-/** BGM 风格分类 */
-export type BgmCategory = "轻快" | "治愈" | "科技" | "电商"
-
-/** BGM 预设项 */
-export interface BgmPreset {
-  id: string
-  name: string
-  category: BgmCategory
-  /** 音频文件 URL */
-  url: string
-  /** 时长（秒） */
-  duration: number
-  /** 关键词标签 */
-  tags: string[]
-  /** 封面图 URL */
-  cover_url?: string
-}
-
-/** BGM 预设列表查询参数 */
-export interface BgmPresetsQuery {
-  category?: BgmCategory | string
-  keyword?: string
-}
-
-/** BGM 混音配置（嵌入模板） */
-export interface BgmMixConfig {
-  /** 是否启用 BGM */
-  enabled: boolean
-  /** 选中的 BGM ID */
-  music_id: string
-  /** BGM 音量 0-100 */
-  volume: number
-  /** 淡入时长（秒） 0-3 */
-  fade_in: number
-  /** 淡出时长（秒） 0-3 */
-  fade_out: number
-  /** 人声闪避（sidechain） */
-  voice_dodge: boolean
-}
-
-/** 默认 BGM 混音配置 */
-export const DEFAULT_BGM_MIX_CONFIG: BgmMixConfig = {
-  enabled: false,
-  music_id: "",
-  volume: 50,
-  fade_in: 0.5,
-  fade_out: 0.5,
-  voice_dodge: true,
-}
-
-/* ──────────── API ──────────── */
-
-/** 获取 BGM 预设列表 */
-export const getBgmPresets = async (params?: BgmPresetsQuery): Promise<BgmPreset[]> => {
-  const searchParams: Record<string, string> = {}
-  if (params?.category) searchParams.category = params.category
-  if (params?.keyword) searchParams.keyword = params.keyword
-  const res = await apiClient.get("/bgm/presets", { params: searchParams })
-  return res.data?.data ?? res.data ?? []
-}
@@ -0,0 +1,14 @@
+/**
+ * BGM 预设音乐 API 函数
+ */
+import apiClient from "../client"
+import type { BgmPreset, BgmPresetsQuery } from "./types"
+
+/** 获取 BGM 预设列表 */
+export const getBgmPresets = async (params?: BgmPresetsQuery): Promise<BgmPreset[]> => {
+  const searchParams: Record<string, string> = {}
+  if (params?.category) searchParams.category = params.category
+  if (params?.keyword) searchParams.keyword = params.keyword
+  const res = await apiClient.get("/bgm/presets", { params: searchParams })
+  return res.data?.data ?? res.data ?? []
+}
@@ -0,0 +1,14 @@
+/**
+ * BGM 相关常量
+ */
+import type { BgmMixConfig } from "./types"
+
+/** 默认 BGM 混音配置 */
+export const DEFAULT_BGM_MIX_CONFIG: BgmMixConfig = {
+  enabled: false,
+  music_id: "",
+  volume: 50,
+  fade_in: 0.5,
+  fade_out: 0.5,
+  voice_dodge: true,
+}
@@ -0,0 +1,13 @@
+/**
+ * BGM API — 目录化入口
+ * 保持与原 bgm.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type { BgmCategory, BgmPreset, BgmPresetsQuery, BgmMixConfig } from "./types"
+
+// 常量
+export { DEFAULT_BGM_MIX_CONFIG } from "./constants"
+
+// API 函数
+export { getBgmPresets } from "./bgm"
@@ -0,0 +1,43 @@
+/**
+ * BGM 相关类型定义
+ */
+
+/** BGM 风格分类 */
+export type BgmCategory = "轻快" | "治愈" | "科技" | "电商"
+
+/** BGM 预设项 */
+export interface BgmPreset {
+  id: string
+  name: string
+  category: BgmCategory
+  /** 音频文件 URL */
+  url: string
+  /** 时长（秒） */
+  duration: number
+  /** 关键词标签 */
+  tags: string[]
+  /** 封面图 URL */
+  cover_url?: string
+}
+
+/** BGM 预设列表查询参数 */
+export interface BgmPresetsQuery {
+  category?: BgmCategory | string
+  keyword?: string
+}
+
+/** BGM 混音配置（嵌入模板） */
+export interface BgmMixConfig {
+  /** 是否启用 BGM */
+  enabled: boolean
+  /** 选中的 BGM ID */
+  music_id: string
+  /** BGM 音量 0-100 */
+  volume: number
+  /** 淡入时长（秒） 0-3 */
+  fade_in: number
+  /** 淡出时长（秒） 0-3 */
+  fade_out: number
+  /** 人声闪避（sidechain） */
+  voice_dodge: boolean
+}
@@ -0,0 +1,38 @@
+/**
+ * 查重 API 函数
+ */
+import apiClient from "../client"
+import type { DuplicationDetail, DuplicationRecord, DuplicationUploadResponse } from "./types"
+
+/** 上传视频进行查重 */
+export const uploadForDuplication = async (file: File): Promise<DuplicationUploadResponse> => {
+  const formData = new FormData()
+  formData.append("file", file)
+  const response = await apiClient.post("/duplication/upload", formData, {
+    headers: { "Content-Type": "multipart/form-data" },
+  })
+  return response.data
+}
+
+/** 获取查重记录列表 */
+export const getDuplicationRecords = async (): Promise<DuplicationRecord[]> => {
+  const response = await apiClient.get("/duplication/records")
+  return response.data
+}
+
+/** 获取查重详情 */
+export const getDuplicationDetail = async (recordId: string): Promise<DuplicationDetail> => {
+  const response = await apiClient.get(`/duplication/records/${recordId}`)
+  return response.data
+}
+
+/** 删除查重记录 */
+export const deleteDuplicationRecord = async (recordId: string): Promise<void> => {
+  await apiClient.delete(`/duplication/records/${recordId}`)
+}
+
+/** 重新查重 */
+export const retryDuplication = async (recordId: string): Promise<DuplicationUploadResponse> => {
+  const response = await apiClient.post(`/duplication/records/${recordId}/retry`)
+  return response.data
+}
@@ -0,0 +1,22 @@
+/**
+ * 查重 API — 目录化入口
+ * 保持与原 duplication.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  DuplicationStatus,
+  DuplicationRecord,
+  DuplicateSegment,
+  DuplicationDetail,
+  DuplicationUploadResponse,
+} from "./types"
+
+// API 函数
+export {
+  uploadForDuplication,
+  getDuplicationRecords,
+  getDuplicationDetail,
+  deleteDuplicationRecord,
+  retryDuplication,
+} from "./duplication"
@@ -1,8 +1,6 @@
 /**
- * 查重 API 模块
- * 提供视频查重相关接口
+ * 查重相关类型定义
 */
-import apiClient from "./client"

 /** 查重记录状态 */
 export type DuplicationStatus = "pending" | "processing" | "completed" | "failed"
@@ -62,38 +60,3 @@ export interface DuplicationUploadResponse {
  /** 消息 */
  message: string
 }
-
-// ============ API 函数 ============
-
-/** 上传视频进行查重 */
-export const uploadForDuplication = async (file: File): Promise<DuplicationUploadResponse> => {
-  const formData = new FormData()
-  formData.append("file", file)
-  const response = await apiClient.post("/duplication/upload", formData, {
-    headers: { "Content-Type": "multipart/form-data" },
-  })
-  return response.data
-}
-
-/** 获取查重记录列表 */
-export const getDuplicationRecords = async (): Promise<DuplicationRecord[]> => {
-  const response = await apiClient.get("/duplication/records")
-  return response.data
-}
-
-/** 获取查重详情 */
-export const getDuplicationDetail = async (recordId: string): Promise<DuplicationDetail> => {
-  const response = await apiClient.get(`/duplication/records/${recordId}`)
-  return response.data
-}
-
-/** 删除查重记录 */
-export const deleteDuplicationRecord = async (recordId: string): Promise<void> => {
-  await apiClient.delete(`/duplication/records/${recordId}`)
-}
-
-/** 重新查重 */
-export const retryDuplication = async (recordId: string): Promise<DuplicationUploadResponse> => {
-  const response = await apiClient.post(`/duplication/records/${recordId}/retry`)
-  return response.data
-}
@@ -0,0 +1,20 @@
+/**
+ * 模板编辑器常量
+ */
+import type { TemplateMode } from "./types"
+
+/** 模式显示名称映射 */
+export const MODE_LABELS: Record<TemplateMode, string> = {
+  pip: "混剪",
+  voice_over: "人物口播",
+  one_take: "一镜到底",
+  voice_pip: "口播+混剪",
+}
+
+/** 模式颜色映射 */
+export const MODE_COLORS: Record<TemplateMode, string> = {
+  pip: "blue",
+  voice_over: "green",
+  one_take: "orange",
+  voice_pip: "purple",
+}
@@ -0,0 +1,36 @@
+/**
+ * 模板编辑器 API — 目录化入口
+ * 保持与原 editing-planner.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  TemplateMode,
+  TitleConfig,
+  SubtitleConfig,
+  BgmConfig,
+  TemplateSegment,
+  EditingTemplate,
+  TemplateCategory,
+  SaveTemplatePayload,
+  GenerateFromTemplatePayload,
+  ValidationWarningDetails,
+  ValidateWarning,
+  GenerateFromTemplateResponse,
+  ListTemplatesResponse,
+  ListCategoriesResponse,
+} from "./types"
+
+// 常量
+export { MODE_LABELS, MODE_COLORS } from "./constants"
+
+// API 函数
+export {
+  getEditingTemplates,
+  getEditingTemplate,
+  createEditingTemplate,
+  updateEditingTemplate,
+  deleteEditingTemplate,
+  getTemplateCategories,
+  generateFromTemplate,
+} from "./templates"
@@ -0,0 +1,78 @@
+/**
+ * 模板编辑器 API 函数
+ */
+import apiClient from "../client"
+import type {
+  EditingTemplate,
+  TemplateCategory,
+  SaveTemplatePayload,
+  GenerateFromTemplatePayload,
+  GenerateFromTemplateResponse,
+  ListTemplatesResponse,
+  ListCategoriesResponse,
+} from "./types"
+
+/** 获取模板列表 */
+export const getEditingTemplates = async (params?: {
+  category?: string
+  tag?: string
+  skip?: number
+  limit?: number
+}): Promise<EditingTemplate[]> => {
+  const response = await apiClient.get<ListTemplatesResponse>("/templates", {
+    params: {
+      skip: params?.skip ?? 0,
+      limit: params?.limit ?? 50,
+    },
+  })
+  let list = response.data.items
+  if (params?.category) list = list.filter((t) => t.category === params.category)
+  if (params?.tag) list = list.filter((t) => t.tags.includes(params.tag!))
+  return list
+}
+
+/** 获取模板详情 */
+export const getEditingTemplate = async (id: string): Promise<EditingTemplate> => {
+  const response = await apiClient.get<EditingTemplate>(`/templates/${id}`)
+  return response.data
+}
+
+/** 创建模板 */
+export const createEditingTemplate = async (
+  data: SaveTemplatePayload,
+): Promise<EditingTemplate> => {
+  const response = await apiClient.post<EditingTemplate>("/templates", data)
+  return response.data
+}
+
+/** 更新模板 */
+export const updateEditingTemplate = async (
+  id: string,
+  data: SaveTemplatePayload,
+): Promise<EditingTemplate> => {
+  const response = await apiClient.patch<EditingTemplate>(`/templates/${id}`, data)
+  return response.data
+}
+
+/** 删除模板 */
+export const deleteEditingTemplate = async (id: string): Promise<void> => {
+  await apiClient.delete(`/templates/${id}`)
+}
+
+/** 获取模板分类列表 */
+export const getTemplateCategories = async (): Promise<TemplateCategory[]> => {
+  const response = await apiClient.get<ListCategoriesResponse>("/templates/categories/list")
+  return response.data.items
+}
+
+/** 使用模板生成视频（调用 validate 端点） */
+export const generateFromTemplate = async (
+  templateId: string,
+  data: GenerateFromTemplatePayload,
+): Promise<GenerateFromTemplateResponse> => {
+  const response = await apiClient.post<GenerateFromTemplateResponse>(
+    `/templates/${templateId}/validate`,
+    data,
+  )
+  return response.data
+}
@@ -0,0 +1,138 @@
+/**
+ * 模板编辑器类型定义
+ */
+import type {
+  WatermarkConfig,
+  IntroOutroConfig,
+  PipConfig,
+  FilterConfig,
+  ChromaKeyConfig,
+  StickerConfig,
+  CoverConfig,
+} from "@/pages/editing-planner/types"
+
+/** 模板模式（后端枚举值） */
+export type TemplateMode = "pip" | "voice_over" | "one_take" | "voice_pip"
+
+/** 标题配置 */
+export interface TitleConfig {
+  ai_auto_select: boolean
+  content: string
+  font_preset: string
+  font_color: string
+  font_size: number
+  position: string
+}
+
+/** 字幕配置 */
+export interface SubtitleConfig {
+  enabled: boolean
+  position: string
+  font: string
+  color: string
+  size: number
+  animation: string
+}
+
+/** BGM 配置 */
+export interface BgmConfig {
+  enabled: boolean
+  music_id: string
+}
+
+/** 模板片段 */
+export interface TemplateSegment {
+  id?: string
+  segment_order: number
+  duration_min: number
+  duration_max: number
+  material_type: string | null
+}
+
+/** 剪辑模板 */
+export interface EditingTemplate {
+  id: string
+  name: string
+  mode: TemplateMode
+  category: string
+  tags: string[]
+  title_config: TitleConfig
+  subtitle_config: SubtitleConfig
+  bgm_config: BgmConfig
+  estimated_duration: number
+  segments: TemplateSegment[]
+  watermark_config?: WatermarkConfig
+  intro_outro_config?: IntroOutroConfig
+  pip_config?: PipConfig
+  filter_config?: FilterConfig
+  green_screen_config?: ChromaKeyConfig
+  sticker_config?: StickerConfig
+  cover_config?: CoverConfig
+  is_active?: boolean
+  created_at: string
+  updated_at: string
+}
+
+/** 模板分类 */
+export interface TemplateCategory {
+  id: string
+  name: string
+  created_at?: string
+}
+
+/** 创建/更新模板请求体 */
+export interface SaveTemplatePayload {
+  name: string
+  mode: TemplateMode
+  category: string
+  tags: string[]
+  title_config: TitleConfig
+  subtitle_config: SubtitleConfig
+  bgm_config: BgmConfig
+  estimated_duration: number
+  segments: Omit<TemplateSegment, "id">[]
+  watermark_config?: WatermarkConfig
+  intro_outro_config?: IntroOutroConfig
+  pip_config?: PipConfig
+  filter_config?: FilterConfig
+  green_screen_config?: ChromaKeyConfig
+  sticker_config?: StickerConfig
+  cover_config?: CoverConfig
+}
+
+/** 使用模板生成请求体 */
+export interface GenerateFromTemplatePayload {
+  voiceover_duration: number
+}
+
+/** 验证警告详情 */
+export interface ValidationWarningDetails {
+  field?: string
+  expected?: string | number
+  actual?: string | number
+  suggested?: string | number
+}
+
+/** 验证警告 */
+export interface ValidateWarning {
+  code: string
+  message: string
+  details?: ValidationWarningDetails
+}
+
+/** 使用模板生成响应 */
+export interface GenerateFromTemplateResponse {
+  template: EditingTemplate
+  warnings: ValidateWarning[]
+}
+
+/** 列表响应（带分页） */
+export interface ListTemplatesResponse {
+  items: EditingTemplate[]
+  total: number
+}
+
+/** 分类列表响应 */
+export interface ListCategoriesResponse {
+  items: TemplateCategory[]
+}
@@ -1,243 +0,0 @@
-/**
- * 模板编辑器 API
- * 对接后端 /api/v1/templates 路由
- */
-import apiClient from "./client"
-import type {
-  WatermarkConfig,
-  IntroOutroConfig,
-  PipConfig,
-  FilterConfig,
-  ChromaKeyConfig,
-  StickerConfig,
-  CoverConfig,
-} from "@/pages/editing-planner/types"
-
-/* ──────────── 类型定义 ──────────── */
-
-/** 模板模式（后端枚举值） */
-export type TemplateMode = "pip" | "voice_over" | "one_take" | "voice_pip"
-
-/** 模式显示名称映射 */
-export const MODE_LABELS: Record<TemplateMode, string> = {
-  pip: "混剪",
-  voice_over: "人物口播",
-  one_take: "一镜到底",
-  voice_pip: "口播+混剪",
-}
-
-/** 模式颜色映射 */
-export const MODE_COLORS: Record<TemplateMode, string> = {
-  pip: "blue",
-  voice_over: "green",
-  one_take: "orange",
-  voice_pip: "purple",
-}
-
-/** 标题配置 */
-export interface TitleConfig {
-  ai_auto_select: boolean
-  content: string
-  font_preset: string
-  font_color: string
-  font_size: number
-  position: string
-}
-
-/** 字幕配置 */
-export interface SubtitleConfig {
-  enabled: boolean
-  position: string
-  font: string
-  color: string
-  size: number
-  animation: string
-}
-
-/** BGM 配置 */
-export interface BgmConfig {
-  enabled: boolean
-  music_id: string
-}
-
-/** 模板片段 */
-export interface TemplateSegment {
-  id?: string
-  segment_order: number
-  duration_min: number
-  duration_max: number
-  material_type: string | null
-}
-
-/** 剪辑模板 */
-export interface EditingTemplate {
-  id: string
-  name: string
-  mode: TemplateMode
-  category: string
-  tags: string[]
-  title_config: TitleConfig
-  subtitle_config: SubtitleConfig
-  bgm_config: BgmConfig
-  estimated_duration: number
-  segments: TemplateSegment[]
-  /** 水印配置（后端就绪后启用） */
-  watermark_config?: WatermarkConfig
-  /** 片头片尾配置（后端就绪后启用） */
-  intro_outro_config?: IntroOutroConfig
-  /** 混剪配置 */
-  pip_config?: PipConfig
-  /** 滤镜调色配置 */
-  filter_config?: FilterConfig
-  /** 绿幕抠像配置 */
-  green_screen_config?: ChromaKeyConfig
-  /** 贴纸配置 */
-  sticker_config?: StickerConfig
-  /** 封面配置 */
-  cover_config?: CoverConfig
-  is_active?: boolean
-  created_at: string
-  updated_at: string
-}
-
-/** 模板分类 */
-export interface TemplateCategory {
-  id: string
-  name: string
-  created_at?: string
-}
-
-/** 创建/更新模板请求体 */
-export interface SaveTemplatePayload {
-  name: string
-  mode: TemplateMode
-  category: string
-  tags: string[]
-  title_config: TitleConfig
-  subtitle_config: SubtitleConfig
-  bgm_config: BgmConfig
-  estimated_duration: number
-  segments: Omit<TemplateSegment, "id">[]
-  /** 水印配置（后端就绪后启用） */
-  watermark_config?: WatermarkConfig
-  /** 片头片尾配置（后端就绪后启用） */
-  intro_outro_config?: IntroOutroConfig
-  /** 混剪配置 */
-  pip_config?: PipConfig
-  /** 滤镜调色配置 */
-  filter_config?: FilterConfig
-  /** 绿幕抠像配置 */
-  green_screen_config?: ChromaKeyConfig
-  /** 贴纸配置 */
-  sticker_config?: StickerConfig
-  /** 封面配置 */
-  cover_config?: CoverConfig
-}
-
-/** 使用模板生成请求体 */
-export interface GenerateFromTemplatePayload {
-  voiceover_duration: number
-}
-
-/** 验证警告详情 */
-export interface ValidationWarningDetails {
-  /** 相关字段名 */
-  field?: string
-  /** 期望值 */
-  expected?: string | number
-  /** 实际值 */
-  actual?: string | number
-  /** 建议值 */
-  suggested?: string | number
-}
-
-/** 验证/生成响应 */
-export interface ValidateWarning {
-  code: string
-  message: string
-  details?: ValidationWarningDetails
-}
-
-/** 使用模板生成响应 */
-export interface GenerateFromTemplateResponse {
-  template: EditingTemplate
-  warnings: ValidateWarning[]
-}
-
-/** 列表响应（带分页） */
-export interface ListTemplatesResponse {
-  items: EditingTemplate[]
-  total: number
-}
-
-/** 分类列表响应 */
-export interface ListCategoriesResponse {
-  items: TemplateCategory[]
-}
-
-// ============ API 函数 ============
-
-/** 获取模板列表 */
-export const getEditingTemplates = async (params?: {
-  category?: string
-  tag?: string
-  skip?: number
-  limit?: number
-}): Promise<EditingTemplate[]> => {
-  const response = await apiClient.get<ListTemplatesResponse>("/templates", {
-    params: {
-      skip: params?.skip ?? 0,
-      limit: params?.limit ?? 50,
-    },
-  })
-  let list = response.data.items
-  if (params?.category) list = list.filter((t) => t.category === params.category)
-  if (params?.tag) list = list.filter((t) => t.tags.includes(params.tag!))
-  return list
-}
-
-/** 获取模板详情 */
-export const getEditingTemplate = async (id: string): Promise<EditingTemplate> => {
-  const response = await apiClient.get<EditingTemplate>(`/templates/${id}`)
-  return response.data
-}
-
-/** 创建模板 */
-export const createEditingTemplate = async (
-  data: SaveTemplatePayload,
-): Promise<EditingTemplate> => {
-  const response = await apiClient.post<EditingTemplate>("/templates", data)
-  return response.data
-}
-
-/** 更新模板 */
-export const updateEditingTemplate = async (
-  id: string,
-  data: SaveTemplatePayload,
-): Promise<EditingTemplate> => {
-  const response = await apiClient.patch<EditingTemplate>(`/templates/${id}`, data)
-  return response.data
-}
-
-/** 删除模板 */
-export const deleteEditingTemplate = async (id: string): Promise<void> => {
-  await apiClient.delete(`/templates/${id}`)
-}
-
-/** 获取模板分类列表 */
-export const getTemplateCategories = async (): Promise<TemplateCategory[]> => {
-  const response = await apiClient.get<ListCategoriesResponse>("/templates/categories/list")
-  return response.data.items
-}
-
-/** 使用模板生成视频（调用 validate 端点） */
-export const generateFromTemplate = async (
-  templateId: string,
-  data: GenerateFromTemplatePayload,
-): Promise<GenerateFromTemplateResponse> => {
-  const response = await apiClient.post<GenerateFromTemplateResponse>(
-    `/templates/${templateId}/validate`,
-    data,
-  )
-  return response.data
-}
@@ -1,174 +0,0 @@
-/**
- * 成品 / 视频相关 API
- * 后端实际接口：/videos
- */
-import apiClient from "./client"
-
-/** 复核状态 */
-export type ReviewStatus = "pending_review" | "approved" | "rejected"
-
-/** 成品条目 */
-export interface ProductItem {
-  id: string
-  title: string
-  video_url?: string
-  thumbnail_url?: string
-  duration_seconds?: number
-  file_size?: number
-  resolution?: string
-  status: "processing" | "completed" | "failed"
-  /** 复核状态 */
-  review_status?: ReviewStatus
-  /** 所属项目 ID */
-  project_id?: string
-  /** 所属项目名称 */
-  project_name?: string
-  /** 查重率（百分比） */
-  duplicate_rate?: number
-  created_at?: string
-  updated_at?: string
-}
-
-/** 列表查询参数 */
-export interface ProductListParams {
-  page?: number
-  page_size?: number
-  project_id?: string
-  review_status?: ReviewStatus | "all"
-}
-
-/** 分页响应 */
-export interface ProductListResponse {
-  items: ProductItem[]
-  total: number
-  page: number
-  page_size: number
-}
-
-/** 批量下载任务状态 */
-export interface BatchDownloadStatus {
-  job_id: string
-  status: "processing" | "completed" | "failed"
-  /** 完成后返回的下载 URL */
-  download_url?: string
-  /** 进度百分比 */
-  progress?: number
-}
-
-/** 后端 /videos 接口返回的原始视频条目 */
-interface VideoItem {
-  id: string
-  project_id: string
-  generation_task_id: string
-  name: string
-  file_url: string
-  file_size: number
-  duration: number
-  thumbnail_url: string | null
-  width: number
-  height: number
-  fps: number
-  status: string
-  review_status: ReviewStatus
-  generation_params: Record<string, unknown>
-  download_url: string
-  generated_at: string
-}
-
-/**
- * 将后端 VideoItem 映射为 ProductItem 格式
- */
-function mapVideoToProductItem(video: VideoItem): ProductItem {
-  return {
-    id: video.id,
-    title: video.name || "未命名视频",
-    // 优先用 download_url（带签名）播放，file_url 无签名无法访问
-    video_url: video.download_url || video.file_url,
-    thumbnail_url: video.thumbnail_url || undefined,
-    duration_seconds: video.duration,
-    file_size: video.file_size,
-    resolution: video.width && video.height ? `${video.width}x${video.height}` : undefined,
-    status:
-      video.status === "completed"
-        ? "completed"
-        : video.status === "failed"
-          ? "failed"
-          : "processing",
-    review_status: video.review_status,
-    project_id: video.project_id,
-    // 后端 /videos 接口暂无 project_name 字段
-    project_name: undefined,
-    // 后端字段名为 generated_at，映射为 created_at 供前端统一使用
-    created_at: video.generated_at,
-    updated_at: video.generated_at,
-    // 后端 /videos 接口暂无 duplicate_rate 字段
-    duplicate_rate: undefined,
-  }
-}
-
-/** 获取成品列表（支持分页和筛选） */
-export const getProducts = async (params?: ProductListParams): Promise<ProductItem[]> => {
-  const response = await apiClient.get("/videos", { params })
-  const data = response.data
-  const videos: VideoItem[] = Array.isArray(data?.items)
-    ? data.items
-    : Array.isArray(data)
-      ? data
-      : []
-  return videos.map(mapVideoToProductItem)
-}
-
-/** 获取单个成品详情 */
-export const getProduct = async (productId: string): Promise<ProductItem> => {
-  const response = await apiClient.get(`/videos/${productId}`)
-  return mapVideoToProductItem(response.data as VideoItem)
-}
-
-/**
- * 删除成品
- * 注意：后端暂未实现 /videos DELETE 接口，调用会返回 405
- * 待后端实现后自动生效
- */
-export const deleteProduct = async (productId: string): Promise<void> => {
-  await apiClient.delete(`/videos/${productId}`)
-}
-
-/**
- * 获取成品下载链接
- * 直接使用列表返回的 download_url（带OSS签名）
- */
-export const getProductDownloadUrl = async (
-  productId: string,
-): Promise<{ url: string; expires_at: string }> => {
-  // 优先从列表缓存取；如果没有则调详情接口
-  const product = await getProduct(productId)
-  if (!product.video_url) throw new Error("下载链接不可用")
-  return { url: product.video_url, expires_at: "" }
-}
-
-/** 更新复核状态 — TODO: 后端暂无对应端点，暂存本地状态 */
-export const updateReviewStatus = async (
-  productId: string,
-  status: ReviewStatus,
-): Promise<ProductItem> => {
-  // 后端暂无 /videos/{id}/review 端点
-  // 暂时返回当前状态，后续可扩展
-  const product = await getProduct(productId)
-  return { ...product, review_status: status }
-}
-
-/** 发起批量下载 — TODO: 后端暂无对应端点 */
-export const batchDownload = async (videoIds: string[]): Promise<{ job_id: string }> => {
-  // 后端暂无 /videos/batch-download 端点
-  // 暂时返回模拟 job_id，后续可扩展
-  console.warn("[batchDownload] 后端暂无批量下载端点", videoIds)
-  return { job_id: `mock-${Date.now()}` }
-}
-
-/** 查询批量下载状态 — TODO: 后端暂无对应端点 */
-export const getBatchDownloadStatus = async (jobId: string): Promise<BatchDownloadStatus> => {
-  // 后端暂无 /videos/batch-download/{jobId} 端点
-  // 暂时返回模拟状态，后续可扩展
-  console.warn("[getBatchDownloadStatus] 后端暂无批量下载状态端点", jobId)
-  return { job_id: jobId, status: "processing", progress: 0 }
-}
@@ -0,0 +1,28 @@
+/**
+ * 成品 / 视频相关 API — 目录化入口
+ * 保持与原 products.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  ReviewStatus,
+  ProductItem,
+  ProductListParams,
+  ProductListResponse,
+  BatchDownloadStatus,
+  VideoItem,
+} from "./types"
+
+// 工具函数
+export { mapVideoToProductItem } from "./utils"
+
+// API 函数
+export {
+  getProducts,
+  getProduct,
+  deleteProduct,
+  getProductDownloadUrl,
+  updateReviewStatus,
+  batchDownload,
+  getBatchDownloadStatus,
+} from "./products"
@@ -0,0 +1,80 @@
+/**
+ * 成品 / 视频相关 API 函数
+ * 后端实际接口：/videos
+ */
+import apiClient from "../client"
+import type {
+  BatchDownloadStatus,
+  ProductItem,
+  ProductListParams,
+  VideoItem,
+  ReviewStatus,
+} from "./types"
+import { mapVideoToProductItem } from "./utils"
+
+/** 获取成品列表（支持分页和筛选） */
+export const getProducts = async (params?: ProductListParams): Promise<ProductItem[]> => {
+  const response = await apiClient.get("/videos", { params })
+  const data = response.data
+  const videos: VideoItem[] = Array.isArray(data?.items)
+    ? data.items
+    : Array.isArray(data)
+      ? data
+      : []
+  return videos.map(mapVideoToProductItem)
+}
+
+/** 获取单个成品详情 */
+export const getProduct = async (productId: string): Promise<ProductItem> => {
+  const response = await apiClient.get(`/videos/${productId}`)
+  return mapVideoToProductItem(response.data as VideoItem)
+}
+
+/**
+ * 删除成品
+ * 注意：后端暂未实现 /videos DELETE 接口，调用会返回 405
+ * 待后端实现后自动生效
+ */
+export const deleteProduct = async (productId: string): Promise<void> => {
+  await apiClient.delete(`/videos/${productId}`)
+}
+
+/**
+ * 获取成品下载链接
+ * 直接使用列表返回的 download_url（带OSS签名）
+ */
+export const getProductDownloadUrl = async (
+  productId: string,
+): Promise<{ url: string; expires_at: string }> => {
+  // 优先从列表缓存取；如果没有则调详情接口
+  const product = await getProduct(productId)
+  if (!product.video_url) throw new Error("下载链接不可用")
+  return { url: product.video_url, expires_at: "" }
+}
+
+/** 更新复核状态 — TODO: 后端暂无对应端点，暂存本地状态 */
+export const updateReviewStatus = async (
+  productId: string,
+  status: ReviewStatus,
+): Promise<ProductItem> => {
+  // 后端暂无 /videos/{id}/review 端点
+  // 暂时返回当前状态，后续可扩展
+  const product = await getProduct(productId)
+  return { ...product, review_status: status }
+}
+
+/** 发起批量下载 — TODO: 后端暂无对应端点 */
+export const batchDownload = async (videoIds: string[]): Promise<{ job_id: string }> => {
+  // 后端暂无 /videos/batch-download 端点
+  // 暂时返回模拟 job_id，后续可扩展
+  console.warn("[batchDownload] 后端暂无批量下载端点", videoIds)
+  return { job_id: `mock-${Date.now()}` }
+}
+
+/** 查询批量下载状态 — TODO: 后端暂无对应端点 */
+export const getBatchDownloadStatus = async (jobId: string): Promise<BatchDownloadStatus> => {
+  // 后端暂无 /videos/batch-download/{jobId} 端点
+  // 暂时返回模拟状态，后续可扩展
+  console.warn("[getBatchDownloadStatus] 后端暂无批量下载状态端点", jobId)
+  return { job_id: jobId, status: "processing", progress: 0 }
+}
@@ -0,0 +1,74 @@
+/**
+ * 成品 / 视频相关类型定义
+ */
+
+/** 复核状态 */
+export type ReviewStatus = "pending_review" | "approved" | "rejected"
+
+/** 成品条目 */
+export interface ProductItem {
+  id: string
+  title: string
+  video_url?: string
+  thumbnail_url?: string
+  duration_seconds?: number
+  file_size?: number
+  resolution?: string
+  status: "processing" | "completed" | "failed"
+  /** 复核状态 */
+  review_status?: ReviewStatus
+  /** 所属项目 ID */
+  project_id?: string
+  /** 所属项目名称 */
+  project_name?: string
+  /** 查重率（百分比） */
+  duplicate_rate?: number
+  created_at?: string
+  updated_at?: string
+}
+
+/** 列表查询参数 */
+export interface ProductListParams {
+  page?: number
+  page_size?: number
+  project_id?: string
+  review_status?: ReviewStatus | "all"
+}
+
+/** 分页响应 */
+export interface ProductListResponse {
+  items: ProductItem[]
+  total: number
+  page: number
+  page_size: number
+}
+
+/** 批量下载任务状态 */
+export interface BatchDownloadStatus {
+  job_id: string
+  status: "processing" | "completed" | "failed"
+  /** 完成后返回的下载 URL */
+  download_url?: string
+  /** 进度百分比 */
+  progress?: number
+}
+
+/** 后端 /videos 接口返回的原始视频条目 */
+export interface VideoItem {
+  id: string
+  project_id: string
+  generation_task_id: string
+  name: string
+  file_url: string
+  file_size: number
+  duration: number
+  thumbnail_url: string | null
+  width: number
+  height: number
+  fps: number
+  status: string
+  review_status: ReviewStatus
+  generation_params: Record<string, unknown>
+  download_url: string
+  generated_at: string
+}
@@ -0,0 +1,35 @@
+/**
+ * 成品数据转换工具函数
+ */
+import type { ProductItem, VideoItem } from "./types"
+
+/**
+ * 将后端 VideoItem 映射为 ProductItem 格式
+ */
+export function mapVideoToProductItem(video: VideoItem): ProductItem {
+  return {
+    id: video.id,
+    title: video.name || "未命名视频",
+    // 优先用 download_url（带签名）播放，file_url 无签名无法访问
+    video_url: video.download_url || video.file_url,
+    thumbnail_url: video.thumbnail_url || undefined,
+    duration_seconds: video.duration,
+    file_size: video.file_size,
+    resolution: video.width && video.height ? `${video.width}x${video.height}` : undefined,
+    status:
+      video.status === "completed"
+        ? "completed"
+        : video.status === "failed"
+          ? "failed"
+          : "processing",
+    review_status: video.review_status,
+    project_id: video.project_id,
+    // 后端 /videos 接口暂无 project_name 字段
+    project_name: undefined,
+    // 后端字段名为 generated_at，映射为 created_at 供前端统一使用
+    created_at: video.generated_at,
+    updated_at: video.generated_at,
+    // 后端 /videos 接口暂无 duplicate_rate 字段
+    duplicate_rate: undefined,
+  }
+}
@@ -0,0 +1,13 @@
+/**
+ * 项目 API — 目录化入口
+ * 保持与原 projects.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type { ProjectItem, BackendProjectResponse, BackendListProjectsResponse } from "./types"
+
+// 工具函数
+export { toProjectItem } from "./utils"
+
+// API 函数
+export { getProjects, createProject, getOrCreateDefaultProject } from "./projects"
@@ -1,32 +1,10 @@
 /**
- * 项目相关 API
+ * 项目相关 API 函数
 * 素材库需要 project_id，前端自动管理默认项目
 */
-import apiClient from "./client"
-
-export interface ProjectItem {
-  id: string
-  name: string
-  description: string
-}
-
-/** 后端 ProjectResponse 只返回 id, name, description */
-interface BackendProjectResponse {
-  id: string
-  name: string
-  description: string
-}
-
-/** 后端 ListProjectsResponse 返回 { items: [...] } */
-interface BackendListProjectsResponse {
-  items: BackendProjectResponse[]
-}
-
-const toProjectItem = (item: BackendProjectResponse): ProjectItem => ({
-  id: item.id,
-  name: item.name,
-  description: item.description,
-})
+import apiClient from "../client"
+import type { BackendListProjectsResponse, BackendProjectResponse, ProjectItem } from "./types"
+import { toProjectItem } from "./utils"

 /** 获取当前用户的项目列表 */
 export const getProjects = async (): Promise<ProjectItem[]> => {
@@ -0,0 +1,21 @@
+/**
+ * 项目相关类型定义
+ */
+
+export interface ProjectItem {
+  id: string
+  name: string
+  description: string
+}
+
+/** 后端 ProjectResponse 只返回 id, name, description */
+export interface BackendProjectResponse {
+  id: string
+  name: string
+  description: string
+}
+
+/** 后端 ListProjectsResponse 返回 { items: [...] } */
+export interface BackendListProjectsResponse {
+  items: BackendProjectResponse[]
+}
@@ -0,0 +1,10 @@
+/**
+ * 项目相关工具函数
+ */
+import type { BackendProjectResponse, ProjectItem } from "./types"
+
+export const toProjectItem = (item: BackendProjectResponse): ProjectItem => ({
+  id: item.id,
+  name: item.name,
+  description: item.description,
+})
@@ -0,0 +1,26 @@
+/**
+ * 订阅 API — 目录化入口
+ * 保持与原 subscription.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  PlanType,
+  SubscriptionStatus,
+  BillingStatus,
+  BillingCycle,
+  Plan,
+  SubscriptionInfo,
+  BillingRecord,
+  ChangePlanRequest,
+  ChangePlanResponse,
+} from "./types"
+
+// API 函数
+export {
+  getCurrentSubscription,
+  getBillingRecords,
+  changePlan,
+  cancelSubscription,
+  toggleAutoRenew,
+} from "./subscription"
@@ -0,0 +1,47 @@
+/**
+ * 订阅相关 API 函数
+ */
+import apiClient from "../client"
+import type {
+  BillingRecord,
+  ChangePlanRequest,
+  ChangePlanResponse,
+  SubscriptionInfo,
+} from "./types"
+
+/** 获取当前订阅信息 */
+export const getCurrentSubscription = async (): Promise<SubscriptionInfo> => {
+  const response = await apiClient.get("/subscription/current")
+  return response.data
+}
+
+/** 获取账单记录列表 */
+export const getBillingRecords = async (): Promise<BillingRecord[]> => {
+  const response = await apiClient.get("/subscription/billing-records")
+  return response.data
+}
+
+/** 升级/降级套餐 */
+export const changePlan = async (request: ChangePlanRequest): Promise<ChangePlanResponse> => {
+  const response = await apiClient.post("/subscription/change-plan", request)
+  return response.data
+}
+
+/** 取消订阅 */
+export const cancelSubscription = async (): Promise<{
+  success: boolean
+  message: string
+}> => {
+  const response = await apiClient.post("/subscription/cancel")
+  return response.data
+}
+
+/** 切换自动续费 */
+export const toggleAutoRenew = async (
+  enabled: boolean,
+): Promise<{ success: boolean; message: string }> => {
+  const response = await apiClient.post("/subscription/toggle-auto-renew", {
+    enabled,
+  })
+  return response.data
+}
@@ -1,8 +1,6 @@
 /**
- * 订阅 API 模块
- * 对接后端订阅管理接口
+ * 订阅相关类型定义
 */
-import apiClient from "./client"

 /** 套餐类型 */
 export type PlanType = "free" | "standard" | "pro" | "enterprise"
@@ -65,42 +63,3 @@ export interface ChangePlanResponse {
  message: string
  new_subscription?: SubscriptionInfo
 }
-
-// ============ API 函数 ============
-
-/** 获取当前订阅信息 */
-export const getCurrentSubscription = async (): Promise<SubscriptionInfo> => {
-  const response = await apiClient.get("/subscription/current")
-  return response.data
-}
-
-/** 获取账单记录列表 */
-export const getBillingRecords = async (): Promise<BillingRecord[]> => {
-  const response = await apiClient.get("/subscription/billing-records")
-  return response.data
-}
-
-/** 升级/降级套餐 */
-export const changePlan = async (request: ChangePlanRequest): Promise<ChangePlanResponse> => {
-  const response = await apiClient.post("/subscription/change-plan", request)
-  return response.data
-}
-
-/** 取消订阅 */
-export const cancelSubscription = async (): Promise<{
-  success: boolean
-  message: string
-}> => {
-  const response = await apiClient.post("/subscription/cancel")
-  return response.data
-}
-
-/** 切换自动续费 */
-export const toggleAutoRenew = async (
-  enabled: boolean,
-): Promise<{ success: boolean; message: string }> => {
-  const response = await apiClient.post("/subscription/toggle-auto-renew", {
-    enabled,
-  })
-  return response.data
-}
@@ -0,0 +1,10 @@
+/**
+ * 标签 API — 目录化入口
+ * 保持与原 tags.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type { TagItem } from "./types"
+
+// API 函数
+export { getTags, createTag, deleteTag, tagAsset, untagAsset } from "./tags"
@@ -1,15 +1,9 @@
 /**
- * 标签 CRUD API
+ * 标签 CRUD API 函数
 * P3 标签体系：对接后端标签表
 */
-import apiClient from "./client"
-
-export interface TagItem {
-  id: string
-  name: string
-  created_at?: string
-  usage_count?: number
-}
+import apiClient from "../client"
+import type { TagItem } from "./types"

 /** 获取当前用户所有标签 */
 export const getTags = async (): Promise<TagItem[]> => {
@@ -0,0 +1,10 @@
+/**
+ * 标签相关类型定义
+ */
+
+export interface TagItem {
+  id: string
+  name: string
+  created_at?: string
+  usage_count?: number
+}
@@ -0,0 +1,19 @@
+/**
+ * 任务相关 API — 目录化入口
+ * 保持与原 tasks.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  TaskStatus,
+  TaskType,
+  TaskErrorInfo,
+  TaskItem,
+  TaskListParams,
+  TaskListResponse,
+  CreateGenerationTaskRequest,
+  CreateGenerationTaskResponse,
+} from "./types"
+
+// API 函数
+export { createGenerationTask, getTasks, getUserTasks, getTask, retryTask } from "./tasks"
@@ -0,0 +1,46 @@
+/**
+ * 任务相关 API 函数
+ * 对接后端任务中心 API
+ */
+import apiClient from "../client"
+import type {
+  CreateGenerationTaskRequest,
+  CreateGenerationTaskResponse,
+  TaskItem,
+  TaskListParams,
+  TaskListResponse,
+} from "./types"
+
+/** 创建生成任务（智能剪辑） */
+export const createGenerationTask = async (
+  params: CreateGenerationTaskRequest,
+): Promise<CreateGenerationTaskResponse> => {
+  const { data } = await apiClient.post<CreateGenerationTaskResponse>("/generation/tasks", params)
+  return data
+}
+
+/** 获取任务列表（支持分页和筛选） */
+export const getTasks = async (params?: TaskListParams): Promise<TaskListResponse> => {
+  const { data } = await apiClient.get<TaskListResponse>("/tasks", {
+    params,
+  })
+  return data
+}
+
+/** 获取当前用户的所有任务（兼容旧接口，跨 project） */
+export const getUserTasks = async (): Promise<TaskItem[]> => {
+  const { data } = await apiClient.get("/tasks")
+  return data.items || data || []
+}
+
+/** 获取单个任务详情（含 error_info） */
+export const getTask = async (taskId: string): Promise<TaskItem> => {
+  const { data } = await apiClient.get(`/tasks/${taskId}`)
+  return data
+}
+
+/** 重试失败的任务 */
+export const retryTask = async (taskId: string): Promise<TaskItem> => {
+  const { data } = await apiClient.post(`/tasks/${taskId}/retry`)
+  return data
+}
@@ -1,14 +1,6 @@
 /**
- * 任务相关 API
- * 对接后端任务中心 API：
- * - POST /api/v1/generation/tasks — 创建生成任务
- * - GET  /api/v1/tasks              — 用户级任务列表（支持分页/筛选）
- * - GET  /api/v1/tasks/{task_id}    — 任务详情（含 error_info）
- * - POST /api/v1/tasks/{task_id}/retry — 重试失败任务
+ * 任务相关类型定义
 */
-import apiClient from "./client"
-
-/* ──────────── 类型定义 ──────────── */

 /** 任务状态 */
 export type TaskStatus = "pending" | "waiting" | "running" | "completed" | "failed" | "cancelled"
@@ -85,39 +77,3 @@ export interface CreateGenerationTaskResponse {
  result_count: number
  error_message: string
 }
-
-/* ──────────── API 函数 ──────────── */
-
-/** 创建生成任务（智能剪辑） */
-export const createGenerationTask = async (
-  params: CreateGenerationTaskRequest,
-): Promise<CreateGenerationTaskResponse> => {
-  const { data } = await apiClient.post<CreateGenerationTaskResponse>("/generation/tasks", params)
-  return data
-}
-
-/** 获取任务列表（支持分页和筛选） */
-export const getTasks = async (params?: TaskListParams): Promise<TaskListResponse> => {
-  const { data } = await apiClient.get<TaskListResponse>("/tasks", {
-    params,
-  })
-  return data
-}
-
-/** 获取当前用户的所有任务（兼容旧接口，跨 project） */
-export const getUserTasks = async (): Promise<TaskItem[]> => {
-  const { data } = await apiClient.get("/tasks")
-  return data.items || data || []
-}
-
-/** 获取单个任务详情（含 error_info） */
-export const getTask = async (taskId: string): Promise<TaskItem> => {
-  const { data } = await apiClient.get(`/tasks/${taskId}`)
-  return data
-}
-
-/** 重试失败的任务 */
-export const retryTask = async (taskId: string): Promise<TaskItem> => {
-  const { data } = await apiClient.post(`/tasks/${taskId}/retry`)
-  return data
-}
@@ -0,0 +1,28 @@
+/**
+ * AI 推荐 + 封面生成 API
+ */
+import apiClient from "../client"
+import type {
+  AIRecommendRequest,
+  AIRecommendResponse,
+  GenerateCoverRequest,
+  GenerateCoverResponse,
+} from "./types"
+
+/** AI 推荐片段方案 */
+export async function aiRecommendClips(
+  templateId: string,
+  data: AIRecommendRequest,
+): Promise<AIRecommendResponse> {
+  const response = await apiClient.post(`/templates/${templateId}/editor/ai-recommend`, data)
+  return response.data
+}
+
+/** AI 生成封面 */
+export async function generateCover(
+  templateId: string,
+  data: GenerateCoverRequest,
+): Promise<GenerateCoverResponse> {
+  const response = await apiClient.post(`/templates/${templateId}/editor/generate-cover`, data)
+  return response.data
+}
@@ -0,0 +1,99 @@
+/**
+ * 片段 CRUD + 批量操作 API
+ */
+import apiClient from "../client"
+import type {
+  EditPlanClip,
+  EditPlanClipListParams,
+  EditPlanClipListResponse,
+  CreateEditPlanClipRequest,
+  UpdateEditPlanClipRequest,
+  ClipReorderItem,
+  ClipReorderResponse,
+  ClipBatchDeleteResponse,
+  ClipsFromAssetsResponse,
+} from "./types"
+
+/** 获取片段列表 */
+export async function getEditPlanClips(
+  templateId: string,
+  params?: EditPlanClipListParams,
+): Promise<EditPlanClipListResponse> {
+  const response = await apiClient.get<EditPlanClipListResponse>(
+    `/templates/${templateId}/editor/clips`,
+    { params },
+  )
+  return response.data
+}
+
+/** 获取单个片段详情 */
+export async function getEditPlanClip(templateId: string, clipId: string): Promise<EditPlanClip> {
+  const response = await apiClient.get<EditPlanClip>(
+    `/templates/${templateId}/editor/clips/${clipId}`,
+  )
+  return response.data
+}
+
+/** 创建片段 */
+export async function createEditPlanClip(
+  templateId: string,
+  data: CreateEditPlanClipRequest,
+): Promise<EditPlanClip> {
+  const response = await apiClient.post<EditPlanClip>(`/templates/${templateId}/editor/clips`, data)
+  return response.data
+}
+
+/** 更新片段 */
+export async function updateEditPlanClip(
+  templateId: string,
+  clipId: string,
+  data: UpdateEditPlanClipRequest,
+): Promise<EditPlanClip> {
+  const response = await apiClient.put<EditPlanClip>(
+    `/templates/${templateId}/editor/clips/${clipId}`,
+    data,
+  )
+  return response.data
+}
+
+/** 删除片段 */
+export async function deleteEditPlanClip(templateId: string, clipId: string): Promise<void> {
+  await apiClient.delete(`/templates/${templateId}/editor/clips/${clipId}`)
+}
+
+/** 片段重排序（拖拽排序后一次性提交） */
+export async function reorderEditPlanClips(
+  templateId: string,
+  items: ClipReorderItem[],
+): Promise<ClipReorderResponse> {
+  const response = await apiClient.post<ClipReorderResponse>(
+    `/templates/${templateId}/editor/clips/reorder`,
+    { items },
+  )
+  return response.data
+}
+
+/** 批量删除片段 */
+export async function batchDeleteEditPlanClips(
+  templateId: string,
+  clipIds: string[],
+): Promise<ClipBatchDeleteResponse> {
+  const response = await apiClient.post<ClipBatchDeleteResponse>(
+    `/templates/${templateId}/editor/clips/batch-delete`,
+    { clip_ids: clipIds },
+  )
+  return response.data
+}
+
+/** 从素材批量创建片段（追加到时间线末尾） */
+export async function createClipsFromAssets(
+  templateId: string,
+  assetIds: string[],
+  clipType = "main",
+): Promise<ClipsFromAssetsResponse> {
+  const response = await apiClient.post<ClipsFromAssetsResponse>(
+    `/templates/${templateId}/editor/clips/from-assets`,
+    { asset_ids: assetIds, clip_type: clipType },
+  )
+  return response.data
+}
@@ -0,0 +1,66 @@
+/**
+ * 模板编辑器常量
+ */
+import type { TransitionEffect, EditPlanStatus } from "./types"
+
+/** 转场效果选项（14 种预设） */
+export const TRANSITION_OPTIONS: {
+  value: TransitionEffect["type"]
+  label: string
+  icon: string
+}[] = [
+  { value: "none", label: "无转场", icon: "⊘" },
+  { value: "cut", label: "硬切", icon: "✂" },
+  { value: "fade", label: "淡入淡出", icon: "◐" },
+  { value: "dissolve", label: "溶解", icon: "◈" },
+  { value: "zoom", label: "缩放", icon: "⊕" },
+  { value: "slide_left", label: "左滑", icon: "←" },
+  { value: "slide_right", label: "右滑", icon: "→" },
+  { value: "slide_up", label: "上滑", icon: "↑" },
+  { value: "slide_down", label: "下滑", icon: "↓" },
+  { value: "wipe_left", label: "左擦除", icon: "▸|" },
+  { value: "wipe_right", label: "右擦除", icon: "|◂" },
+  { value: "wipe_up", label: "上擦除", icon: "▴̄" },
+  { value: "wipe_down", label: "下擦除", icon: "▾̄" },
+  { value: "circlecrop", label: "圆形裁切", icon: "●" },
+  { value: "rectcrop", label: "矩形裁切", icon: "■" },
+]
+
+/** 素材类型标签 */
+export const MATERIAL_TYPE_LABELS: Record<string, string> = {
+  video: "视频",
+  image: "图片",
+  audio: "音频",
+  voiceover: "配音",
+}
+
+/** 素材类型图标 */
+export const MATERIAL_TYPE_ICONS: Record<string, string> = {
+  video: "🎬",
+  image: "🖼️",
+  audio: "🎵",
+  voiceover: "🎙️",
+}
+
+/** 计划状态标签 */
+export const PLAN_STATUS_LABELS: Record<EditPlanStatus, string> = {
+  draft: "草稿",
+  editing: "编辑中",
+  rendering: "渲染中",
+  completed: "已完成",
+  failed: "失败",
+  cancelled: "已取消",
+}
+
+/** 质量分筛选选项 */
+export const QUALITY_OPTIONS: {
+  value: string
+  label: string
+  min?: number
+  max?: number
+}[] = [
+  { value: "all", label: "全部质量" },
+  { value: "high", label: "高质量 (80-100)", min: 80, max: 100 },
+  { value: "medium", label: "中质量 (50-79)", min: 50, max: 79 },
+  { value: "low", label: "低质量 (0-49)", min: 0, max: 49 },
+]
@@ -0,0 +1,91 @@
+/**
+ * 模板草稿 CRUD + 生成相关 API
+ */
+import apiClient from "../client"
+import type {
+  EditPlan,
+  EditPlanListParams,
+  EditPlanListResponse,
+  CreateEditPlanRequest,
+  UpdateEditPlanRequest,
+  GenerateResponse,
+  GenerationStatusResponse,
+  EditPlanGeneration,
+  GeneratedVideo,
+  CopyEditPlanRequest,
+} from "./types"
+
+/** 获取模板草稿列表（支持分页和筛选） */
+export async function getEditPlans(params?: EditPlanListParams): Promise<EditPlanListResponse> {
+  const response = await apiClient.get<EditPlanListResponse>("/templates/drafts", {
+    params,
+  })
+  return response.data
+}
+
+/** 获取单个模板草稿 */
+export async function getEditPlan(templateId: string): Promise<EditPlan> {
+  const response = await apiClient.get(`/templates/${templateId}/editor`)
+  return response.data
+}
+
+/** 创建模板草稿 */
+export async function createEditPlan(data: CreateEditPlanRequest): Promise<EditPlan> {
+  const response = await apiClient.post("/templates/drafts", data)
+  return response.data
+}
+
+/** 更新模板草稿 */
+export async function updateEditPlan(
+  templateId: string,
+  data: UpdateEditPlanRequest,
+): Promise<EditPlan> {
+  const response = await apiClient.put(`/templates/${templateId}/editor`, data)
+  return response.data
+}
+
+/** 删除模板草稿 */
+export async function deleteEditPlan(templateId: string): Promise<void> {
+  await apiClient.delete(`/templates/${templateId}/editor`)
+}
+
+/** 触发生成 */
+export async function generateEditPlan(templateId: string): Promise<GenerateResponse> {
+  const response = await apiClient.post(`/templates/${templateId}/editor/generate`)
+  return response.data
+}
+
+/** 获取生成状态（轮询用） */
+export async function getGenerationStatus(templateId: string): Promise<GenerationStatusResponse> {
+  const response = await apiClient.get(`/templates/${templateId}/editor/generation-status`)
+  return response.data
+}
+
+/** 获取模板草稿关联的生成记录 */
+export async function getEditPlanGenerations(templateId: string): Promise<EditPlanGeneration[]> {
+  const response = await apiClient.get(`/templates/${templateId}/editor/generations`)
+  return response.data.items || []
+}
+
+/** 获取生成任务的视频结果列表 */
+export async function getGenerationTaskResults(taskId: string): Promise<GeneratedVideo[]> {
+  const response = await apiClient.get(`/generation/tasks/${taskId}/results`)
+  return response.data.items || response.data || []
+}
+
+/** 取消生成任务 */
+export async function cancelGeneration(templateId: string): Promise<void> {
+  await apiClient.post(`/templates/${templateId}/editor/cancel`)
+}
+
+/** 复制模板草稿（含所有片段配置） */
+export async function copyEditPlan(
+  templateId: string,
+  data?: CopyEditPlanRequest,
+): Promise<EditPlan> {
+  const response = await apiClient.post<EditPlan>(
+    `/templates/${templateId}/editor/copy`,
+    data || {},
+  )
+  return response.data
+}
@@ -0,0 +1,88 @@
+/**
+ * 模板编辑器 API — 按模块拆分后的统一入口
+ * 保持与原 template-editor.ts 相同的导出结构，向后兼容
+ */
+
+// 类型
+export type {
+  EditPlanStatus,
+  TitleConfig,
+  SubtitleConfig,
+  BgmConfig,
+  SegmentTtsConfig,
+  SegmentTrimConfig,
+  SegmentTransitionConfig,
+  EditPlanSegment,
+  EditPlanConfig,
+  EditPlan,
+  CreateEditPlanRequest,
+  UpdateEditPlanRequest,
+  EditPlanListParams,
+  EditPlanListResponse,
+  GenerateResponse,
+  EditPlanGeneration,
+  ClipStatusItem,
+  GenerationStatusResponse,
+  GeneratedVideo,
+  AIRecommendRequest,
+  AIRecommendClipItem,
+  AIRecommendResponse,
+  GenerateCoverRequest,
+  GenerateCoverResponse,
+  CoverResult,
+  EditPlanClipStatus,
+  EditPlanClip,
+  CreateEditPlanClipRequest,
+  UpdateEditPlanClipRequest,
+  EditPlanClipListResponse,
+  EditPlanClipListParams,
+  ClipReorderItem,
+  ClipReorderResponse,
+  ClipBatchDeleteResponse,
+  ClipsFromAssetsResponse,
+  CopyEditPlanRequest,
+  TransitionEffect,
+  MediaAsset,
+} from "./types"
+
+// 常量
+export {
+  TRANSITION_OPTIONS,
+  MATERIAL_TYPE_LABELS,
+  MATERIAL_TYPE_ICONS,
+  PLAN_STATUS_LABELS,
+  QUALITY_OPTIONS,
+} from "./constants"
+
+// 模板草稿 CRUD + 生成
+export {
+  getEditPlans,
+  getEditPlan,
+  createEditPlan,
+  updateEditPlan,
+  deleteEditPlan,
+  generateEditPlan,
+  getGenerationStatus,
+  getEditPlanGenerations,
+  getGenerationTaskResults,
+  cancelGeneration,
+  copyEditPlan,
+} from "./editPlans"
+
+// 片段 CRUD + 批量操作
+export {
+  getEditPlanClips,
+  getEditPlanClip,
+  createEditPlanClip,
+  updateEditPlanClip,
+  deleteEditPlanClip,
+  reorderEditPlanClips,
+  batchDeleteEditPlanClips,
+  createClipsFromAssets,
+} from "./clips"
+
+// AI 推荐 + 封面生成
+export { aiRecommendClips, generateCover } from "./aiFeatures"
+
+// 素材库
+export { getMediaAssets, getMediaAsset } from "./mediaAssets"
--- a/Show More
+++ b/Show More