test: cleanup workflow验证用临时PR

Co-authored-by: xiaoxia <dev@xiaoxiajianji.com>
Co-committed-by: xiaoxia <dev@xiaoxiajianji.com>

.flake8

@@ -1,14 +0,0 @@
-[flake8]
-max-line-length = 120
-exclude =
-    .git,
-    .cache,
-    __pycache__,
-    .venv,
-    venv,
-    node_modules,
-    alembic
-
-per-file-ignores =
-    tests/integration/*:F821
-    tests/unit/*:F821

.gitea/workflows/auto-approve.yml

@@ -0,0 +1,174 @@
+name: Auto Approve CI PRs
+
+on:
+  pull_request:
+    types: [synchronize, opened, ready_for_review]
+
+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
+    steps:
+      - name: Checkout code
+        shell: sh
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: "set -eu\npython3 - <<'PY'\nimport io, os, tarfile, time, urllib.request, urllib.error\nurl = f\"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz\"\nrequest = urllib.request.Request(url, headers={\"Authorization\": f\"token {os.environ['GITHUB_TOKEN']}\"})\nlast_err = None\nfor attempt in range(5):\n    try:\n        with urllib.request.urlopen(request, timeout=120) as response:\n            archive = response.read()\n        break\n    except urllib.error.HTTPError as e:\n        last_err = e\n        if e.code >= 500 and attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...\")\n            time.sleep(wait)\n            continue\n        raise\n    except Exception as e:\n        last_err = e\n        if attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...\")\n            time.sleep(wait)\n            continue\n        raise\nelse:\n    raise last_err\nwith tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:\n    root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'\n    for member in tar.getmembers():\n        name = member.name\n        if name == root_prefix[:-1]:\n            continue\n        if name.startswith(root_prefix):\n            member.name = name[len(root_prefix):]\n        if member.name:\n            tar.extract(member, '.')\nPY\n"
+
+      - name: Auto approve when CI passes
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          REVIEW_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+          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 / Unit Tests (pull_request)"
+              "CI/CD Pipeline / Frontend Lint (pull_request)"
+            )
+          fi
+
+          echo "需要通过的CI检查: ${#CONTEXTS[@]} 项"
+          for ctx in "${CONTEXTS[@]}"; do
+            echo "  - $ctx"
+          done
+          echo
+
+          # 初始等待30秒，给CI启动写status的时间，避免checkout太快导致全找不到context误判
+          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}"
+
+              # 检查是否已有审批（任何用户的APPROVED都算，避免重复审批）
+              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（Gitea API需要先创建再提交）
+              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
+
+              # 如果已经是APPROVED就不用再submit了（兼容不同Gitea版本）
+              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在跑（pending状态）→ 继续等
+            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

.gitea/workflows/auto-merge.yml

@@ -0,0 +1,170 @@
+name: Auto Merge CI PRs
+
+on:
+  pull_request:
+    types: [synchronize, opened, ready_for_review, review_requested]
+
+jobs:
+  auto-merge:
+    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
+    steps:
+      - name: Checkout code
+        shell: sh
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: "set -eu\npython3 - <<'PY'\nimport io, os, tarfile, time, urllib.request, urllib.error\nurl = f\"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz\"\nrequest = urllib.request.Request(url, headers={\"Authorization\": f\"token {os.environ['GITHUB_TOKEN']}\"})\nlast_err = None\nfor attempt in range(5):\n    try:\n        with urllib.request.urlopen(request, timeout=120) as response:\n            archive = response.read()\n        break\n    except urllib.error.HTTPError as e:\n        last_err = e\n        if e.code >= 500 and attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...\")\n            time.sleep(wait)\n            continue\n        raise\n    except Exception as e:\n        last_err = e\n        if attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...\")\n            time.sleep(wait)\n            continue\n        raise\nelse:\n    raise last_err\nwith tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:\n    root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'\n    for member in tar.getmembers():\n        name = member.name\n        if name == root_prefix[:-1]:\n            continue\n        if name.startswith(root_prefix):\n            member.name = name[len(root_prefix):]\n        if member.name:\n            tar.extract(member, '.')\nPY\n"
+
+      - name: Auto merge when CI passes and approved
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          MERGE_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          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 / Unit Tests (pull_request)"
+              "CI/CD Pipeline / Frontend Lint (pull_request)"
+              "CI/CD Pipeline / Integration Tests (pull_request)"
+            )
+            echo "检查全部四门禁"
+          fi
+          echo
+
+          # 初始等待30秒，给CI启动写status的时间，避免checkout太快导致全找不到context误判
+          echo "等待30秒让CI启动..."
+          sleep 30
+
+          # 405连续计数器：连续多次合并返回405才放弃
+          MERGE_405_COUNT=0
+          MAX_405_RETRIES=6
+
+          # 轮询等待，最多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全绿 + 审批通过，执行自动合并"
+
+              # 幂等检查：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 failed after multiple 405 errors: PR may have conflicts or unresolved checks. Please review manually."}' \
+                    "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null 2>&1 || true
+                  exit 1
+                fi
+              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

.gitea/workflows/ci-build.yml

@@ -4,17 +4,6 @@ on:
     branches:
     - main
     - develop
-    - feature/**
-    - feat/**
-    - bugfix/**
-    - fix/**
-    - hotfix/**
-    - release/**
-    - refactor/**
-    - perf/**
-    - docs/**
-    - chore/**
-    - ci/**
     tags:
     - v*
   pull_request:
@@ -35,7 +24,7 @@ concurrency:
 jobs:
   build-staging:
     name: Build Staging ${{ matrix.service_display }} Image
-    runs-on: host
+    runs-on: runtime-builder
     timeout-minutes: ${{ matrix.timeout }}
     if: github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'develop')
     strategy:
@@ -120,9 +109,13 @@ jobs:
       env:
         ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
         ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+        GITEA_REGISTRY_USER: xiaoxia
+        GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
       run: 'set -eu
 
         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}"
 
         echo "Docker login successful"
 
@@ -130,13 +123,9 @@ jobs:
     - name: Setup cache strategy
       shell: sh
       run: "set -eu\n# develop/main 分支写回缓存，其他分支只读\nif [ \"${GITHUB_REF_NAME}\" = \"develop\" ] || [ \"${GITHUB_REF_NAME}\" = \"main\" ]; then\n  echo \"CACHE_MODE=read-write\" >> $GITHUB_ENV\n  echo \"Cache mode: read-write (will push cache)\"\nelse\n  echo \"CACHE_MODE=read-only\" >> $GITHUB_ENV\n  echo \"Cache mode: read-only\"\nfi\n"
-    - name: Build frontend assets (npm build)
-      if: matrix.service == 'web'
-      shell: sh
-      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm           -v \"$PWD:/workspace\"           -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\"           -w /workspace/apps/web           docker.m.daocloud.io/library/node:20           sh -lc \"npm ci && npx tsc --incremental --tsBuildInfoFile node_modules/.tsbuildinfo && npx vite build\"\n\ntest -f apps/web/dist/index.html\necho \"Frontend build complete: $(ls apps/web/dist/ | head -5)\"\n"
     - name: Setup buildx builder (docker-container driver)
       shell: sh
-      run: "set -eu\n# 确保使用 docker-container driver 以支持 cache export 功能\nif ! docker buildx inspect ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB} > /dev/null 2>&1; then\n  docker buildx create --use --name ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB} --driver docker-container\n  echo \"Created ci-builder (docker-container driver)\"\nelse\n  docker buildx use ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB}\n  echo \"Using existing ci-builder\"\nfi\ndocker buildx inspect --bootstrap\n"
+      run: "set -eu\n# 确保使用 docker-container driver 以支持 cache export 功能\nif ! docker buildx inspect ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB}-${{ matrix.cache_name }} > /dev/null 2>&1; then\n  docker buildx create --use --name ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB}-${{ matrix.cache_name }} --driver docker-container\n  echo \"Created ci-builder (docker-container driver)\"\nelse\n  docker buildx use ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB}-${{ matrix.cache_name }}\n  echo \"Using existing ci-builder\"\nfi\ndocker buildx inspect --bootstrap\n"
     - name: Build and push ${{ matrix.service_display }} image (buildx cache)
       shell: sh
       run: "set -eu\nREGISTRY=\"xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji\"\nIMAGE_TAG=\"${REGISTRY}/${{ matrix.image_name }}:${GITHUB_SHA}\"\nCACHE_REF=\"${REGISTRY}/${{ matrix.cache_name }}:${GITHUB_REF_NAME}\"\n\nEXTRA_BUILD_ARGS=\"APP_VERSION=\\\"${GITHUB_SHA}\\\"\"\nif [ \"${{ matrix.service }}\" = \"web\" ]; then\n  EXTRA_BUILD_ARGS=\"$EXTRA_BUILD_ARGS NGINX_CONF=infra/docker/nginx-staging.conf\"\nfi\n\nbash scripts/ci/docker_build_push.sh  ${{ matrix.dockerfile }}  \"${IMAGE_TAG}\"  \"${CACHE_REF}\"  $EXTRA_BUILD_ARGS\n\necho\necho \"${{ matrix.service_display }} image pushed: ${IMAGE_TAG}\""
@@ -157,8 +146,11 @@ jobs:
         '
   deploy-staging:
     name: Deploy Staging (Watchtower auto-deploy)
-    runs-on: saas
+    runs-on: runtime-builder
     timeout-minutes: 15
+    concurrency:
+      group: deploy-staging-${{ gitea.ref }}
+      cancel-in-progress: false
     needs:
     - build-staging
     if: github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'develop')
@@ -232,9 +224,13 @@ jobs:
       env:
         ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
         ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+        GITEA_REGISTRY_USER: xiaoxia
+        GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
       run: 'set -eu
 
         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}"
 
         echo "Docker login successful"
 
@@ -308,7 +304,7 @@ jobs:
         '
   staging-e2e:
     name: Staging E2E Tests
-    runs-on: saas
+    runs-on: runtime-builder
     timeout-minutes: 15
     if: github.ref_name == 'develop' || github.ref_name == 'main'
     needs: deploy-staging
@@ -388,7 +384,7 @@ jobs:
         '
   staging-api-tests:
     name: Staging API Integration Tests
-    runs-on: saas
+    runs-on: runtime-builder
     timeout-minutes: 10
     if: github.ref_name == 'develop' || github.ref_name == 'main'
     needs: deploy-staging
@@ -468,7 +464,7 @@ jobs:
         '
   build-production:
     name: Build Production ${{ matrix.service_display }} Image
-    runs-on: host
+    runs-on: runtime-builder
     timeout-minutes: ${{ matrix.timeout }}
     needs:
     if: startsWith(github.ref, 'refs/tags/v')
@@ -554,20 +550,20 @@ jobs:
       env:
         ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
         ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+        GITEA_REGISTRY_USER: xiaoxia
+        GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
       run: 'set -eu
 
         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}"
 
         echo "Docker login successful"
 
         '
-    - name: Build frontend assets (npm build)
-      if: matrix.service == 'web'
-      shell: sh
-      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\nfi\n\ndocker run --rm           -v \"$PWD:/workspace\"           -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\"           -w /workspace/apps/web           docker.m.daocloud.io/library/node:20           sh -lc \"npm ci && npx tsc --incremental --tsBuildInfoFile node_modules/.tsbuildinfo && npx vite build\"\n\ntest -f apps/web/dist/index.html\necho \"Frontend build complete\"\n"
     - name: Setup buildx builder (docker-container driver)
       shell: sh
-      run: "set -eu\n# 确保使用 docker-container driver 以支持 cache export 功能\nif ! docker buildx inspect ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB} > /dev/null 2>&1; then\n  docker buildx create --use --name ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB} --driver docker-container\n  echo \"Created ci-builder (docker-container driver)\"\nelse\n  docker buildx use ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB}\n  echo \"Using existing ci-builder\"\nfi\ndocker buildx inspect --bootstrap\n"
+      run: "set -eu\n# 确保使用 docker-container driver 以支持 cache export 功能\nif ! docker buildx inspect ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB}-${{ matrix.cache_name }} > /dev/null 2>&1; then\n  docker buildx create --use --name ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB}-${{ matrix.cache_name }} --driver docker-container\n  echo \"Created ci-builder (docker-container driver)\"\nelse\n  docker buildx use ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB}-${{ matrix.cache_name }}\n  echo \"Using existing ci-builder\"\nfi\ndocker buildx inspect --bootstrap\n"
     - name: Build and push ${{ matrix.service_display }} image (buildx cache)
       shell: sh
       run: "set -eu\nREGISTRY=\"xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji\"\nIMAGE_TAG=\"${REGISTRY}/${{ matrix.image_name }}:${GITHUB_SHA}\"\nCACHE_REF=\"${REGISTRY}/${{ matrix.cache_name }}:${GITHUB_REF_NAME}\"\n\nbash scripts/ci/docker_build_push.sh  ${{ matrix.dockerfile }}  \"${IMAGE_TAG}\"  \"${CACHE_REF}\"  APP_VERSION=\"${GITHUB_SHA}\"\n\necho\necho \"${{ matrix.service_display }} image pushed: ${IMAGE_TAG}\""
@@ -592,8 +588,11 @@ jobs:
         '
   deploy-production:
     name: Deploy Production
-    runs-on: saas
+    runs-on: runtime-builder
     timeout-minutes: 30
+    concurrency:
+      group: deploy-production-${{ gitea.ref }}
+      cancel-in-progress: false
     if: startsWith(github.ref, 'refs/tags/v')
     needs:
     - build-production
@@ -735,7 +734,7 @@ jobs:
         '
   production-e2e:
     name: Production Browser E2E
-    runs-on: saas
+    runs-on: runtime-builder
     timeout-minutes: 15
     if: startsWith(github.ref, 'refs/tags/v')
     needs: deploy-production

.gitea/workflows/ci-cd.yml

@@ -4,17 +4,6 @@ on:
     branches:
     - main
     - develop
-    - feature/**
-    - feat/**
-    - bugfix/**
-    - fix/**
-    - hotfix/**
-    - release/**
-    - refactor/**
-    - perf/**
-    - docs/**
-    - chore/**
-    - ci/**
     tags:
     - v*
   pull_request:
@@ -30,13 +19,51 @@ on:
 permissions:
   contents: read
 concurrency:
-  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+  group: ci-cd-${{ gitea.event_name }}-${{ gitea.ref }}
   cancel-in-progress: true
 jobs:
+  check-frontend-only:
+    name: Check if frontend-only change
+    runs-on: ci-check
+    if: github.event_name == 'pull_request'
+    outputs:
+      skip_backend: ${{ steps.check.outputs.skip_backend }}
+    steps:
+    - name: Checkout code
+      shell: sh
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: "set -eu\npython3 - <<'PY'\nimport io, os, tarfile, time, urllib.request, urllib.error\nurl = f\"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz\"\nrequest = urllib.request.Request(url, headers={\"Authorization\": f\"token {os.environ['GITHUB_TOKEN']}\"})\nlast_err = None\nfor attempt in range(5):\n    try:\n        with urllib.request.urlopen(request, timeout=120) as response:\n            archive = response.read()\n        break\n    except urllib.error.HTTPError as e:\n        last_err = e\n        if e.code >= 500 and attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...\")\n            time.sleep(wait)\n            continue\n        raise\n    except Exception as e:\n        last_err = e\n        if attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...\")\n            time.sleep(wait)\n            continue\n        raise\nelse:\n    raise last_err\nwith tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:\n    root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'\n    for member in tar.getmembers():\n        name = member.name\n        if name == root_prefix[:-1]:\n            continue\n        if name.startswith(root_prefix):\n            member.name = name[len(root_prefix):]\n        if member.name:\n            tar.extract(member, '.')\nPY\n"
+    - name: Check changed files
+      id: check
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: |
+        set -eu
+        PR_NUMBER=$(echo "$GITHUB_REF" | sed 's|refs/pull/||; s|/.*||')
+        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
+          echo "skip_backend=true" >> $GITHUB_OUTPUT
+          echo "✅ 纯前端改动，跳过后端检查"
+        else
+          echo "skip_backend=false" >> $GITHUB_OUTPUT
+          echo "🔧 包含后端/公共变更，运行完整CI"
+        fi
+
   validate:
+    needs: check-frontend-only
+    if: always() && needs.check-frontend-only.outputs.skip_backend != 'true'
     name: Validate Code Quality And Tests
-    runs-on: host
+    runs-on: ci-check
     timeout-minutes: 10
+    permissions:
+      contents: write
     env:
       DATABASE_URL: postgresql+psycopg://postgres:postgres@127.0.0.1:5432/xiaoxia_saas
       USE_IN_MEMORY_DB: 'false'
@@ -77,6 +104,10 @@ jobs:
 
         python3 -m pip install -q -r requirements-dev.txt
 
+        # Force source install of black/isort to ensure consistent formatting
+        # across compiled/source installations on different machines
+        python3 -m pip install --no-binary :all: black==26.5.1 isort==8.0.1
+
         python3 -m black --version
 
         python3 -m isort --version-number
@@ -100,6 +131,12 @@ jobs:
     - name: Run code quality checks
       shell: sh
       run: "set -eu\n\nif [ \"$SCAN_MODE\" = \"incremental\" ]; then\n  echo \"=== Incremental scan mode ===\"\n\n  python3 -m compileall -q $CHANGED_PY_FILES\n\n  python3 -m black --check --fast $CHANGED_PY_FILES\n\n  python3 -m isort --check-only $CHANGED_PY_FILES\n\n  RUFF_FILES=$(echo \"$CHANGED_PY_FILES\" | tr ' ' '\\n' | grep -v '^scripts/' | tr '\\n' ' ')\n  if [ -n \"$RUFF_FILES\" ]; then\n    python3 -m ruff check $RUFF_FILES --statistics\n  else\n    echo \"No ruff-checkable files changed, skipping\"\n  fi\n\nelif [ \"$SCAN_MODE\" = \"skip_py\" ]; then\n  echo \"No Python files changed - skipping Python lint checks\"\n\nelse\n  echo \"=== Full scan mode ===\"\n\n  python3 -m compileall -q alembic apps packages tests scripts\n\n  python3 -m black --check --fast alembic apps packages tests scripts\n\n  python3 -m isort --check-only alembic apps packages tests scripts\n\n  python3 -m ruff check apps packages tests --statistics\nfi\n"
+    - name: Auto-fix formatting (black + isort)
+      if: failure()
+      shell: sh
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: python3 scripts/ci/auto_fix_formatting.py
     - name: Type check (mypy, hard gate)
       
       shell: sh
@@ -190,8 +227,10 @@ jobs:
 
         '
   unit-tests:
+    needs: check-frontend-only
+    if: always() && needs.check-frontend-only.outputs.skip_backend != 'true'
     name: Unit Tests
-    runs-on: host
+    runs-on: ci-l2
     timeout-minutes: 8
     env:
       USE_IN_MEMORY_DB: 'true'
@@ -231,9 +270,128 @@ jobs:
         pytest --version
 
         '
+    - name: Select incremental test files
+      if: github.event_name == 'pull_request'
+      shell: sh
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: |
+        set +e
+        PR_NUMBER=$(echo "$GITHUB_REF" | sed 's|refs/pull/||; s|/.*||')
+        API_URL="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?limit=300"
+        CHANGED_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) if f['status'] != 'removed']")
+        echo "改动文件数: $(echo "$CHANGED_FILES" | grep -c . || echo 0)"
+
+        CHANGED_FILES="$CHANGED_FILES" \
+        SELECTED_TESTS_OUTPUT=/tmp/selected_tests.txt \
+        python3 scripts/ci/select_unit_tests.py
+        SELECT_EXIT=$?
+
+        if [ $SELECT_EXIT -eq 0 ]; then
+          echo "UNIT_TEST_MODE=incremental" >> $GITHUB_ENV
+          TEST_FILES=$(cat /tmp/selected_tests.txt | tr '\n' ' ')
+          echo "SELECTED_TEST_FILES=$TEST_FILES" >> $GITHUB_ENV
+          echo "增量模式: $(cat /tmp/selected_tests.txt | wc -l) 个测试文件"
+        else
+          echo "UNIT_TEST_MODE=full" >> $GITHUB_ENV
+          echo "SELECTED_TEST_FILES=tests/unit" >> $GITHUB_ENV
+          echo "全量模式"
+        fi
+
     - name: Run unit tests with coverage
       shell: sh
-      run: "set -eu\nPYTHONPATH=\"$PWD/apps/api:$PWD\" python3 -m coverage run \\\n  --source=apps/api/app,packages \\\n  --omit=\"*/migrations/*,*/tests/*,*/test_*.py,*/site-packages/*\" \\\n  --branch \\\n  -m pytest tests/unit -q\npython3 -m coverage report --show-missing\npython3 -m coverage xml -o coverage.xml\npython3 -m coverage report --fail-under=60 > /dev/null\n"
+      run: |
+        set -eu
+        if [ "${UNIT_TEST_MODE:-full}" = "incremental" ]; then
+          echo "=== 增量测试模式 ==="
+          PYTHONPATH="$PWD/apps/api:$PWD" python3 -m coverage run \
+            --source=apps/api/app,packages \
+            --omit="*/migrations/*,*/tests/*,*/test_*.py,*/site-packages/*" \
+            --branch \
+            -m pytest $SELECTED_TEST_FILES -q
+          python3 -m coverage report --show-missing
+          python3 -m coverage xml -o coverage.xml
+          # 增量模式下调低覆盖率门槛（跑的文件少覆盖率自然低，不做强校验）
+          python3 -m coverage report --fail-under=10 > /dev/null || true
+        else
+          PYTHONPATH="$PWD/apps/api:$PWD" python3 -m coverage run \
+            --source=apps/api/app,packages \
+            --omit="*/migrations/*,*/tests/*,*/test_*.py,*/site-packages/*" \
+            --branch \
+            -m pytest tests/unit -q
+          python3 -m coverage report --show-missing
+          python3 -m coverage xml -o coverage.xml
+          python3 -m coverage report --fail-under=65 > /dev/null
+        fi
+    - name: Diff coverage check (增量行覆盖率)
+      if: github.event_name == 'pull_request' && env.HAS_APP_CHANGES == 'true'
+      shell: sh
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: |
+        set -eu
+        PR_NUMBER=$(echo "$GITHUB_REF" | sed 's|refs/pull/||; s|/.*||')
+        
+        # 获取base分支
+        BASE_BRANCH="${{ github.base_ref }}"
+        echo "Base branch: $BASE_BRANCH"
+        
+        # 初始化git (CI tarball checkout没有.git目录)
+        # 先备份PR代码，再基于base分支建分支，确保HEAD与base有共同祖先
+        PR_CODE_DIR="/tmp/pr-code-$$"
+        mkdir -p "$PR_CODE_DIR"
+        # 排除隐藏文件（如.env）和后续生成的coverage文件，只备份源码
+        find . -maxdepth 1 -mindepth 1 ! -name 'coverage.xml' ! -name 'diff_coverage.html' -exec cp -r {} "$PR_CODE_DIR/" \;
+        
+        rm -rf .git
+        git init > /dev/null 2>&1
+        git remote add origin https://git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas.git > /dev/null 2>&1
+        git config user.email "ci@local"
+        git config user.name "CI"
+        # 拉取base分支用于对比
+        git fetch origin $BASE_BRANCH --depth=200
+        # 基于base分支创建当前分支，确保有共同祖先
+        git checkout -b ci-pr-branch "origin/$BASE_BRANCH" > /dev/null 2>&1
+        # 清除base分支的源码，用PR代码覆盖
+        find . -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +
+        cp -r "$PR_CODE_DIR"/. .
+        rm -rf "$PR_CODE_DIR"
+        # 提交当前代码
+        git add -A > /dev/null 2>&1
+        git commit -m "ci-tmp" > /dev/null 2>&1
+        
+        # 根据模式设置门槛
+        if [ "${UNIT_TEST_MODE:-full}" = "incremental" ]; then
+          # 增量测试模式覆盖不全，门槛设低一些
+          THRESHOLD=40
+          echo "增量测试模式，增量覆盖率门槛: ${THRESHOLD}%"
+        else
+          THRESHOLD=60
+          echo "全量测试模式，增量覆盖率门槛: ${THRESHOLD}%"
+        fi
+        
+        # 运行diff-cover
+        set +e
+        python3 -m diff_cover.diff_cover_tool coverage.xml \
+          --compare-branch="origin/$BASE_BRANCH" \
+          --fail-under=$THRESHOLD \
+          --html-report diff_coverage.html \
+          2>&1
+        DIFF_EXIT=$?
+        set -e
+        
+        if [ $DIFF_EXIT -ne 0 ]; then
+          echo ""
+          echo "❌ 增量覆盖率未达到门槛 (${THRESHOLD}%)"
+          echo "   请为改动的代码添加单元测试后再提交"
+          echo ""
+          echo "=== 覆盖率报告 ==="
+          python3 -m diff_cover.diff_cover_tool coverage.xml \
+            --compare-branch="origin/$BASE_BRANCH" 2>&1 | tail -30
+          exit 1
+        fi
+        
+        echo "✅ 增量覆盖率达标"
     - name: CI failure notification
       if: failure()
       shell: sh
@@ -262,10 +420,12 @@ jobs:
         '
   integration-tests:
     name: Integration Tests
-    runs-on: host
+    runs-on: ci-l2
     timeout-minutes: 30
-    if: always()
-    needs: validate
+    if: always() && needs.check-frontend-only.outputs.skip_backend != 'true'
+    needs:
+      - check-frontend-only
+      - validate
     env:
       DATABASE_URL: postgresql+psycopg://postgres:postgres@127.0.0.1:5432/xiaoxia_saas
       USE_IN_MEMORY_DB: 'false'
@@ -379,7 +539,7 @@ jobs:
         '
   frontend-lint:
     name: Frontend Lint
-    runs-on: host
+    runs-on: ci-check
     timeout-minutes: 10
     steps:
     - name: Checkout code
@@ -402,7 +562,7 @@ jobs:
       run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'PACKAGE_LOCK_HASH=$(md5sum package-lock.json 2>/dev/null | cut -d\" \" -f1)\nCACHE_HASH_FILE=\"node_modules/.package-lock-hash\"\nCACHE_VALID=false\nif [ -f \"$CACHE_HASH_FILE\" ] && [ \"$(cat \"$CACHE_HASH_FILE\")\" = \"$PACKAGE_LOCK_HASH\" ] && [ -x \"node_modules/.bin/eslint\" ] && [ -x \"node_modules/.bin/tsc\" ] && [ -x \"node_modules/.bin/prettier\" ] && [ -x \"node_modules/.bin/vitest\" ]; then\n  CACHE_VALID=true\n  echo \"Cache hit: dependencies valid, skipping npm ci\"\nfi\nif [ \"$CACHE_VALID\" = \"false\" ]; then\n  echo \"Cache miss or invalid: running npm ci...\"\n  if ! npm ci --include=dev; then\n    echo \"npm ci failed, cleaning node_modules and retrying...\"\n    rm -rf node_modules\n    mkdir -p node_modules\n    npm ci --include=dev\n  fi\n  # Post-install integrity check: verify all critical tools exist\n  if [ ! -x \"node_modules/.bin/eslint\" ] || [ ! -x \"node_modules/.bin/tsc\" ] || [ ! -x \"node_modules/.bin/prettier\" ] || [ ! -x \"node_modules/.bin/vitest\" ]; then\n    echo \"Post-install check failed: critical binaries missing, cleaning and retrying...\"\n    rm -rf node_modules\n    mkdir -p node_modules\n    npm ci --include=dev\n  fi\n  echo \"$PACKAGE_LOCK_HASH\" > \"$CACHE_HASH_FILE\"\n  echo \"Dependencies installed, cache updated\"\nfi'\n"
     - name: Run ESLint
       shell: sh
-      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'npx --no-install eslint src --ext .ts,.tsx --max-warnings 50'\n"
+      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'npx --no-install eslint src --ext .ts,.tsx --max-warnings 0'\n"
     - name: Run TypeScript type check
       shell: sh
       run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'npx --no-install tsc --noEmit'\n"
@@ -426,4 +586,4 @@ jobs:
 
         NOTIFY_MODE=failure JOB_NAME="Frontend Lint" python3 scripts/ci_notify.py
 
-        '
+        '

.gitea/workflows/ci-trigger-monitor.yml

@@ -0,0 +1,36 @@
+name: CI Trigger Monitor
+
+on:
+  schedule:
+    - cron: '*/5 * * * *'  # 每5分钟检查一次
+  workflow_dispatch:
+    inputs:
+      stale_threshold:
+        description: 'CI未触发告警阈值（分钟）'
+        required: false
+        default: '5'
+
+permissions:
+  contents: read
+
+jobs:
+  monitor:
+    name: Monitor CI Trigger Reliability
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      
+      - name: Check CI trigger status for all open PRs
+        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 }}
+          STALE_THRESHOLD_MIN: ${{ inputs.stale_threshold || 5 }}
+        run: |
+          set +e
+          python3 scripts/ci_trigger_monitor.py
+          # 监控脚本永远不fail，避免告警风暴
+          exit 0

.gitea/workflows/code-review.yml

@@ -0,0 +1,53 @@
+name: AI Code Review
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+# 同一个 PR 只跑一个 review，新的取消旧的
+concurrency:
+  group: code-review-${{ gitea.repository }}-${{ gitea.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  code-review:
+    name: AI Code Review
+    runs-on: ubuntu-latest
+    # 跳过草稿 PR
+    if: ${{ !gitea.event.pull_request.draft }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Install dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install requests
+
+      - name: Run AI Code Review
+        env:
+          # Gitea 配置（自动从运行环境获取）
+          GITEA_API_URL: ${{ gitea.server_url }}
+          GITEA_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+          REPO_NAME: ${{ gitea.repository }}
+          PR_NUMBER: ${{ gitea.event.pull_request.number }}
+          # LLM 提供商: coze (扣子原生Bot) / openai (OpenAI兼容)
+          LLM_PROVIDER: "coze"
+          # 扣子模式配置（默认国内站 api.coze.cn）
+          LLM_BASE_URL: ${{ secrets.LLM_BASE_URL }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          COZE_BOT_ID: ${{ secrets.COZE_BOT_ID }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          # 可选参数
+          MAX_DIFF_CHARS: "30000"
+          LLM_TIMEOUT: "120"
+        run: |
+          python3 scripts/ci_code_review.py
+        # 审查脚本异常不影响 CI 通过
+        continue-on-error: true

.gitea/workflows/preview-cleanup.yml

@@ -0,0 +1,149 @@
+name: Preview Cleanup
+on:
+  pull_request:
+    types:
+    - closed
+    branches:
+    - main
+    - develop
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  cleanup-preview:
+    name: Cleanup Preview Environment
+    runs-on: runtime-builder
+    timeout-minutes: 10
+    steps:
+    - name: Extract PR number
+      shell: sh
+      run: |
+        set -eu
+        # 优先从event payload中读取（兼容所有PR事件类型）
+        if [ -n "${GITHUB_EVENT_PATH:-}" ] && [ -f "$GITHUB_EVENT_PATH" ]; then
+          PR_NUMBER=$(python3 -c "import json,sys; print(json.load(sys.stdin).get('number',''))" < "$GITHUB_EVENT_PATH")
+        fi
+        # fallback: 从GITHUB_REF中提取
+        if [ -z "${PR_NUMBER:-}" ]; then
+          PR_NUMBER=$(echo "$GITHUB_REF" | sed -n 's|refs/pull/\([0-9]*\)/.*|\1|p')
+        fi
+        # 再fallback: 兼容纯数字ref
+        if [ -z "${PR_NUMBER:-}" ] || ! echo "$PR_NUMBER" | grep -qE '^[0-9]+$'; then
+          echo "WARNING: Could not extract PR number cleanly, using raw ref suffix"
+          PR_NUMBER=$(echo "$GITHUB_REF" | sed 's|refs/pull/||; s|/.*||')
+        fi
+        echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
+        echo "PR number: $PR_NUMBER"
+        echo "Preview dir: /var/www/preview/pr-${PR_NUMBER}"
+
+    - name: Install SSH client
+      shell: sh
+      run: |
+        set -eu
+        # 先检查是否已存在ssh
+        if command -v ssh >/dev/null 2>&1 && command -v ssh-keyscan >/dev/null 2>&1; then
+          echo "SSH client already available: $(ssh -V 2>&1)"
+          exit 0
+        fi
+        # 尝试多种包管理器安装
+        if command -v apk >/dev/null 2>&1; then
+          apk add --no-cache openssh-client >/dev/null 2>&1
+          echo "openssh-client installed via apk"
+        elif command -v apt-get >/dev/null 2>&1; then
+          apt-get update -qq && apt-get install -y -qq openssh-client >/dev/null 2>&1
+          echo "openssh-client installed via apt-get"
+        elif command -v yum >/dev/null 2>&1; then
+          yum install -y openssh-clients >/dev/null 2>&1
+          echo "openssh-client installed via yum"
+        elif command -v dnf >/dev/null 2>&1; then
+          dnf install -y openssh-clients >/dev/null 2>&1
+          echo "openssh-client installed via dnf"
+        else
+          echo "ERROR: No package manager found and ssh not pre-installed"
+          which ssh 2>/dev/null || echo "  ssh: not found"
+          which ssh-keyscan 2>/dev/null || echo "  ssh-keyscan: not found"
+          exit 1
+        fi
+
+    - name: Remove preview directory from server
+      shell: sh
+      env:
+        PREVIEW_SSH_HOST: ${{ secrets.PREVIEW_SSH_HOST }}
+        PREVIEW_SSH_USER: ${{ secrets.PREVIEW_SSH_USER }}
+        PREVIEW_SSH_PORT: ${{ secrets.PREVIEW_SSH_PORT }}
+        PREVIEW_SSH_KEY: ${{ secrets.PREVIEW_SSH_KEY }}
+      run: |
+        set -eux
+        preview_host="${PREVIEW_SSH_HOST:-172.30.18.197}"
+        preview_user="${PREVIEW_SSH_USER:-deploy}"
+        preview_port="${PREVIEW_SSH_PORT:-22222}"
+        preview_dir="/var/www/preview/pr-${PR_NUMBER}"
+
+        mkdir -p ~/.ssh
+
+        # 查找可用的SSH密钥
+        key_path=""
+        if [ -f /root/.ssh/xiaoxia_runtime_builder ]; then
+          key_path="/root/.ssh/xiaoxia_runtime_builder"
+          echo "Using key: $key_path (builder key)"
+        elif [ -f "$HOME/.ssh/xiaoxia_runtime_builder" ]; then
+          key_path="$HOME/.ssh/xiaoxia_runtime_builder"
+          echo "Using key: $key_path (home key)"
+        elif [ -n "${PREVIEW_SSH_KEY:-}" ]; then
+          key_path="$HOME/.ssh/id_ed25519"
+          printf '%s\n' "$PREVIEW_SSH_KEY" > "$key_path"
+          chmod 600 "$key_path"
+          echo "Using key from PREVIEW_SSH_KEY secret"
+        else
+          echo "ERROR: No SSH key available"
+          ls -la ~/.ssh/ 2>/dev/null || true
+          ls -la /root/.ssh/ 2>/dev/null || true
+          exit 1
+        fi
+
+        ssh-keyscan -p "$preview_port" -H "$preview_host" >> ~/.ssh/known_hosts 2>/dev/null
+        echo "SSH keyscan done"
+
+        # 测试SSH连接
+        ssh -p "$preview_port" -i "$key_path" -o StrictHostKeyChecking=no "${preview_user}@${preview_host}" "echo SSH_CONNECTION_OK && hostname"
+        echo "SSH connection verified"
+
+        # 检查目录是否存在
+        DIR_EXISTS=$(ssh -p "$preview_port" -i "$key_path" -o StrictHostKeyChecking=no "${preview_user}@${preview_host}" \
+          "if [ -d '${preview_dir}' ]; then echo 'yes'; else echo 'no'; fi")
+
+        if [ "$DIR_EXISTS" = "yes" ]; then
+          echo "Removing preview directory: ${preview_dir}"
+          ssh -p "$preview_port" -i "$key_path" -o StrictHostKeyChecking=no "${preview_user}@${preview_host}" \
+            "rm -rf ${preview_dir} && echo 'Preview directory removed successfully'"
+          echo "Cleanup completed: ${preview_dir}"
+        else
+          echo "Preview directory does not exist: ${preview_dir}, nothing to clean up"
+        fi
+
+    - name: Comment cleanup notice on PR
+      if: success()
+      shell: sh
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: |
+        set -eu
+        # 从event payload读取PR号（最可靠）
+        if [ -n "${GITHUB_EVENT_PATH:-}" ] && [ -f "$GITHUB_EVENT_PATH" ]; then
+          PR_NUMBER=$(python3 -c "import json,sys; print(json.load(sys.stdin).get('number',''))" < "$GITHUB_EVENT_PATH")
+        else
+          PR_NUMBER=$(echo "$GITHUB_REF" | sed -n 's|refs/pull/\([0-9]*\)/.*|\1|p')
+        fi
+        export PR_NUMBER
+
+        COMMENT_BODY=$(python3 scripts/ci/preview_comment.py cleanup)
+
+        API_URL="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments"
+        curl -s -X POST \
+          -H "Authorization: token ${GITHUB_TOKEN}" \
+          -H "Content-Type: application/json" \
+          -d "$COMMENT_BODY" \
+          "$API_URL" \
+          > /dev/null
+        echo "Cleanup comment posted"
+

.gitea/workflows/preview-deploy.yml

@@ -0,0 +1,274 @@
+name: Preview Deploy
+on:
+  pull_request:
+    types:
+    - opened
+    - synchronize
+    - reopened
+    branches:
+    - main
+    - develop
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: "触发原因"
+        required: false
+        default: "手动触发 - 预览环境补跑"
+permissions:
+  contents: read
+  pull-requests: write
+concurrency:
+  group: preview-deploy-${{ gitea.ref }}
+  cancel-in-progress: true
+jobs:
+  deploy-preview:
+    name: Deploy Preview Environment
+    runs-on: runtime-builder
+    timeout-minutes: 20
+    steps:
+    - name: Checkout code
+      shell: sh
+      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
+
+    - name: Record job start time
+      shell: sh
+      run: |
+        set -eu
+        echo "JOB_START_TIME=$(date +%s)" >> $GITHUB_ENV
+        echo "Job started at $(date)"
+
+    - name: Extract PR number
+      shell: sh
+      run: |
+        set -eu
+        PR_NUMBER=$(echo "$GITHUB_REF" | sed 's|refs/pull/||; s|/.*||')
+        echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
+        echo "PR number: $PR_NUMBER"
+        echo "PREVIEW_URL=https://pr-${PR_NUMBER}.preview.xiaoxiajianji.com" >> $GITHUB_ENV
+        echo "Preview URL: https://pr-${PR_NUMBER}.preview.xiaoxiajianji.com"
+
+    - name: Build frontend
+      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
+
+        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/
+          '
+
+    - name: Install SSH client and rsync
+      shell: sh
+      run: |
+        set -eu
+        if command -v apk >/dev/null 2>&1; then
+          apk add --no-cache openssh-client rsync >/dev/null 2>&1
+        elif command -v apt-get >/dev/null 2>&1; then
+          apt-get update -qq && apt-get install -y -qq openssh-client rsync >/dev/null 2>&1
+        elif command -v yum >/dev/null 2>&1; then
+          yum install -y openssh-clients rsync >/dev/null 2>&1
+        else
+          echo "ERROR: No package manager found"
+          exit 1
+        fi
+        echo "openssh-client and rsync installed"
+
+    - name: Deploy preview to server
+      shell: sh
+      env:
+        PREVIEW_SSH_HOST: ${{ secrets.PREVIEW_SSH_HOST }}
+        PREVIEW_SSH_USER: ${{ secrets.PREVIEW_SSH_USER }}
+        PREVIEW_SSH_PORT: ${{ secrets.PREVIEW_SSH_PORT }}
+        PREVIEW_SSH_KEY: ${{ secrets.PREVIEW_SSH_KEY }}
+      run: |
+        set -eux
+        preview_host="${PREVIEW_SSH_HOST:-172.30.18.197}"
+        preview_user="${PREVIEW_SSH_USER:-deploy}"
+        preview_port="${PREVIEW_SSH_PORT:-22222}"
+        preview_dir="/var/www/preview/pr-${PR_NUMBER}"
+
+        mkdir -p ~/.ssh
+
+        # 查找可用的SSH密钥
+        key_path=""
+        if [ -f /root/.ssh/xiaoxia_runtime_builder ]; then
+          key_path="/root/.ssh/xiaoxia_runtime_builder"
+          echo "Using key: $key_path (builder key)"
+        elif [ -f "$HOME/.ssh/xiaoxia_runtime_builder" ]; then
+          key_path="$HOME/.ssh/xiaoxia_runtime_builder"
+          echo "Using key: $key_path (home key)"
+        elif [ -n "${PREVIEW_SSH_KEY:-}" ]; then
+          key_path="$HOME/.ssh/id_ed25519"
+          printf '%s\n' "$PREVIEW_SSH_KEY" > "$key_path"
+          chmod 600 "$key_path"
+          echo "Using key from PREVIEW_SSH_KEY secret"
+        else
+          echo "ERROR: No SSH key available"
+          ls -la ~/.ssh/ 2>/dev/null || true
+          ls -la /root/.ssh/ 2>/dev/null || true
+          exit 1
+        fi
+
+        ssh-keyscan -p "$preview_port" -H "$preview_host" >> ~/.ssh/known_hosts 2>/dev/null
+        echo "SSH keyscan done"
+
+        # 测试SSH连接
+        ssh -p "$preview_port" -i "$key_path" -o StrictHostKeyChecking=no "${preview_user}@${preview_host}" "echo SSH_CONNECTION_OK && hostname"
+        echo "SSH connection verified"
+
+        # 创建预览目录并上传文件
+        ssh -p "$preview_port" -i "$key_path" -o StrictHostKeyChecking=no "${preview_user}@${preview_host}" \
+          "mkdir -p ${preview_dir} && echo 'Preview directory created: ${preview_dir}'"
+
+        # 使用rsync上传dist目录内容
+        rsync -avz --delete -e "ssh -p ${preview_port} -i ${key_path} -o StrictHostKeyChecking=no" \
+          apps/web/dist/ \
+          "${preview_user}@${preview_host}:${preview_dir}/"
+
+        echo "Preview deployed to: ${preview_dir}"
+        echo "Preview URL: https://pr-${PR_NUMBER}.preview.xiaoxiajianji.com"
+
+    - name: Comment preview link on PR
+      shell: sh
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: |
+        set -eu
+        PR_NUMBER=$(echo "$GITHUB_REF" | sed 's|refs/pull/||; s|/.*||')
+        PREVIEW_URL="https://pr-${PR_NUMBER}.preview.xiaoxiajianji.com"
+        export PR_NUMBER PREVIEW_URL
+
+        COMMENT_BODY=$(python3 scripts/ci/preview_comment.py deploy)
+
+        API_URL="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments"
+
+        EXISTING_COMMENT_ID=$(curl -s -H "Authorization: token ${GITHUB_TOKEN}" "$API_URL" | python3 -c "
+        import sys, json
+        try:
+            for c in json.load(sys.stdin):
+                if '预览环境已部署' in c.get('body', ''):
+                    print(c['id'])
+                    break
+        except Exception:
+            pass
+        ")
+
+        if [ -n "$EXISTING_COMMENT_ID" ]; then
+          curl -s -X PATCH \
+            -H "Authorization: token ${GITHUB_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "$COMMENT_BODY" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/comments/${EXISTING_COMMENT_ID}" \
+            > /dev/null
+          echo "Comment updated"
+        else
+          curl -s -X POST \
+            -H "Authorization: token ${GITHUB_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "$COMMENT_BODY" \
+            "$API_URL" \
+            > /dev/null
+          echo "Comment posted"
+        fi
+
+    - name: Job duration summary
+      if: always()
+      shell: sh
+      run: |
+        set +eu
+        if [ -n "$JOB_START_TIME" ]; then
+          END_TIME=$(date +%s)
+          DURATION=$((END_TIME - JOB_START_TIME))
+          MINS=$((DURATION / 60))
+          SECS=$((DURATION % 60))
+          echo "JOB_DURATION_SECONDS=$DURATION" >> $GITHUB_ENV
+          echo "=== Job Duration: ${MINS}m${SECS}s ==="
+        else
+          echo "JOB_DURATION_SECONDS=0" >> $GITHUB_ENV
+          echo "=== Job Duration: unknown ==="
+        fi
+
+    - 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="Deploy Preview Environment" python3 scripts/ci_notify.py

.gitignore

@@ -49,3 +49,7 @@ build/
 tracker_tasks.json
 
 frontend-v21-ui-prototype-final.html
+
+!.vscode/
+!.vscode/settings.json
+.vscode/extensions.json

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 26.5.1
+    hooks:
+      - id: black
+        language_version: python3.12
+
+  - repo: https://github.com/pycqa/isort
+    rev: 8.0.1
+    hooks:
+      - id: isort
+        args: ["--profile", "black"]
+        language_version: python3.12
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+        language_version: python3.12

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+  "[python]": {
+    "editor.defaultFormatter": "ms-python.black-formatter",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.organizeImports": "explicit"
+    }
+  },
+  "isort.args": ["--profile", "black"],
+  "python.linting.ruffEnabled": true,
+  "python.analysis.typeCheckingMode": "basic"
+}

alembic/versions/042_add_storage_key_to_assets.py

@@ -0,0 +1,29 @@
+"""add storage_key to assets
+
+Revision ID: 042_storage_key
+Revises: 041_result_count
+Create Date: 2026-07-17 18:10:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "042_storage_key"
+down_revision = "041_result_count"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "assets",
+        sa.Column("storage_key", sa.String(500), nullable=False, server_default=""),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("assets", "storage_key")

apps/api/app/api/routes/_helpers.py

@@ -46,3 +46,97 @@ def require_project_and_library(
     libraries = asset_library_repository.find_by_project(project_id)
     if not any(item.id == library_id for item in libraries):
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Asset library not found")
+
+
+def auto_select_video_assets(
+    *,
+    project_id: str,
+    asset_library_repo: Any,
+    asset_repo: Any,
+    logger=None,
+) -> list[str]:
+    """从项目视频素材库自动选取 ready 状态的视频素材。
+
+    Args:
+        project_id: 项目 ID
+        asset_library_repo: 素材库仓储
+        asset_repo: 素材仓储
+        logger: 可选的 logger 实例，用于记录警告
+
+    Returns:
+        选中的素材 ID 列表，无可用素材时返回空列表
+    """
+    # 明确不支持的视频编码（会导致渲染失败）
+    UNSUPPORTED_CODECS = {"hevc", "h265", "hev1", "hvc1", "vp9", "vp09", "av1", "av01"}
+
+    if not project_id:
+        return []
+
+    # 找到项目的视频素材库
+    libs = asset_library_repo.find_by_project(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 not video_lib:
+        if logger:
+            logger.warning("自动选素材: 项目 %s 无视频素材库", project_id)
+        return []
+
+    # 从素材库中选取 ready 状态的视频素材
+    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")
+    ]
+
+    # 过滤不支持的编码格式（HEVC/VP9/AV1 等会导致渲染失败）
+    # 优先读 asset.codec 字段，其次从 metadata 里取（兼容存量数据）
+    codec_filtered = []
+    skipped_codec = 0
+    for a in ready_videos:
+        codec = (a.codec or "").lower()
+        if not codec and a.metadata and isinstance(a.metadata, dict):
+            codec = str(a.metadata.get("codec", "")).lower()
+        if codec and codec in UNSUPPORTED_CODECS:
+            skipped_codec += 1
+            continue
+        codec_filtered.append(a)
+
+    if skipped_codec and logger:
+        logger.warning("自动选素材: 跳过 %d 个不支持编码的素材", skipped_codec)
+
+    # 过滤横屏素材（只保留竖屏/正方形）
+    # 移动端短视频场景默认竖屏，横屏素材裁剪后画面不可用
+    filtered_videos = []
+    skipped_landscape = 0
+    for a in codec_filtered:
+        width = a.width if hasattr(a, "width") and a.width else 0
+        height = a.height if hasattr(a, "height") and a.height else 0
+        if not width or not height:
+            # 从 metadata 兜底
+            if a.metadata and isinstance(a.metadata, dict):
+                width = int(a.metadata.get("width", 0) or 0)
+                height = int(a.metadata.get("height", 0) or 0)
+        if width and height and width > height:
+            skipped_landscape += 1
+            continue
+        filtered_videos.append(a)
+
+    if skipped_landscape and logger:
+        logger.warning("自动选素材: 跳过 %d 个横屏素材", skipped_landscape)
+
+    if not filtered_videos:
+        if logger:
+            logger.warning("自动选素材: 素材库 %s 无可用视频素材", video_lib.name)
+        return []
+
+    # 按创建时间降序（新素材在前）
+    filtered_videos.sort(key=lambda a: a.created_at, reverse=True)
+    return [a.id for a in filtered_videos]

apps/api/app/api/routes/edit_plans.py

@@ -22,7 +22,13 @@ from datetime import datetime
 from typing import Any, List, Optional
 
 from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
+from app.core.storage import get_storage_service
+from app.dependencies import (
+    get_asset_library_repository,
+    get_asset_repository,
+    get_db_session,
+    get_project_repository,
+)
 from app.schemas.generation_task import GenerationTaskResponse
 from app.services import EditPlanService, EditTemplateService
 from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
@@ -32,7 +38,7 @@ from sqlalchemy.orm import Session
 from packages.domain.config_schemas import normalize_plan_config
 from packages.domain.edit_plan import EditPlan, EditPlanStatus
 
-from ._helpers import check_project_access
+from ._helpers import auto_select_video_assets, check_project_access
 
 logger = logging.getLogger(__name__)
 
@@ -50,6 +56,7 @@ class EditPlanCreateRequest(BaseModel):
     config: dict[str, Any] = Field(default_factory=dict, description="计划配置 (JSON)")
     total_duration: float = Field(default=0.0, ge=0.0, description="总时长 (秒)")
     project_id: str = Field(default="", description="所属项目 ID")
+    asset_ids: List[str] = Field(default_factory=list, description="素材 ID 列表，创建时自动分配给片段")
 
 
 class EditPlanUpdateRequest(BaseModel):
@@ -67,7 +74,9 @@ class EditPlanUpdateRequest(BaseModel):
 class CopyPlanRequest(BaseModel):
     """复制剪辑计划请求体"""
 
-    name: Optional[str] = Field(default=None, min_length=1, max_length=200, description="新计划名称，不传则为「原名 - 副本」")
+    name: Optional[str] = Field(
+        default=None, min_length=1, max_length=200, description="新计划名称，不传则为「原名 - 副本」"
+    )
     project_id: Optional[str] = Field(default=None, description="目标项目 ID，不传则复用源计划的项目")
 
 
@@ -243,6 +252,16 @@ class GenerateFromTemplateResponse(BaseModel):
 
 
 def _to_response(p: EditPlan) -> EditPlanResponse:
+    # 对 config 中的 rendered_url 做签名转换（私有bucket裸URL会403）
+    config = dict(p.config) if p.config else {}
+    raw_rendered_url = config.get("rendered_url", "")
+    if raw_rendered_url:
+        try:
+            storage = get_storage_service()
+            config["rendered_url"] = storage.get_download_url(raw_rendered_url, expires_seconds=86400)
+        except Exception as e:
+            logger.warning("剪辑计划rendered_url签名失败，返回原始URL: plan_id=%s error=%s", p.id, e)
+
     return EditPlanResponse(
         id=p.id,
         template_id=p.template_id,
@@ -252,12 +271,26 @@ def _to_response(p: EditPlan) -> EditPlanResponse:
         result_count=getattr(p, "result_count", 0),
         project_id=p.project_id or "",
         created_by_user_id=p.created_by_user_id or "",
-        config=p.config,
+        config=config,
         created_at=p.created_at,
         updated_at=p.updated_at,
     )
 
 
+# ── Include sub-routers (拆分模块) ────────────────────────────────────────────
+# 注意：含静态路径的子路由需放在 CRUD 路由之前，避免被 /{plan_id} 抢先匹配
+
+from .edit_plans_adjustments import router as adjustments_router
+from .edit_plans_export import router as export_router
+from .edit_plans_filter import router as filter_router
+from .edit_plans_transitions import router as transitions_router
+
+router.include_router(export_router)
+router.include_router(adjustments_router)
+router.include_router(filter_router)
+router.include_router(transitions_router)
+
+
 # ── CRUD Routes ───────────────────────────────────────────────────────────────
 
 
@@ -348,37 +381,121 @@ def create_plan(
     db: Session = Depends(get_db_session),
     current_user: AuthenticatedUser = Depends(get_current_user),
     project_repository: Any = Depends(get_project_repository),
+    asset_repository: Any = Depends(get_asset_repository),
+    asset_library_repository: Any = Depends(get_asset_library_repository),
 ) -> EditPlanResponse:
-    """创建剪辑计划"""
+    """创建剪辑计划
+
+    基于模板自动生成片段结构：
+    - 模板存在时：从模板的 clip_configs 生成初始 clips
+    - 模板不存在时：降级为空计划（保持向后兼容）
+    - 用户传入的 config 与模板 config 合并（用户配置优先级更高）
+    - total_duration 自动根据 clips 总时长计算
+    """
+    from app.services import PlanGeneratorService
+
     # 空串 project_id 统一为 ""
     project_id = (body.project_id or "").strip()
     # 项目鉴权
     if project_id:
         check_project_access(project_id, current_user.user.id, project_repository)
+
+    # 标准化用户传入的 config
+    normalized_config = normalize_plan_config(body.config or {})
+
+    template_svc = EditTemplateService(db)
     svc = EditPlanService(db)
-    # 标准化 config，填充 cover/title/subtitle/bgm 默认值
-    normalized_config = normalize_plan_config(body.config)
+
+    # 尝试从模板生成（模板不存在时降级为空计划）
+    template = None
+    clips = []
     try:
-        created = svc.create_plan(
+        template = template_svc.get_template_or_raise(body.template_id)
+    except ValueError:
+        # 模板不存在，降级为普通空计划
+        logger.info("模板不存在，创建空计划: template_id=%s", body.template_id)
+        plan = svc.create_plan(
             template_id=body.template_id,
             name=body.name,
             config=normalized_config,
-            total_duration=body.total_duration,
             project_id=project_id,
             created_by_user_id=current_user.user.id,
+            total_duration=body.total_duration if body.total_duration > 0 else 0.0,
+        )
+        logger.info(
+            "创建空剪辑计划: id=%s name=%s by user=%s",
+            plan.id,
+            plan.name,
+            current_user.user.id,
+        )
+        return _to_response(plan)
+
+    # 模板存在，从模板生成计划+片段
+    clip_configs = template_svc.list_clip_configs(body.template_id, skip=0, limit=200)
+
+    # 自动选素材：未传 asset_ids 但有 project_id 时，从项目视频素材库选 ready 的视频素材
+    resolved_asset_ids = list(body.asset_ids)
+    if not resolved_asset_ids and project_id:
+        auto_assets = auto_select_video_assets(
+            project_id=project_id,
+            asset_library_repo=asset_library_repository,
+            asset_repo=asset_repository,
+            logger=logger,
+        )
+        if auto_assets:
+            resolved_asset_ids = auto_assets
+            logger.info(
+                "自动选素材: project_id=%s count=%d",
+                project_id,
+                len(auto_assets),
+            )
+
+    generator = PlanGeneratorService(db)
+    try:
+        result = generator.generate_from_template(
+            template=template,
+            clip_configs=clip_configs,
+            asset_ids=resolved_asset_ids,
+            project_id=project_id,
+            created_by_user_id=current_user.user.id,
+            name=body.name,
         )
     except ValueError as exc:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail=str(exc),
         ) from exc
+
+    plan = result["plan"]
+    clips = result["clips"]
+
+    # 如果用户传入了自定义 config，合并覆盖模板配置
+    if body.config:
+        base_config = template.config or {}
+        merged_config = {**base_config, **normalized_config}
+        # 重新标准化确保默认值填充正确
+        merged_config = normalize_plan_config(merged_config)
+        plan = svc.update_plan(
+            plan.id,
+            config=merged_config,
+            total_duration=body.total_duration if body.total_duration > 0 else None,
+        )
+
+    # 把 asset_ids 写入 plan.config，供生成时兜底分配使用
+    if resolved_asset_ids:
+        current_config = plan.config or {}
+        if current_config.get("asset_ids") != resolved_asset_ids:
+            current_config["asset_ids"] = resolved_asset_ids
+            plan = svc.update_plan(plan.id, config=normalize_plan_config(current_config))
+
     logger.info(
-        "创建剪辑计划: id=%s name=%s by user=%s",
-        created.id,
-        created.name,
+        "创建剪辑计划: id=%s name=%s clips=%d by user=%s",
+        plan.id,
+        plan.name,
+        len(clips),
         current_user.user.id,
     )
-    return _to_response(created)
+    return _to_response(plan)
 
 
 @router.put("/{plan_id}", response_model=EditPlanResponse)
@@ -506,6 +623,417 @@ def copy_plan(
         current_user.user.id,
     )
     return _to_response(new_plan)
+
+
+# ── 字幕管理 ────────────────────────────────────────────────────────────────
+
+
+class SubtitleCreateRequest(BaseModel):
+    """添加字幕请求体"""
+
+    start: float = Field(..., ge=0, description="开始时间（秒）")
+    end: float = Field(..., gt=0, description="结束时间（秒）")
+    text: str = Field(..., min_length=1, max_length=500, description="字幕文本")
+    style: Optional[dict[str, Any]] = Field(default=None, description="字幕样式")
+
+
+class SubtitleUpdateRequest(BaseModel):
+    """更新字幕请求体"""
+
+    start: Optional[float] = Field(default=None, ge=0, description="开始时间（秒）")
+    end: Optional[float] = Field(default=None, gt=0, description="结束时间（秒）")
+    text: Optional[str] = Field(default=None, min_length=1, max_length=500, description="字幕文本")
+    style: Optional[dict[str, Any]] = Field(default=None, description="字幕样式")
+
+
+class SubtitleBatchUpdateRequest(BaseModel):
+    """批量更新字幕请求体"""
+
+    subtitles: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="字幕列表（全量替换），每条包含 start/end/text，可选 id/style",
+    )
+
+
+@router.get(
+    "/clips/{clip_id}/subtitles",
+    response_model=list[dict[str, Any]],
+    summary="获取片段的所有字幕",
+)
+def list_subtitles(
+    clip_id: str,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    db: Session = Depends(get_db_session),
+    project_repo=Depends(get_project_repository),
+) -> list[dict[str, Any]]:
+    """获取指定片段的所有字幕，按时间排序。"""
+    service = EditPlanService(db)
+
+    clip = service.get_clip(clip_id)
+    if clip is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"片段不存在: {clip_id}",
+        )
+    plan = service.get_plan(clip.plan_id)
+    if plan and plan.project_id:
+        check_project_access(project_repo, current_user, plan.project_id)
+
+    return service.list_subtitles(clip_id)
+
+
+@router.post(
+    "/clips/{clip_id}/subtitles",
+    response_model=dict[str, Any],
+    summary="添加一条字幕",
+    status_code=status.HTTP_201_CREATED,
+)
+def add_subtitle(
+    clip_id: str,
+    body: SubtitleCreateRequest,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    db: Session = Depends(get_db_session),
+    project_repo=Depends(get_project_repository),
+) -> dict[str, Any]:
+    """给片段添加一条字幕。"""
+    service = EditPlanService(db)
+
+    clip = service.get_clip(clip_id)
+    if clip is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"片段不存在: {clip_id}",
+        )
+    plan = service.get_plan(clip.plan_id)
+    if plan and plan.project_id:
+        check_project_access(project_repo, current_user, plan.project_id)
+
+    try:
+        subtitle = service.add_subtitle(
+            clip_id,
+            start=body.start,
+            end=body.end,
+            text=body.text,
+            style=body.style,
+        )
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        ) from e
+
+    logger.info("添加字幕: clip_id=%s by user=%s", clip_id, current_user.user.id)
+    return subtitle
+
+
+@router.put(
+    "/clips/{clip_id}/subtitles/{subtitle_id}",
+    response_model=dict[str, Any],
+    summary="更新一条字幕",
+)
+def update_subtitle(
+    clip_id: str,
+    subtitle_id: str,
+    body: SubtitleUpdateRequest,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    db: Session = Depends(get_db_session),
+    project_repo=Depends(get_project_repository),
+) -> dict[str, Any]:
+    """更新一条字幕的时间、文本或样式。"""
+    service = EditPlanService(db)
+
+    clip = service.get_clip(clip_id)
+    if clip is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"片段不存在: {clip_id}",
+        )
+    plan = service.get_plan(clip.plan_id)
+    if plan and plan.project_id:
+        check_project_access(project_repo, current_user, plan.project_id)
+
+    try:
+        subtitle = service.update_subtitle(
+            clip_id,
+            subtitle_id,
+            start=body.start,
+            end=body.end,
+            text=body.text,
+            style=body.style,
+        )
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        ) from e
+
+    logger.info(
+        "更新字幕: clip_id=%s subtitle_id=%s by user=%s",
+        clip_id,
+        subtitle_id,
+        current_user.user.id,
+    )
+    return subtitle
+
+
+@router.delete(
+    "/clips/{clip_id}/subtitles/{subtitle_id}",
+    summary="删除一条字幕",
+    status_code=status.HTTP_204_NO_CONTENT,
+    response_model=None,
+    response_class=Response,
+)
+def delete_subtitle(
+    clip_id: str,
+    subtitle_id: str,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    db: Session = Depends(get_db_session),
+    project_repo=Depends(get_project_repository),
+) -> None:
+    """删除一条字幕。"""
+    service = EditPlanService(db)
+
+    clip = service.get_clip(clip_id)
+    if clip is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"片段不存在: {clip_id}",
+        )
+    plan = service.get_plan(clip.plan_id)
+    if plan and plan.project_id:
+        check_project_access(project_repo, current_user, plan.project_id)
+
+    deleted = service.delete_subtitle(clip_id, subtitle_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"字幕不存在: {subtitle_id}",
+        )
+
+    logger.info(
+        "删除字幕: clip_id=%s subtitle_id=%s by user=%s",
+        clip_id,
+        subtitle_id,
+        current_user.user.id,
+    )
+
+
+@router.put(
+    "/clips/{clip_id}/subtitles",
+    response_model=list[dict[str, Any]],
+    summary="批量更新字幕（全量替换）",
+)
+def batch_update_subtitles(
+    clip_id: str,
+    body: SubtitleBatchUpdateRequest,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    db: Session = Depends(get_db_session),
+    project_repo=Depends(get_project_repository),
+) -> list[dict[str, Any]]:
+    """批量更新片段的所有字幕（全量替换）。
+
+    用于批量编辑、SRT导入、ASR结果导入等场景。
+    每条字幕包含 start/end/text，已有 id 则保留，否则生成新 id。
+    """
+    service = EditPlanService(db)
+
+    clip = service.get_clip(clip_id)
+    if clip is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"片段不存在: {clip_id}",
+        )
+    plan = service.get_plan(clip.plan_id)
+    if plan and plan.project_id:
+        check_project_access(project_repo, current_user, plan.project_id)
+
+    try:
+        subtitles = service.batch_update_subtitles(clip_id, body.subtitles)
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        ) from e
+
+    logger.info(
+        "批量更新字幕: clip_id=%s count=%d by user=%s",
+        clip_id,
+        len(subtitles),
+        current_user.user.id,
+    )
+    return subtitles
+
+
+# ── 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="闪避音量降低比例")
+
+
+@router.get(
+    "/{plan_id}/bgm",
+    response_model=dict[str, Any],
+    summary="获取剪辑计划的 BGM 配置",
+)
+def get_plan_bgm(
+    plan_id: str,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    db: Session = Depends(get_db_session),
+    project_repo=Depends(get_project_repository),
+) -> dict[str, Any]:
+    """获取指定剪辑计划的 BGM 配置。"""
+    service = EditPlanService(db)
+
+    plan = service.get_plan(plan_id)
+    if plan is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+    if plan.project_id:
+        check_project_access(project_repo, current_user, plan.project_id)
+
+    config = plan.config or {}
+    bgm_config = config.get("bgm", {})
+
+    return {
+        "plan_id": plan.id,
+        "bgm": bgm_config,
+    }
+
+
+@router.put(
+    "/{plan_id}/bgm",
+    response_model=dict[str, Any],
+    summary="更新剪辑计划的 BGM 配置",
+)
+def update_plan_bgm(
+    plan_id: str,
+    body: BGMConfigUpdateRequest,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    db: Session = Depends(get_db_session),
+    project_repo=Depends(get_project_repository),
+) -> dict[str, Any]:
+    """更新剪辑计划的 BGM 配置。
+
+    支持部分更新，只传需要修改的字段即可。
+    启用 BGM 后需要指定来源（asset_id / preset_id / audio_url 三选一）。
+    """
+    service = EditPlanService(db)
+
+    plan = service.get_plan(plan_id)
+    if plan is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+    if plan.project_id:
+        check_project_access(project_repo, current_user, plan.project_id)
+
+    # 读取当前 BGM 配置，合并更新
+    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)
+
+    # 校验：启用 BGM 时至少有一个有效来源
+    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）",
+            )
+
+    # 保存到 plan.config.bgm
+    config["bgm"] = current_bgm
+    updated_plan = service.update_plan_config(plan_id, config)
+
+    logger.info(
+        "更新BGM配置: plan_id=%s enabled=%s by user=%s",
+        plan_id,
+        current_bgm.get("enabled", False),
+        current_user.user.id,
+    )
+
+    return {
+        "plan_id": updated_plan.id,
+        "bgm": current_bgm,
+    }
+
+
+# ── BGM 预设库 ────────────────────────────────────────────────────────────────
+
+
+@router.get(
+    "/bgm/presets",
+    response_model=dict[str, Any],
+    summary="获取预设 BGM 列表",
+)
+def list_bgm_presets(
+    style: Optional[str] = Query(default=None, description="按风格筛选"),
+    keyword: Optional[str] = Query(default=None, description="关键词搜索"),
+    skip: int = Query(default=0, ge=0, description="分页偏移"),
+    limit: int = Query(default=50, ge=1, le=200, description="每页数量"),
+) -> dict[str, Any]:
+    """获取预设 BGM 列表，支持按风格筛选和关键词搜索。
+
+    风格可选: upbeat（轻快）、relax（治愈）、tech（科技）、commerce（电商）、
+    emotional（情感）、cinematic（电影）
+    """
+    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
+        ],
+    }
+
+
 # ── 保存为模板 ────────────────────────────────────────────────────────────────
 
 
@@ -591,6 +1119,7 @@ def save_plan_as_template(
 from .edit_plans_ai import router as ai_router
 from .edit_plans_clips import router as clips_router
 from .edit_plans_clips_batch import router as clips_batch_router
+from .edit_plans_cover import router as cover_router
 from .edit_plans_generation import router as generation_router
 from .edit_plans_timeline import router as timeline_router
 
@@ -599,3 +1128,4 @@ router.include_router(ai_router)
 router.include_router(timeline_router)
 router.include_router(clips_router, prefix="/{plan_id}/clips", tags=["EditPlan Clips"])
 router.include_router(clips_batch_router, prefix="/{plan_id}/clips", tags=["EditPlan Clips"])
+router.include_router(cover_router)

apps/api/app/api/routes/edit_plans_adjustments.py

@@ -0,0 +1,311 @@
+"""片段调整 API.
+
+- PUT    /clips/{clip_id}/speed         调速
+- PUT    /clips/{clip_id}/volume        音量调节
+- PUT    /clips/{clip_id}/trim          裁剪（trim in/out）
+- PUT    /clips/{clip_id}/adjustments   统一调整（speed+volume+trim）
+- POST   /{plan_id}/clips/batch-speed   批量调速
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session, get_project_repository
+from app.services import EditPlanService
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+from ._helpers import check_project_access
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ── Schemas ──────────────────────────────────────────────────────────────────
+
+
+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
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _get_clip_config(clip) -> dict:
+    config = getattr(clip, "config", {}) or {}
+    if not isinstance(config, dict):
+        config = {}
+    return config
+
+
+def _get_volume(clip) -> float:
+    config = _get_clip_config(clip)
+    return float(config.get("volume", 1.0))
+
+
+def _get_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_response(clip) -> ClipAdjustResponse:
+    trim_start, trim_end = _get_trim(clip)
+    return ClipAdjustResponse(
+        clip_id=clip.id,
+        speed=clip.playback_speed,
+        volume=_get_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）")
+
+
+# ── Routes ───────────────────────────────────────────────────────────────────
+
+
+def _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository):
+    svc = EditPlanService(db)
+    clip = svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"片段不存在: {clip_id}",
+        )
+    plan = svc.get_plan(clip.plan_id)
+    if plan and plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+    return svc, plan, clip
+
+
+@router.put("/clips/{clip_id}/speed", response_model=ClipAdjustResponse)
+def adjust_speed(
+    clip_id: str,
+    body: SpeedAdjustRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> ClipAdjustResponse:
+    """调整片段播放速度"""
+    svc, _, clip = _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository)
+
+    updated = svc.update_clip(clip_id, playback_speed=body.speed)
+
+    logger.info(
+        "调整片段速度: clip_id=%s speed=%.2f by user=%s",
+        clip_id,
+        body.speed,
+        current_user.user.id,
+    )
+    return _build_response(updated)
+
+
+@router.put("/clips/{clip_id}/volume", response_model=ClipAdjustResponse)
+def adjust_volume(
+    clip_id: str,
+    body: VolumeAdjustRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> ClipAdjustResponse:
+    """调整片段音量"""
+    svc, _, clip = _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository)
+
+    # 更新 config.volume
+    config = dict(_get_clip_config(clip))
+    config["volume"] = body.volume
+    updated = svc.update_clip(clip_id, config=config)
+
+    logger.info(
+        "调整片段音量: clip_id=%s volume=%.2f by user=%s",
+        clip_id,
+        body.volume,
+        current_user.user.id,
+    )
+    return _build_response(updated)
+
+
+@router.put("/clips/{clip_id}/trim", response_model=ClipAdjustResponse)
+def adjust_trim(
+    clip_id: str,
+    body: TrimAdjustRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> ClipAdjustResponse:
+    """裁剪片段（trim in/out）"""
+    svc, _, clip = _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository)
+
+    # 验证裁剪时长
+    try:
+        _validate_trim(body.trim_start, body.trim_end, clip.duration)
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+
+    # 更新 config
+    config = dict(_get_clip_config(clip))
+    config["trim_start"] = body.trim_start
+    config["trim_end"] = body.trim_end
+    updated = svc.update_clip(clip_id, config=config)
+
+    logger.info(
+        "裁剪片段: clip_id=%s trim_start=%.2f trim_end=%.2f by user=%s",
+        clip_id,
+        body.trim_start,
+        body.trim_end,
+        current_user.user.id,
+    )
+    return _build_response(updated)
+
+
+@router.put("/clips/{clip_id}/adjustments", response_model=ClipAdjustResponse)
+def adjust_all(
+    clip_id: str,
+    body: ClipAdjustmentsRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> ClipAdjustResponse:
+    """统一调整片段的 speed / volume / trim"""
+    svc, _, clip = _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository)
+
+    update_kwargs = {}
+    config_updates = {}
+
+    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
+
+    # 验证 trim
+    current_trim_start, current_trim_end = _get_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=status.HTTP_400_BAD_REQUEST, 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_response(clip)
+
+    updated = svc.update_clip(clip_id, **update_kwargs)
+
+    logger.info(
+        "统一调整片段: clip_id=%s speed=%s volume=%s by user=%s",
+        clip_id,
+        body.speed,
+        body.volume,
+        current_user.user.id,
+    )
+    return _build_response(updated)
+
+
+@router.post("/{plan_id}/clips/batch-speed", response_model=BatchSpeedResponse)
+def batch_adjust_speed(
+    plan_id: str,
+    body: BatchSpeedRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> BatchSpeedResponse:
+    """批量调整计划内所有片段的播放速度"""
+    svc = EditPlanService(db)
+    plan = svc.get_plan(plan_id)
+    if not plan:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    clips = svc.list_clips(plan_id, limit=500, skip=0)
+    count = 0
+    for clip in clips:
+        svc.update_clip(clip.id, playback_speed=body.speed)
+        count += 1
+
+    logger.info(
+        "批量调速: plan_id=%s count=%d speed=%.2f by user=%s",
+        plan_id,
+        count,
+        body.speed,
+        current_user.user.id,
+    )
+    return BatchSpeedResponse(updated_count=count, plan_id=plan_id)

apps/api/app/api/routes/edit_plans_clips.py

@@ -276,3 +276,140 @@ def delete_clip(
 
     logger.info("删除剪辑片段: plan_id=%s clip_id=%s by user=%s", plan_id, clip_id, current_user.user.id)
     return None
+
+
+# ── 片段分割与合并 ──────────────────────────────────────────────────────────
+
+
+class SplitClipRequest(BaseModel):
+    """分割片段请求体"""
+
+    split_time: float = Field(..., gt=0, description="分割点（秒，相对于片段起始）")
+
+
+class MergeClipsRequest(BaseModel):
+    """合并片段请求体"""
+
+    clip_ids: list[str] = Field(..., min_length=2, description="要合并的片段 ID 列表")
+
+
+@router.post(
+    "/{clip_id}/split",
+    response_model=dict[str, Any],
+    summary="分割片段",
+    status_code=status.HTTP_200_OK,
+)
+def split_clip(
+    plan_id: str,
+    clip_id: str,
+    body: SplitClipRequest,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    db: Session = Depends(get_db_session),
+    project_repository: Any = Depends(get_project_repository),
+) -> dict[str, Any]:
+    """将一个片段从指定时间点分割为两个片段。
+
+    分割后原片段变为左半部分，新增右半部分片段，后续片段顺序自动后移。
+    若片段有关联素材，会自动设置 trim_start/trim_end 标记裁剪范围。
+    """
+    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
+
+    svc = _get_svc(db)
+    clip = svc.get_clip(clip_id)
+    if clip is None or clip.plan_id != plan_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"片段不存在: {clip_id}",
+        )
+
+    try:
+        result = svc.split_clip(clip_id, body.split_time)
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        ) from e
+
+    left = result["left_clip"]
+    right = result["right_clip"]
+    logger.info("分割片段: plan_id=%s clip_id=%s by user=%s", plan_id, clip_id, current_user.user.id)
+
+    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(
+    "/merge",
+    response_model=dict[str, Any],
+    summary="合并多个连续片段",
+    status_code=status.HTTP_200_OK,
+)
+def merge_clips(
+    plan_id: str,
+    body: MergeClipsRequest,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    db: Session = Depends(get_db_session),
+    project_repository: Any = Depends(get_project_repository),
+) -> dict[str, Any]:
+    """将多个连续的同类型片段合并为一个片段。
+
+    合并要求：
+    - 至少 2 个片段
+    - 属于同一剪辑计划
+    - order 连续
+    - 类型相同
+
+    合并后保留第一个片段，其余删除，后续片段顺序自动前移。
+    """
+    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
+
+    svc = _get_svc(db)
+
+    # 校验所有片段都属于该 plan
+    for cid in body.clip_ids:
+        clip = svc.get_clip(cid)
+        if clip is None or clip.plan_id != plan_id:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"片段不存在: {cid}",
+            )
+
+    try:
+        merged = svc.merge_clips(body.clip_ids)
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        ) from e
+
+    logger.info(
+        "合并片段: plan_id=%s clip_count=%d by user=%s",
+        plan_id,
+        len(body.clip_ids),
+        current_user.user.id,
+    )
+
+    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,
+    }

apps/api/app/api/routes/edit_plans_clips_batch.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import logging
-from typing import Any, List, Optional
+from typing import Any, List
 
 from app.auth import AuthenticatedUser, get_current_user
 from app.dependencies import get_db_session, get_project_repository

apps/api/app/api/routes/edit_plans_cover.py

@@ -0,0 +1,315 @@
+"""封面管理 API.
+
+- GET    /{plan_id}/cover              获取封面配置
+- PUT    /{plan_id}/cover              更新封面配置
+- POST   /{plan_id}/cover/extract      从指定片段抽帧生成封面
+- POST   /{plan_id}/cover/smart        智能选帧生成封面
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.core.storage import get_storage_service
+from app.dependencies import (
+    get_asset_repository,
+    get_db_session,
+    get_project_repository,
+)
+from app.services import EditPlanService
+from app.services.cover_service import CoverService
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+from packages.domain.config_schemas import normalize_plan_config
+
+from ._helpers import check_project_access
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ── Schemas ──────────────────────────────────────────────────────────────────
+
+
+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="抽帧时间点（秒）")
+
+
+# ── Routes ───────────────────────────────────────────────────────────────────
+
+
+@router.get("/{plan_id}/cover", response_model=CoverConfigResponse)
+def get_cover(
+    plan_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> CoverConfigResponse:
+    """获取封面配置"""
+    svc = EditPlanService(db)
+    plan = svc.get_plan(plan_id)
+    if not plan:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    cover = CoverService.get_cover_config(plan.config or {})
+    return CoverConfigResponse(**cover)
+
+
+@router.put("/{plan_id}/cover", response_model=CoverConfigResponse)
+def update_cover(
+    plan_id: str,
+    body: CoverUpdateRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> CoverConfigResponse:
+    """更新封面配置
+
+    用于：设置上传的封面图片 URL、切换封面类型、调整时间点等。
+    """
+    svc = EditPlanService(db)
+    plan = svc.get_plan(plan_id)
+    if not plan:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    # 合并更新
+    current_cover = CoverService.get_cover_config(plan.config or {})
+    updates = body.model_dump(exclude_none=True)
+    new_cover = {**current_cover, **updates}
+
+    # 验证 type 值
+    valid_types = {"ai_frame", "manual", "upload", "ai_regenerate"}
+    if "type" in updates and updates["type"] not in valid_types:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"无效的封面类型: {updates['type']}，有效值: {valid_types}",
+        )
+
+    # 更新到 plan.config
+    current_config = dict(plan.config or {})
+    current_config["cover"] = new_cover
+    normalized = normalize_plan_config(current_config)
+    updated_plan = svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
+
+    result = CoverService.get_cover_config(updated_plan.config or {})
+    logger.info("更新封面配置: plan_id=%s type=%s by user=%s", plan_id, result["type"], current_user.user.id)
+    return CoverConfigResponse(**result)
+
+
+@router.post("/{plan_id}/cover/extract", response_model=CoverGenerateResponse)
+def extract_cover(
+    plan_id: str,
+    body: CoverExtractRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+    storage_service: Any = Depends(get_storage_service),
+    asset_repository: Any = Depends(get_asset_repository),
+) -> CoverGenerateResponse:
+    """从指定片段的指定时间点抽帧生成封面"""
+    svc = EditPlanService(db)
+    plan = svc.get_plan(plan_id)
+    if not plan:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    # 获取片段对应的素材
+    clip = svc.get_clip(body.clip_id)
+    if not clip:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"片段不存在: {body.clip_id}",
+        )
+
+    if clip.plan_id != plan_id:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="片段不属于该剪辑计划",
+        )
+
+    if not clip.asset_id:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="片段没有关联素材，无法抽帧",
+        )
+
+    # 抽帧生成封面
+    cover_svc = CoverService(storage_service, asset_repository)
+    try:
+        cover_data = cover_svc.extract_cover_from_clip(
+            plan_id=plan_id,
+            asset_id=clip.asset_id,
+            frame_time=body.frame_time,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+    except RuntimeError as e:
+        logger.error("封面抽帧失败: plan_id=%s clip_id=%s error=%s", plan_id, body.clip_id, e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"封面抽帧失败: {e}",
+        ) from e
+
+    # 更新到 plan.config.cover
+    current_config = dict(plan.config or {})
+    current_config["cover"] = cover_data
+    normalized = normalize_plan_config(current_config)
+    svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
+
+    logger.info(
+        "封面抽帧完成: plan_id=%s clip_id=%s time=%.2fs by user=%s",
+        plan_id,
+        body.clip_id,
+        body.frame_time,
+        current_user.user.id,
+    )
+    return CoverGenerateResponse(**cover_data)
+
+
+@router.post("/{plan_id}/cover/smart", response_model=CoverGenerateResponse)
+def smart_cover(
+    plan_id: str,
+    body: CoverSmartRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+    storage_service: Any = Depends(get_storage_service),
+    asset_repository: Any = Depends(get_asset_repository),
+) -> CoverGenerateResponse:
+    """智能选帧生成封面
+
+    从指定片段（或第一个视频片段）中智能选取一帧作为封面。
+    当前实现：取片段第3秒帧（后续可优化为多帧选最清晰）。
+    """
+    svc = EditPlanService(db)
+    plan = svc.get_plan(plan_id)
+    if not plan:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    # 确定使用哪个片段
+    clip_id = body.clip_id
+    asset_id = ""
+
+    if clip_id:
+        clip = svc.get_clip(clip_id)
+        if not clip:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"片段不存在: {clip_id}",
+            )
+        if clip.plan_id != plan_id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="片段不属于该剪辑计划",
+            )
+        if not clip.asset_id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="片段没有关联素材",
+            )
+        asset_id = clip.asset_id
+    else:
+        # 找第一个有素材的视频片段
+        clips = svc.list_clips(plan_id, limit=50, skip=0)
+        for c in clips:
+            if c.asset_id and c.clip_type == "video":
+                asset_id = c.asset_id
+                clip_id = c.id
+                break
+
+        if not asset_id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="没有找到可用的视频片段",
+            )
+
+    # 智能选帧
+    cover_svc = CoverService(storage_service, asset_repository)
+    try:
+        cover_data = cover_svc.generate_smart_cover(
+            plan_id=plan_id,
+            asset_id=asset_id,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+    except RuntimeError as e:
+        logger.error("智能封面生成失败: plan_id=%s error=%s", plan_id, e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"智能封面生成失败: {e}",
+        ) from e
+
+    # 更新到 plan.config.cover
+    current_config = dict(plan.config or {})
+    current_config["cover"] = cover_data
+    normalized = normalize_plan_config(current_config)
+    svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
+
+    logger.info(
+        "智能封面生成完成: plan_id=%s clip_id=%s by user=%s",
+        plan_id,
+        clip_id,
+        current_user.user.id,
+    )
+    return CoverGenerateResponse(**cover_data)

apps/api/app/api/routes/edit_plans_export.py

@@ -0,0 +1,274 @@
+"""导出设置 API.
+
+- GET    /{plan_id}/export              获取导出配置
+- PUT    /{plan_id}/export              更新导出配置
+- GET    /export-presets                 导出预设列表
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, List, Optional
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session, get_project_repository
+from app.services import EditPlanService
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field, validator
+from sqlalchemy.orm import Session
+
+from packages.domain.config_schemas import normalize_plan_config
+
+from ._helpers import check_project_access
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ── 导出预设 ──────────────────────────────────────────────────────────────────
+
+EXPORT_PRESETS = [
+    {
+        "id": "export_1080p_30",
+        "name": "1080P 高清",
+        "resolution": "1080x1920",
+        "fps": 30,
+        "video_bitrate": 8000,
+        "audio_bitrate": 128,
+        "format": "mp4",
+        "quality_preset": "balanced",
+        "description": "竖屏高清，适合短视频平台",
+        "size_hint": "约 10MB/分钟",
+    },
+    {
+        "id": "export_1080p_60",
+        "name": "1080P 高帧率",
+        "resolution": "1080x1920",
+        "fps": 60,
+        "video_bitrate": 12000,
+        "audio_bitrate": 128,
+        "format": "mp4",
+        "quality_preset": "high",
+        "description": "60帧高帧率，流畅运动画面",
+        "size_hint": "约 18MB/分钟",
+    },
+    {
+        "id": "export_720p_30",
+        "name": "720P 流畅",
+        "resolution": "720x1280",
+        "fps": 30,
+        "video_bitrate": 4000,
+        "audio_bitrate": 128,
+        "format": "mp4",
+        "quality_preset": "fast",
+        "description": "快速导出，文件较小",
+        "size_hint": "约 5MB/分钟",
+    },
+    {
+        "id": "export_4k_30",
+        "name": "4K 超清",
+        "resolution": "2160x3840",
+        "fps": 30,
+        "video_bitrate": 20000,
+        "audio_bitrate": 192,
+        "format": "mp4",
+        "quality_preset": "best",
+        "description": "4K超清画质，专业品质",
+        "size_hint": "约 30MB/分钟",
+    },
+    {
+        "id": "export_1080p_30_mov",
+        "name": "1080P ProRes",
+        "resolution": "1080x1920",
+        "fps": 30,
+        "video_bitrate": 15000,
+        "audio_bitrate": 256,
+        "format": "mov",
+        "quality_preset": "high",
+        "description": "MOV格式，适合后期剪辑",
+        "size_hint": "约 25MB/分钟",
+    },
+]
+
+VALID_QUALITY_PRESETS = {"ultra_fast", "fast", "balanced", "high", "best"}
+VALID_FORMATS = {"mp4", "mov"}
+
+RESOLUTION_PATTERN = re.compile(r"^\d+x\d+$")
+
+
+# ── Schemas ──────────────────────────────────────────────────────────────────
+
+
+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 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 VALID_FORMATS:
+            raise ValueError(f"无效格式: {v}，支持: {VALID_FORMATS}")
+        return v
+
+    @validator("quality_preset")
+    def validate_quality_preset(cls, v):
+        if v is None:
+            return v
+        if v not in VALID_QUALITY_PRESETS:
+            raise ValueError(f"无效质量预设: {v}，支持: {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
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _get_export_config(plan_config: dict) -> dict:
+    e = plan_config.get("export", {})
+    if not isinstance(e, dict):
+        e = {}
+    return {
+        "resolution": e.get("resolution", "1080x1920"),
+        "fps": e.get("fps", 30),
+        "video_bitrate": e.get("video_bitrate", 8000),
+        "audio_bitrate": e.get("audio_bitrate", 128),
+        "format": e.get("format", "mp4"),
+        "quality_preset": e.get("quality_preset", "balanced"),
+        "watermark_enabled": e.get("watermark_enabled", False),
+        "watermark_text": e.get("watermark_text", ""),
+    }
+
+
+# ── Routes ───────────────────────────────────────────────────────────────────
+
+
+@router.get("/export-presets", response_model=ExportPresetListResponse)
+def list_export_presets(
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> ExportPresetListResponse:
+    """获取导出预设列表"""
+    items = [ExportPresetItem(**p) for p in EXPORT_PRESETS]
+    return ExportPresetListResponse(items=items, total=len(items))
+
+
+@router.get("/{plan_id}/export", response_model=ExportConfigResponse)
+def get_export_config(
+    plan_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> ExportConfigResponse:
+    """获取导出配置"""
+    svc = EditPlanService(db)
+    plan = svc.get_plan(plan_id)
+    if not plan:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    config = _get_export_config(plan.config or {})
+    return ExportConfigResponse(**config)
+
+
+@router.put("/{plan_id}/export", response_model=ExportConfigResponse)
+def update_export_config(
+    plan_id: str,
+    body: ExportUpdateRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> ExportConfigResponse:
+    """更新导出配置"""
+    svc = EditPlanService(db)
+    plan = svc.get_plan(plan_id)
+    if not plan:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    # 合并更新
+    current = _get_export_config(plan.config or {})
+    updates = body.model_dump(exclude_none=True)
+    new_export = {**current, **updates}
+
+    # 更新到 plan.config
+    current_config = dict(plan.config or {})
+    current_config["export"] = new_export
+    normalized = normalize_plan_config(current_config)
+    updated_plan = svc.update_plan_config(plan_id, {"export": normalized["export"]})
+
+    result = _get_export_config(updated_plan.config or {})
+    logger.info(
+        "更新导出配置: plan_id=%s resolution=%s fps=%d by user=%s",
+        plan_id,
+        result["resolution"],
+        result["fps"],
+        current_user.user.id,
+    )
+    return ExportConfigResponse(**result)

apps/api/app/api/routes/edit_plans_filter.py

@@ -0,0 +1,197 @@
+"""滤镜调色 API.
+
+- GET    /filter-presets            滤镜预设列表
+- GET    /{plan_id}/filter          获取全局滤镜配置
+- PUT    /{plan_id}/filter          更新全局滤镜配置
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, List, Optional
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session, get_project_repository
+from app.services import EditPlanService
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+from packages.domain.config_schemas import normalize_plan_config
+from packages.domain.filter_presets import (
+    FilterPreset,
+    get_filter_preset,
+    list_filter_presets,
+)
+
+from ._helpers import check_project_access
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ── Schemas ──────────────────────────────────────────────────────────────────
+
+
+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
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _preset_to_response(p: FilterPreset) -> FilterPresetResponse:
+    return FilterPresetResponse(
+        id=p.id,
+        name=p.name,
+        category=p.category,
+        description=p.description,
+        tags=list(p.tags),
+    )
+
+
+def _get_filter_config(plan_config: dict) -> dict:
+    """从 plan.config 中提取滤镜配置"""
+    f = plan_config.get("filter", {})
+    if not isinstance(f, dict):
+        f = {}
+    return {
+        "enabled": f.get("enabled", False),
+        "preset_id": f.get("preset_id", "filter_none"),
+        "intensity": f.get("intensity", 100),
+        "brightness": f.get("brightness", 0.0),
+        "contrast": f.get("contrast", 1.0),
+        "saturation": f.get("saturation", 1.0),
+        "warmth": f.get("warmth", 0.0),
+    }
+
+
+# ── Routes ───────────────────────────────────────────────────────────────────
+
+
+@router.get("/filter-presets", response_model=FilterPresetListResponse)
+def list_presets(
+    category: Optional[str] = Query(default=None, description="按分类筛选"),
+    keyword: Optional[str] = Query(default=None, description="关键词搜索"),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> FilterPresetListResponse:
+    """获取滤镜预设列表"""
+    presets = list_filter_presets(category=category, keyword=keyword)
+    items = [_preset_to_response(p) for p in presets]
+    return FilterPresetListResponse(items=items, total=len(items))
+
+
+@router.get("/{plan_id}/filter", response_model=FilterConfigResponse)
+def get_filter(
+    plan_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> FilterConfigResponse:
+    """获取剪辑计划的全局滤镜配置"""
+    svc = EditPlanService(db)
+    plan = svc.get_plan(plan_id)
+    if not plan:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    config = _get_filter_config(plan.config or {})
+    return FilterConfigResponse(**config)
+
+
+@router.put("/{plan_id}/filter", response_model=FilterConfigResponse)
+def update_filter(
+    plan_id: str,
+    body: FilterUpdateRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> FilterConfigResponse:
+    """更新全局滤镜配置"""
+    svc = EditPlanService(db)
+    plan = svc.get_plan(plan_id)
+    if not plan:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    # 验证 preset_id
+    updates = body.model_dump(exclude_none=True)
+    if "preset_id" in updates:
+        preset = get_filter_preset(updates["preset_id"])
+        if preset is None:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"无效的滤镜预设: {updates['preset_id']}",
+            )
+
+    # 合并更新
+    current = _get_filter_config(plan.config or {})
+    new_filter = {**current, **updates}
+
+    # 如果设为原图 preset，自动关闭
+    if new_filter["preset_id"] == "filter_none":
+        new_filter["enabled"] = False
+
+    # 更新到 plan.config
+    current_config = dict(plan.config or {})
+    current_config["filter"] = new_filter
+    normalized = normalize_plan_config(current_config)
+    updated_plan = svc.update_plan_config(plan_id, {"filter": normalized["filter"]})
+
+    result = _get_filter_config(updated_plan.config or {})
+    logger.info(
+        "更新滤镜配置: plan_id=%s preset=%s intensity=%d by user=%s",
+        plan_id,
+        result["preset_id"],
+        result["intensity"],
+        current_user.user.id,
+    )
+    return FilterConfigResponse(**result)

apps/api/app/api/routes/edit_plans_generation.py

@@ -20,6 +20,7 @@ from app.api.routes.edit_plans import (
 )
 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.core.task_enqueue import GLOBAL_PENDING_LIMIT, USER_PENDING_LIMIT
 from app.dependencies import get_asset_library_repository, get_asset_repository, get_db_session, get_project_repository
 from app.services import EditPlanService
@@ -131,17 +132,21 @@ def _auto_fallback_auto_material_mode(
     asset_library_repo: Any,
     asset_repo: Any,
 ) -> None:
-    """自动兜底 4: 自动素材模式 → 从项目默认视频素材库选取"""
+    """自动兜底 4: 项目有视频素材库时，自动选取 ready 视频素材分配给无素材片段
+
+    注：原先需要 material_mode=="auto" 才触发，但全代码库没有任何地方设置为 auto，
+    导致这道兜底防线永远不生效。现改为：只要有 project_id 且存在无素材片段，
+    就自动从项目视频素材库选取素材兜底，确保一键生成等场景能正常出片。
+    """
     if not clips_without_asset:
         return
-    material_mode = (plan_check.config or {}).get("material_mode", "manual")
-    if material_mode != "auto" or not plan_check.project_id:
+    if not plan_check.project_id:
         return
 
     import random
 
     logger.info(
-        "自动兜底4: plan=%s 自动素材模式，从项目素材库选取素材 (%d 个片段需要)",
+        "自动兜底4: plan=%s 自动选素材分配给 %d 个无素材片段",
         plan_id,
         len(clips_without_asset),
     )
@@ -308,6 +313,7 @@ def get_generation_status(
     db: Session = Depends(get_db_session),
     current_user: AuthenticatedUser = Depends(get_current_user),
     project_repository: Any = Depends(get_project_repository),
+    storage_service: OSSStorageService = Depends(get_storage_service),
 ) -> EditPlanGenerationStatusResponse:
     """查询剪辑计划生成进度"""
     svc = EditPlanService(db)
@@ -334,8 +340,15 @@ def get_generation_status(
         for c in clips
     ]
 
-    # 从 plan.config 中取渲染结果 URL
-    video_url = (plan.config or {}).get("rendered_url", "")
+    # 从 plan.config 中取渲染结果 URL，转换为签名 URL
+    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失败，返回原始URL: plan_id=%s error=%s", plan_id, e)
+            video_url = raw_video_url
     # 从 gen_status 中取进度、错误信息、任务状态
     progress = gen_status.get("progress", 0.0)
     error_message = gen_status.get("error_message", "")

apps/api/app/api/routes/edit_plans_timeline.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 import logging
 from typing import Any, List
 
-from app.api.routes._helpers import check_project_access
+from app.api.routes._helpers import auto_select_video_assets, check_project_access
 from app.api.routes.edit_plans import (
     GenerateFromTemplateRequest,
     GenerateFromTemplateResponse,
@@ -18,9 +18,14 @@ from app.api.routes.edit_plans import (
     _to_response,
 )
 from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
+from app.dependencies import (
+    get_asset_library_repository,
+    get_asset_repository,
+    get_db_session,
+    get_project_repository,
+)
 from app.services import EditPlanService, PlanGeneratorService
-from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi import APIRouter, Depends, HTTPException, status
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
 
@@ -161,6 +166,8 @@ def generate_from_template(
     db: Session = Depends(get_db_session),
     current_user: AuthenticatedUser = Depends(get_current_user),
     project_repository: Any = Depends(get_project_repository),
+    asset_repository: Any = Depends(get_asset_repository),
+    asset_library_repository: Any = Depends(get_asset_library_repository),
 ) -> GenerateFromTemplateResponse:
     """基于模板 + 素材自动生成剪辑计划"""
     from app.services import EditTemplateService
@@ -177,11 +184,28 @@ def generate_from_template(
 
     clip_configs = template_svc.list_clip_configs(body.template_id, skip=0, limit=200)
 
+    # 自动选素材：未传 asset_ids 但有 project_id 时，从项目视频素材库选 ready 的视频素材
+    resolved_asset_ids = list(body.asset_ids)
+    if not resolved_asset_ids and body.project_id:
+        auto_assets = auto_select_video_assets(
+            project_id=body.project_id,
+            asset_library_repo=asset_library_repository,
+            asset_repo=asset_repository,
+            logger=logger,
+        )
+        if auto_assets:
+            resolved_asset_ids = auto_assets
+            logger.info(
+                "generate-from-template 自动选素材: project_id=%s count=%d",
+                body.project_id,
+                len(auto_assets),
+            )
+
     generator = PlanGeneratorService(db)
     result = generator.generate_from_template(
         template=template,
         clip_configs=clip_configs,
-        asset_ids=body.asset_ids,
+        asset_ids=resolved_asset_ids,
         project_id=body.project_id,
         created_by_user_id=current_user.user.id,
         name=body.name,
@@ -190,8 +214,20 @@ def generate_from_template(
     plan = result["plan"]
     clips = result["clips"]
 
+    # 把 asset_ids 写入 plan.config，供生成时兜底分配使用
+    if resolved_asset_ids:
+        from app.services import EditPlanService
+
+        from packages.domain.config_schemas import normalize_plan_config
+
+        svc = EditPlanService(db)
+        current_config = plan.config or {}
+        if current_config.get("asset_ids") != resolved_asset_ids:
+            current_config["asset_ids"] = resolved_asset_ids
+            plan = svc.update_plan(plan.id, config=normalize_plan_config(current_config))
+
     logger.info(
-        "基于模板生成剪辑计划: plan_id=%s template_id=%s clips=%d by user=%s",
+        "基于模板生成剪辑计划: plan_id=%s template_id=%s clips=%d by user=%d",
         plan.id,
         body.template_id,
         len(clips),

apps/api/app/api/routes/edit_plans_transitions.py

@@ -0,0 +1,272 @@
+"""转场特效 API.
+
+- GET    /transition-presets              转场预设列表
+- PUT    /clips/{clip_id}/transition      设置单个片段转场
+- POST   /{plan_id}/transitions/batch     批量设置转场（所有片段）
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, List, Optional
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session, get_project_repository
+from app.services import EditPlanService
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+from packages.domain.transition_presets import (
+    TransitionPreset,
+    get_transition_preset,
+    list_transition_presets,
+)
+
+from ._helpers import check_project_access
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ── Schemas ──────────────────────────────────────────────────────────────────
+
+
+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
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _preset_to_response(p: TransitionPreset) -> TransitionPresetResponse:
+    return TransitionPresetResponse(
+        id=p.id,
+        name=p.name,
+        category=p.category,
+        description=p.description,
+        tags=list(p.tags),
+        default_duration=p.default_duration,
+        min_duration=p.min_duration,
+        max_duration=p.max_duration,
+    )
+
+
+def _validate_transition(effect: str, duration: Optional[float] = None) -> tuple[str, float]:
+    """验证转场效果和时长，返回 (effect, duration)"""
+    preset = get_transition_preset(effect)
+    if preset is None:
+        raise ValueError(f"无效的转场效果: {effect}")
+
+    # 硬切特殊处理，时长强制为0
+    if effect == "transition_none" or preset.transition == "none":
+        return "cut", 0.0
+
+    final_duration = duration if duration is not None else preset.default_duration
+    if final_duration < preset.min_duration:
+        final_duration = preset.min_duration
+    if final_duration > preset.max_duration:
+        final_duration = preset.max_duration
+
+    return preset.transition, round(final_duration, 3)
+
+
+# ── Routes ───────────────────────────────────────────────────────────────────
+
+
+@router.get("/transition-presets", response_model=TransitionPresetListResponse)
+def list_presets(
+    category: Optional[str] = Query(default=None, description="按分类筛选"),
+    keyword: Optional[str] = Query(default=None, description="关键词搜索"),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> TransitionPresetListResponse:
+    """获取转场预设列表"""
+    presets = list_transition_presets(category=category, keyword=keyword)
+    items = [_preset_to_response(p) for p in presets]
+    return TransitionPresetListResponse(items=items, total=len(items))
+
+
+@router.put("/clips/{clip_id}/transition", response_model=ClipTransitionResponse)
+def update_clip_transition(
+    clip_id: str,
+    body: TransitionUpdateRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> ClipTransitionResponse:
+    """设置单个片段的转场效果"""
+    svc = EditPlanService(db)
+    clip = svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"片段不存在: {clip_id}",
+        )
+
+    plan = svc.get_plan(clip.plan_id)
+    if plan and plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    # 验证转场参数
+    try:
+        effect, duration = _validate_transition(body.effect, body.duration)
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+
+    # 更新片段
+    updated_clip = svc.update_clip(
+        clip_id,
+        transition_effect=effect,
+        transition_duration=duration,
+    )
+
+    logger.info(
+        "更新片段转场: clip_id=%s effect=%s duration=%.3f by user=%s",
+        clip_id,
+        effect,
+        duration,
+        current_user.user.id,
+    )
+    return ClipTransitionResponse(
+        clip_id=clip_id,
+        effect=updated_clip.transition_effect,
+        duration=updated_clip.transition_duration,
+    )
+
+
+@router.post("/{plan_id}/transitions/batch", response_model=BatchTransitionResponse)
+def batch_update_transitions(
+    plan_id: str,
+    body: BatchTransitionRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> BatchTransitionResponse:
+    """批量设置计划内所有片段的转场效果
+
+    apply_to 说明：
+    - all: 所有片段
+    - except_first: 除第一个片段外（第一个片段不需要前转场）
+    - except_last: 除最后一个片段外
+    - middle: 只设置中间片段（除首尾）
+    """
+    svc = EditPlanService(db)
+    plan = svc.get_plan(plan_id)
+    if not plan:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    # 验证转场参数
+    try:
+        effect, duration = _validate_transition(body.effect, body.duration)
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+
+    # 获取所有片段
+    clips = svc.list_clips(plan_id, limit=500, skip=0)
+    if not clips:
+        return BatchTransitionResponse(updated_count=0, plan_id=plan_id)
+
+    # 确定应用范围
+    total = len(clips)
+    if total <= 1:
+        # 只有一个片段时，只有 all 模式才应用
+        if body.apply_to != "all":
+            return BatchTransitionResponse(updated_count=0, plan_id=plan_id)
+
+    # 按 order 排序
+    clips_sorted = sorted(clips, key=lambda c: c.order)
+    indices_to_update = []
+
+    if body.apply_to == "all":
+        indices_to_update = list(range(total))
+    elif body.apply_to == "except_first":
+        indices_to_update = list(range(1, total))
+    elif body.apply_to == "except_last":
+        indices_to_update = list(range(total - 1))
+    elif body.apply_to == "middle":
+        if total <= 2:
+            indices_to_update = []
+        else:
+            indices_to_update = list(range(1, total - 1))
+    else:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"无效的 apply_to: {body.apply_to}",
+        )
+
+    # 批量更新
+    count = 0
+    for idx in indices_to_update:
+        clip = clips_sorted[idx]
+        svc.update_clip(
+            clip.id,
+            transition_effect=effect,
+            transition_duration=duration,
+        )
+        count += 1
+
+    logger.info(
+        "批量更新转场: plan_id=%s count=%d effect=%s apply_to=%s by user=%s",
+        plan_id,
+        count,
+        effect,
+        body.apply_to,
+        current_user.user.id,
+    )
+    return BatchTransitionResponse(updated_count=count, plan_id=plan_id)

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

@@ -427,3 +427,53 @@ def retry_generation_task(
             detail="系统繁忙，请稍后再试",
         ) from None
     return _to_generation_task_response(retried)
+
+
+@router.post("/tasks/{task_id}/cancel", response_model=GenerationTaskResponse)
+def cancel_generation_task(
+    task_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    generation_task_repository: Any = Depends(get_generation_task_repository),
+) -> GenerationTaskResponse:
+    """取消生成任务。
+
+    仅 pending / running 状态的任务可取消；取消后状态变为 cancelled。
+    对于已在运行的 Celery 任务，标记为 cancelled 后，worker 在下次检查点会中止执行。
+    """
+    task = generation_task_repository.get(task_id)
+    if task is None:
+        raise HTTPException(status_code=404, detail="Generation task not found")
+
+    # 权限校验
+    if task.created_by_user_id and task.created_by_user_id != authenticated_user.user.id:
+        raise HTTPException(status_code=403, detail="Access denied to this task")
+
+    status_val = task.status.value if hasattr(task.status, "value") else str(task.status)
+
+    # 终态不可取消
+    if status_val in ("completed", "failed", "cancelled"):
+        raise HTTPException(
+            status_code=409,
+            detail=f"Cannot cancel task in {status_val} status",
+        )
+
+    # 执行取消
+    try:
+        task.mark_cancelled()
+        task.append_log(
+            stage="cancelled",
+            message="用户主动取消任务",
+            level="INFO",
+            cancelled_by=authenticated_user.user.id,
+        )
+        generation_task_repository.update(task)
+        logger.info(
+            "生成任务已取消: task_id=%s user_id=%s previous_status=%s",
+            task_id,
+            authenticated_user.user.id,
+            status_val,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+    return _to_generation_task_response(task)

apps/api/app/api/routes/task_center.py

@@ -24,8 +24,6 @@ from app.schemas.task_center import (
 from fastapi import APIRouter, Depends, HTTPException, Query
 
 from packages.application import (
-    CreateGenerationTaskCommand,
-    CreateGenerationTaskUseCase,
     RetryGenerationTaskUseCase,
     SubmitIngestJobCommand,
     SubmitIngestJobUseCase,

apps/api/app/api/routes/videos.py

@@ -1,7 +1,5 @@
 import logging
-import uuid
 
-from app.api.routes._helpers import check_project_access
 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
@@ -110,7 +108,9 @@ def update_video_review_status(
     item = use_case.execute(video_id, request.review_status)
     if item is None:
         raise HTTPException(status_code=404, detail="Video not found")
-    logger.info("Video %s review status updated to %s by user %s", video_id, request.review_status, current_user.user_id)
+    logger.info(
+        "Video %s review status updated to %s by user %s", video_id, request.review_status, current_user.user_id
+    )
     return _to_video_response(item, storage)
 
 
@@ -121,7 +121,7 @@ def batch_download_videos(
     current_user: AuthenticatedUser = Depends(get_current_user),
 ):
     """批量下载成片，异步打包 zip。
-    
+
     传入 video_ids 列表，创建一个批量下载任务，任务完成后返回 zip 下载链接。
     """
     if not request.video_ids:
@@ -154,7 +154,7 @@ def get_batch_download_status(
     from celery.result import AsyncResult
 
     task = AsyncResult(job_id, app=celery_app)
-    
+
     status_map = {
         "PENDING": "pending",
         "STARTED": "running",

apps/api/app/services/cover_service.py

@@ -0,0 +1,276 @@
+"""封面管理服务.
+
+提供封面配置管理和从视频抽帧生成封面的能力。
+抽帧使用 FFmpeg，上传使用共享存储服务。
+"""
+
+from __future__ import annotations
+
+import logging
+import tempfile
+from pathlib import Path
+from typing import Any, Dict
+
+logger = logging.getLogger(__name__)
+
+
+# ── 常量 ──────────────────────────────────────────────────────────────────────
+
+DEFAULT_COVER_WIDTH = 1080
+DEFAULT_COVER_HEIGHT = 1920
+DEFAULT_COVER_QUALITY = 5  # JPEG quality (1-31, 越小越好)
+COVER_STORAGE_PREFIX = "covers"
+
+
+class CoverService:
+    """封面管理服务."""
+
+    def __init__(self, storage_service: Any, asset_repository: Any) -> None:
+        self._storage = storage_service
+        self._asset_repo = asset_repository
+
+    # ── 配置读写 ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def get_cover_config(plan_config: Dict[str, Any]) -> Dict[str, Any]:
+        """从 plan.config 中提取封面配置.
+
+        Args:
+            plan_config: 剪辑计划的 config 字段
+
+        Returns:
+            封面配置 dict
+        """
+        cover = plan_config.get("cover", {})
+        if not isinstance(cover, dict):
+            cover = {}
+        # 确保默认字段存在
+        return {
+            "type": cover.get("type", "ai_frame"),
+            "image_url": cover.get("image_url", ""),
+            "frame_time": cover.get("frame_time"),
+        }
+
+    # ── 抽帧生成封面 ──────────────────────────────────────────────────────
+
+    def extract_cover_from_clip(
+        self,
+        plan_id: str,
+        asset_id: str,
+        frame_time: float = 1.0,
+        *,
+        width: int = DEFAULT_COVER_WIDTH,
+        height: int = DEFAULT_COVER_HEIGHT,
+        quality: int = DEFAULT_COVER_QUALITY,
+    ) -> Dict[str, Any]:
+        """从指定素材的指定时间点抽取一帧作为封面.
+
+        Args:
+            plan_id: 剪辑计划 ID（用于生成存储路径）
+            asset_id: 素材 ID
+            frame_time: 抽帧时间点（秒）
+            width: 输出宽度
+            height: 输出高度
+            quality: JPEG 质量
+
+        Returns:
+            封面数据 dict，包含 type / image_url / frame_time
+
+        Raises:
+            ValueError: 素材不存在或不是视频
+            RuntimeError: 抽帧或上传失败
+        """
+        # 1. 获取素材
+        asset = self._asset_repo.get(asset_id) if self._asset_repo else None
+        if not asset:
+            raise ValueError(f"素材不存在: {asset_id}")
+
+        storage_key = getattr(asset, "storage_key", "")
+        if not storage_key:
+            raise ValueError(f"素材没有文件: {asset_id}")
+
+        mime_type = getattr(asset, "mime_type", "")
+        if mime_type and not mime_type.startswith("video"):
+            raise ValueError(f"素材不是视频类型: {mime_type}")
+
+        # 2. 下载视频到临时目录
+        with tempfile.TemporaryDirectory(prefix="cover_extract_") as tmp_dir:
+            tmp_path = Path(tmp_dir)
+            video_path = tmp_path / f"source_{asset_id[:8]}"
+
+            logger.info("下载素材用于封面抽帧: asset_id=%s", asset_id)
+            try:
+                self._storage.download_file(storage_key, str(video_path))
+            except Exception as e:
+                raise RuntimeError(f"下载素材失败: {e}") from e
+
+            if not video_path.exists() or video_path.stat().st_size == 0:
+                raise RuntimeError("下载的素材文件为空")
+
+            # 3. FFmpeg 抽帧
+            output_path = tmp_path / "cover.jpg"
+            self._extract_frame(
+                video_path=video_path,
+                output_path=output_path,
+                time_sec=frame_time,
+                width=width,
+                height=height,
+                quality=quality,
+            )
+
+            if not output_path.exists() or output_path.stat().st_size == 0:
+                raise RuntimeError("封面抽帧失败")
+
+            # 4. 上传到 OSS
+            cover_key = f"{COVER_STORAGE_PREFIX}/{plan_id}/cover_{int(frame_time * 1000)}.jpg"
+            logger.info("上传封面到存储: key=%s", cover_key)
+
+            try:
+                self._storage.upload_file(
+                    file_or_path=str(output_path),
+                    storage_key=cover_key,
+                    content_type="image/jpeg",
+                )
+            except Exception as e:
+                raise RuntimeError(f"上传封面失败: {e}") from e
+
+            # 5. 获取访问 URL
+            try:
+                image_url = self._storage.get_url(cover_key)
+            except Exception:
+                image_url = cover_key  # 降级为 storage_key
+
+        logger.info(
+            "封面抽帧完成: plan_id=%s asset_id=%s time=%.2fs size=%d",
+            plan_id,
+            asset_id,
+            frame_time,
+            output_path.stat().st_size if output_path.exists() else 0,
+        )
+
+        return {
+            "type": "manual",
+            "image_url": image_url,
+            "frame_time": frame_time,
+        }
+
+    def generate_smart_cover(
+        self,
+        plan_id: str,
+        asset_id: str,
+        *,
+        width: int = DEFAULT_COVER_WIDTH,
+        height: int = DEFAULT_COVER_HEIGHT,
+        quality: int = DEFAULT_COVER_QUALITY,
+    ) -> Dict[str, Any]:
+        """智能选帧：从视频中选取多帧，选最清晰的一帧.
+
+        Args:
+            plan_id: 剪辑计划 ID
+            asset_id: 素材 ID
+            width: 输出宽度
+            height: 输出高度
+            quality: JPEG 质量
+
+        Returns:
+            封面数据 dict
+        """
+        # 简单实现：取视频 1/3 处的帧作为智能封面
+        # 更复杂的多帧选清晰帧可以后续优化
+        frame_time = 3.0  # 默认第3秒，后续可以根据视频时长动态计算
+
+        result = self.extract_cover_from_clip(
+            plan_id=plan_id,
+            asset_id=asset_id,
+            frame_time=frame_time,
+            width=width,
+            height=height,
+            quality=quality,
+        )
+        result["type"] = "ai_frame"
+        return result
+
+    # ── 内部方法 ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _extract_frame(
+        video_path: Path,
+        output_path: Path,
+        *,
+        time_sec: float,
+        width: int,
+        height: int,
+        quality: int,
+    ) -> None:
+        """使用 FFmpeg 从视频中抽取一帧.
+
+        Args:
+            video_path: 视频文件路径
+            output_path: 输出图片路径
+            time_sec: 抽帧时间点（秒）
+            width: 输出宽度
+            height: 输出高度
+            quality: JPEG 质量
+        """
+        import subprocess
+
+        # scale + crop 实现 cover 裁剪
+        vf = f"scale={width}:{height}:force_original_aspect_ratio=increase," f"crop={width}:{height}"
+
+        command = [
+            "ffmpeg",
+            "-y",
+            "-ss",
+            f"{time_sec:.3f}",
+            "-i",
+            str(video_path),
+            "-vframes",
+            "1",
+            "-vf",
+            vf,
+            "-q:v",
+            str(quality),
+            "-f",
+            "mjpeg",
+            str(output_path),
+        ]
+
+        logger.debug("FFmpeg 抽帧命令: %s", " ".join(command))
+
+        try:
+            result = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+            if result.returncode != 0:
+                logger.warning("FFmpeg 抽帧返回非零: %s\nstderr: %s", result.returncode, result.stderr[-500:])
+                # 尝试不使用 scale+crop 的简化命令
+                simple_command = [
+                    "ffmpeg",
+                    "-y",
+                    "-ss",
+                    f"{time_sec:.3f}",
+                    "-i",
+                    str(video_path),
+                    "-vframes",
+                    "1",
+                    "-q:v",
+                    str(quality),
+                    "-f",
+                    "mjpeg",
+                    str(output_path),
+                ]
+                result2 = subprocess.run(
+                    simple_command,
+                    capture_output=True,
+                    text=True,
+                    timeout=60,
+                )
+                if result2.returncode != 0:
+                    raise RuntimeError(f"FFmpeg 抽帧失败: {result2.stderr[-300:]}")
+        except subprocess.TimeoutExpired as e:
+            raise RuntimeError("FFmpeg 抽帧超时") from e
+        except FileNotFoundError as e:
+            raise RuntimeError("FFmpeg 不可用") from e

apps/api/app/services/edit_plan_service.py

@@ -504,6 +504,406 @@ class EditPlanService:
         return created
 
     # ── 渲染生成流程 ────────────────────────────────────────────────────────
+    # ── 片段分割与合并 ──────────────────────────────────────────────────────
+
+    def split_clip(self, clip_id: str, split_time: float) -> Dict[str, Any]:
+        """将一个片段从指定位置分割为两个片段
+
+        Args:
+            clip_id: 要分割的片段 ID
+            split_time: 分割点（相对于片段起始的秒数），必须在 (0, duration) 范围内
+
+        Returns:
+            dict: {"left_clip": EditPlanClip, "right_clip": EditPlanClip}
+
+        Raises:
+            ValueError: 片段不存在、分割时间越界
+        """
+        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}")
+
+        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
+        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)
+
+        # 创建右半部分新片段（继承原片段的大部分属性）
+        right_config = dict(clip.config) if clip.config else {}
+        # 素材裁剪信息
+        if clip.asset_id:
+            # 右半部分从 split_time 开始播放
+            right_config["trim_start"] = left_duration
+            # 左半部分在 split_time 处结束
+            left_config = dict(left_clip.config) if left_clip.config else {}
+            left_config["trim_end"] = right_duration
+            left_clip.config = left_config
+            left_clip = self._clip_repo.update(left_clip)
+
+        right_clip = EditPlanClip.create(
+            plan_id=plan_id,
+            clip_type=clip.clip_type,
+            order=original_order + 1,
+            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,
+            transition_effect=clip.transition_effect,
+            transition_duration=clip.transition_duration,
+            playback_speed=clip.playback_speed,
+            config=right_config,
+        )
+        created_right = self._clip_repo.create(right_clip)
+
+        logger.info(
+            "分割片段: clip_id=%s plan_id=%s split_time=%.3fs left_dur=%.3fs right_dur=%.3fs",
+            clip_id,
+            plan_id,
+            split_time,
+            left_duration,
+            right_duration,
+        )
+
+        return {
+            "left_clip": left_clip,
+            "right_clip": created_right,
+        }
+
+    def merge_clips(self, clip_ids: List[str]) -> EditPlanClip:
+        """合并多个连续片段为一个片段
+
+        Args:
+            clip_ids: 要合并的片段 ID 列表（至少2个），必须属于同一个计划且 order 连续
+
+        Returns:
+            EditPlanClip: 合并后的新片段
+
+        Raises:
+            ValueError: 数量不足、不属于同一计划、不连续、类型不一致
+        """
+        if len(clip_ids) < 2:
+            raise ValueError("至少需要 2 个片段才能合并")
+
+        # 读取所有片段
+        clips = []
+        for cid in clip_ids:
+            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("只能合并相同类型的片段")
+
+        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
+        # 转场保留第一个的（合并后的入点转场）
+        # playback_speed 取第一个的
+        merged_clip = self._clip_repo.update(first_clip)
+
+        # 删除其余片段
+        for c in clips[1:]:
+            self._clip_repo.delete(c.id)
+
+        # 后面的片段 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)
+
+        logger.info(
+            "合并片段: plan_id=%s count=%d total_duration=%.3fs",
+            plan_id,
+            len(clips),
+            total_duration,
+        )
+
+        return merged_clip
+
+    # ── 字幕管理 ──────────────────────────────────────────────────────────
+
+    def list_subtitles(self, clip_id: str) -> List[Dict[str, Any]]:
+        """获取片段的所有字幕
+
+        Returns:
+            List[dict]: 字幕列表，按 start 时间排序
+        """
+        clip = self.get_clip_or_raise(clip_id)
+        config = clip.config or {}
+        subtitles = config.get("subtitles", [])
+        # 按开始时间排序
+        subtitles.sort(key=lambda s: s.get("start", 0))
+        return subtitles
+
+    def get_subtitle(self, clip_id: str, subtitle_id: str) -> Optional[Dict[str, Any]]:
+        """获取单条字幕"""
+        subtitles = self.list_subtitles(clip_id)
+        for s in subtitles:
+            if s.get("id") == subtitle_id:
+                return s
+        return None
+
+    def add_subtitle(
+        self,
+        clip_id: str,
+        start: float,
+        end: float,
+        text: str,
+        *,
+        style: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """添加一条字幕
+
+        Args:
+            clip_id: 片段 ID
+            start: 开始时间（秒，相对于片段）
+            end: 结束时间（秒）
+            text: 字幕文本
+            style: 样式配置（字体、大小、颜色、位置等）
+
+        Returns:
+            dict: 新增的字幕条目
+
+        Raises:
+            ValueError: 时间非法或文本为空
+        """
+        clip = self.get_clip_or_raise(clip_id)
+
+        if start < 0 or end <= start:
+            raise ValueError(f"字幕时间非法: start={start}, end={end}")
+        if not text.strip():
+            raise ValueError("字幕文本不能为空")
+        if end > clip.duration + 0.001:
+            raise ValueError(f"字幕结束时间不能超过片段时长: end={end:.3f}, duration={clip.duration:.3f}")
+
+        self._auto_resume_editing(clip.plan_id)
+
+        from uuid import uuid4
+
+        config = dict(clip.config) if clip.config else {}
+        subtitles = list(config.get("subtitles", []))
+
+        subtitle = {
+            "id": uuid4().hex,
+            "start": round(start, 3),
+            "end": round(end, 3),
+            "text": text.strip(),
+            "style": style or {},
+        }
+        subtitles.append(subtitle)
+        subtitles.sort(key=lambda s: s.get("start", 0))
+
+        config["subtitles"] = subtitles
+        clip.config = config
+        self._clip_repo.update(clip)
+
+        logger.info(
+            "添加字幕: clip_id=%s subtitle_id=%s start=%.3fs end=%.3fs",
+            clip_id,
+            subtitle["id"],
+            start,
+            end,
+        )
+
+        return subtitle
+
+    def update_subtitle(
+        self,
+        clip_id: str,
+        subtitle_id: str,
+        *,
+        start: Optional[float] = None,
+        end: Optional[float] = None,
+        text: Optional[str] = None,
+        style: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """更新一条字幕
+
+        Returns:
+            dict: 更新后的字幕条目
+
+        Raises:
+            ValueError: 字幕不存在或参数非法
+        """
+        clip = self.get_clip_or_raise(clip_id)
+        config = dict(clip.config) if clip.config else {}
+        subtitles = list(config.get("subtitles", []))
+
+        found = False
+        for i, s in enumerate(subtitles):
+            if s.get("id") == subtitle_id:
+                # 更新字段
+                updated_s = dict(s)
+                if start is not None:
+                    updated_s["start"] = round(start, 3)
+                if end is not None:
+                    updated_s["end"] = round(end, 3)
+                if text is not None:
+                    if not text.strip():
+                        raise ValueError("字幕文本不能为空")
+                    updated_s["text"] = text.strip()
+                if style is not None:
+                    updated_s["style"] = style
+
+                # 校验时间
+                if updated_s["start"] < 0 or updated_s["end"] <= updated_s["start"]:
+                    raise ValueError(f"字幕时间非法: start={updated_s['start']}, end={updated_s['end']}")
+                if updated_s["end"] > clip.duration + 0.001:
+                    raise ValueError("字幕结束时间不能超过片段时长")
+
+                subtitles[i] = updated_s
+                found = True
+                break
+
+        if not found:
+            raise ValueError(f"字幕不存在: {subtitle_id}")
+
+        self._auto_resume_editing(clip.plan_id)
+
+        subtitles.sort(key=lambda s: s.get("start", 0))
+        config["subtitles"] = subtitles
+        clip.config = config
+        self._clip_repo.update(clip)
+
+        logger.info("更新字幕: clip_id=%s subtitle_id=%s", clip_id, subtitle_id)
+
+        return subtitles[next(i for i, s in enumerate(subtitles) if s["id"] == subtitle_id)]
+
+    def delete_subtitle(self, clip_id: str, subtitle_id: str) -> bool:
+        """删除一条字幕
+
+        Returns:
+            bool: 是否删除成功
+        """
+        clip = self.get_clip_or_raise(clip_id)
+        config = dict(clip.config) if clip.config else {}
+        subtitles = list(config.get("subtitles", []))
+
+        new_subtitles = [s for s in subtitles if s.get("id") != subtitle_id]
+        if len(new_subtitles) == len(subtitles):
+            return False
+
+        self._auto_resume_editing(clip.plan_id)
+
+        config["subtitles"] = new_subtitles
+        clip.config = config
+        self._clip_repo.update(clip)
+
+        logger.info("删除字幕: clip_id=%s subtitle_id=%s", clip_id, subtitle_id)
+        return True
+
+    def batch_update_subtitles(
+        self,
+        clip_id: str,
+        subtitles: List[Dict[str, Any]],
+    ) -> List[Dict[str, Any]]:
+        """批量更新字幕（全量替换，用于批量编辑或导入）
+
+        Args:
+            clip_id: 片段 ID
+            subtitles: 字幕列表，每条需包含 start/end/text，已有 id 则保留
+
+        Returns:
+            List[dict]: 更新后的字幕列表
+        """
+        clip = self.get_clip_or_raise(clip_id)
+
+        from uuid import uuid4
+
+        validated = []
+        for s in subtitles:
+            start = float(s.get("start", 0))
+            end = float(s.get("end", 0))
+            text = str(s.get("text", ""))
+
+            if start < 0 or end <= start:
+                raise ValueError(f"字幕时间非法: start={start}, end={end}")
+            if not text.strip():
+                continue  # 跳过空字幕
+            if end > clip.duration + 0.001:
+                raise ValueError(f"字幕结束时间不能超过片段时长: end={end}")
+
+            subtitle_id = s.get("id") or uuid4().hex
+            validated.append(
+                {
+                    "id": subtitle_id,
+                    "start": round(start, 3),
+                    "end": round(end, 3),
+                    "text": text.strip(),
+                    "style": s.get("style", {}),
+                }
+            )
+
+        validated.sort(key=lambda s: s["start"])
+
+        self._auto_resume_editing(clip.plan_id)
+
+        config = dict(clip.config) if clip.config else {}
+        config["subtitles"] = validated
+        clip.config = config
+        self._clip_repo.update(clip)
+
+        logger.info(
+            "批量更新字幕: clip_id=%s count=%d",
+            clip_id,
+            len(validated),
+        )
+
+        return validated
 
     def get_plan_with_clips(self, plan_id: str) -> Dict[str, Any]:
         """获取计划及其所有片段

apps/api/app/services/edit_template_service.py

@@ -17,8 +17,6 @@ from packages.adapters.sqlalchemy_impl import (
     SQLAlchemyEditTemplateRepository,
     SQLAlchemyTemplateClipConfigRepository,
 )
-from packages.domain.edit_plan import EditPlan
-from packages.domain.edit_plan_clip import EditPlanClip
 from packages.domain.edit_template import EditTemplate, EditTemplateStatus
 from packages.domain.template_clip_config import (
     ClipType,

apps/api/app/services/plan_generator_service.py

@@ -99,6 +99,11 @@ class PlanGeneratorService:
         # 3. 生成片段列表
         if clip_configs:
             clips = self._create_clips_from_configs(plan.id, clip_configs)
+            # 模板 clip_config 的 clip_type 是 ClipType 枚举（main/intro/outro 等），
+            # 但 PIP / VOICE_PIP 模式需要特定的 clip_type（overlay/background/corner_voice/b_roll）
+            # 才能让素材分配和渲染分层正确工作。
+            # 这里将 MAIN 类型的片段按顺序映射为对应模式的角色类型。
+            self._map_clip_types_for_mode(clips, editing_mode)
         else:
             clips = self._generate_default_clips(plan.id, editing_mode, len(asset_ids))
 
@@ -195,6 +200,41 @@ class PlanGeneratorService:
 
         return clips
 
+    def _map_clip_types_for_mode(self, clips: List[EditPlanClip], editing_mode: str) -> None:
+        """将模板 clip_config 生成的 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 不变
+        """
+        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 不变，无需处理
+
     def _generate_default_clips(
         self,
         plan_id: str,

apps/api/app/services/video_compose_service.py

@@ -219,7 +219,7 @@ class VideoComposeService:
         根据 EditPlan 的所有 ready 片段，生成完整的 filter_complex 命令。
 
         滤镜链逻辑：
-        - 每个片段：scale → crop → setpts → trim → atrim
+        - 每个片段：scale → crop → fps → setpts → trim → atrim
         - 多片段之间：concat 滤镜 或 xfade 转场
         - 最终输出：-map '[outv]' -map '[outa]'（如有音频）
         """
@@ -406,20 +406,26 @@ class VideoComposeService:
         滤镜顺序：
         1. scale — 等比缩放到目标分辨率（保证覆盖）
         2. crop — 居中裁剪到目标分辨率
-        3. setpts — 重置时间戳 + 偏移
-        4. trim — 视频时长裁剪
-        5. atrim — 音频时长裁剪（如有音频流）
+        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: 等比缩放，保证覆盖目标区域（scale to larger, then crop）
-        filters.append(f"scale={output_width}:{output_height}" f":force_original_aspect_ratio=increase")
+        # 1. scale: 等比缩放（保持比例，不裁剪）
+        filters.append(f"scale={output_width}:{output_height}" f":force_original_aspect_ratio=decrease")
 
-        # 2. crop: 居中裁剪
-        filters.append(f"crop={output_width}:{output_height}")
+        # 2. pad: 居中+留黑边到目标分辨率（保持原始比例，不裁剪内容）
+        filters.append(f"pad={output_width}:{output_height}:(ow-iw)/2:(oh-ih)/2:black")
+
+        # 3. fps: 统一帧率（concat 要求所有输入帧率一致）
+        # 放在 pad 之后、setpts 之前，确保分辨率和帧率都已统一
+        if fps and fps > 0:
+            filters.append(f"fps={fps}")
 
         # 3. setpts: 重置时间戳
         if start > 0:
@@ -532,11 +538,17 @@ def _build_concat_filter(
     concat_filter = f"{concat_inputs}concat=n={n}:v=1:a=0[outv]"
     parts.append(concat_filter)
 
-    # 音频 concat（如果有）
+    # 音频 concat（如果有）— 先统一音频格式再拼接，否则不同采样率/声道会导致concat失败
     audio_parts: list[str] = []
     for idx, chain in enumerate(clip_chains):
         if chain.audio_label:
-            audio_parts.append(f"[{idx}:a]atrim=0:{chain.duration},asetpts=PTS-STARTPTS[{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)

apps/web/.eslintrc.cjs

@@ -18,6 +18,6 @@ module.exports = {
       { allowConstantExport: true },
     ],
     "@typescript-eslint/no-explicit-any": "warn",
-    "@typescript-eslint/no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
+    "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
   },
 };

apps/web/e2e/assets-full.spec.ts

@@ -299,13 +299,6 @@ test.describe("素材库页面 - 完整交互测试", () => {
       videoLibName,
       "video",
     );
-    const imageLibId = await createLibrary(
-      request,
-      headers,
-      projectId,
-      imageLibName,
-      "image",
-    );
 
     // 在视频库里创建一个素材
     await createAsset(

apps/web/e2e/duplication.spec.ts

@@ -383,7 +383,7 @@ test.describe("去重流程", () => {
 
   test("去重记录删除 - API 验证", async ({ page, request }) => {
     await routeBrowserApiToTestApi(page);
-    const { headers, userId, accessToken, email, username } =
+    const { headers } =
       await createAuthedUser(request, "dup-delete");
 
     // 创建查重记录

apps/web/e2e/profile.spec.ts

@@ -406,7 +406,7 @@ test.describe("个人设置 - 退出登录", () => {
   test.describe.configure({ timeout: 120_000 });
 
   test("登出 API - 正向", async ({ request }) => {
-    const { headers, email } = await createAuthedUser(
+    const { headers } = await createAuthedUser(
       request,
       "profile-logout",
     );

apps/web/e2e/register.spec.ts

@@ -152,7 +152,7 @@ test.describe("注册页面", () => {
 
   // ─── 成功注册 ──────────────────────────────────────
 
-  test("成功注册 - 提交有效表单", async ({ page, request }) => {
+  test("成功注册 - 提交有效表单", async ({ page, _request }) => {
     const email = uniqueEmail("reg-ui-ok");
     const username = uniqueUsername("reguiok");
 

apps/web/e2e/titles-full.spec.ts

@@ -558,7 +558,6 @@ test.describe("标题库 - 批量操作", () => {
     });
 
     // 检查是否有批量操作相关 UI
-    const checkboxes = page.locator(".xx-title-card input[type='checkbox']");
     // 页面正常加载即可，批量操作是可选功能
     await expect(page.locator(".xx-titles-page")).toBeVisible();
   });

apps/web/e2e/voice-clone.spec.ts

@@ -162,7 +162,6 @@ test.describe("声音克隆页面 - 页面加载", () => {
     });
 
     // 验证页面标题包含"克隆"或"音色"相关文字
-    const pageTitle = page.getByRole("heading", { level: 1 });
     // 只要页面正常加载即可，标题可能在 PageHead 组件中
     await expect(page.locator(".vc-page")).toBeVisible();
   });
@@ -186,7 +185,6 @@ test.describe("声音克隆页面 - 页面加载", () => {
     });
 
     // 验证克隆新音色按钮存在
-    const cloneBtn = page.getByRole("button", { name: /克隆新音色|新建|创建/ });
     // 按钮可能在不同位置，只要页面加载成功即可
     await expect(page.locator(".vc-page")).toBeVisible();
   });

apps/web/e2e/voices.spec.ts

@@ -311,9 +311,6 @@ test.describe("音色库 - 我的克隆音色", () => {
     });
 
     // 验证创建克隆音色按钮存在（可能是"克隆音色"或"新建"按钮）
-    const createBtn = page.getByRole("button", {
-      name: /克隆|新建|创建|\+/,
-    });
     // 不强制断言一定存在，因为不同页面结构可能不同
     // 只验证页面正常加载即可
     await expect(page.locator(".xx-voices-page")).toBeVisible();
@@ -372,7 +369,6 @@ test.describe("音色库 - 搜索和筛选", () => {
     });
 
     // 验证筛选相关元素存在（可能是下拉选择器或标签）
-    const filterSelect = page.locator("select, .xx-voices-filter");
     // 页面正常加载即通过
     await expect(page.locator(".xx-voices-page")).toBeVisible();
   });

apps/web/src/api/editPlans.ts

@@ -20,7 +20,7 @@ import type {
 
 /** 剪辑计划状态枚举 */
 export type EditPlanStatus =
-  "draft" | "editing" | "rendering" | "completed" | "failed";
+  "draft" | "editing" | "rendering" | "completed" | "failed" | "cancelled";
 
 /** 标题配置（对齐后端 title_config） */
 export interface TitleConfig {
@@ -276,24 +276,6 @@ export interface CoverResult {
  * 前端 UI 类型（EditingPlanner 组件依赖，保留兼容）
  * ============================================================ */
 
-/** 剪辑计划中的片段（UI 层类型） */
-export interface EditPlanClip {
-  id: string;
-  template_segment_id: string;
-  /** 素材库中的素材 ID */
-  media_asset_id?: string;
-  /** 素材类型 */
-  material_type: "video" | "image" | "audio" | "voiceover";
-  /** 片段文案 */
-  script_text: string;
-  /** 实际时长（秒） */
-  duration: number;
-  /** 转场效果 */
-  transition?: TransitionEffect;
-  /** 排序 */
-  order: number;
-}
-
 /** 转场效果（14 种预设） */
 export interface TransitionEffect {
   type:
@@ -453,6 +435,225 @@ export async function getGenerationTaskResults(
   return response.data.items || response.data || [];
 }
 
+/** 取消生成任务 */
+export async function cancelGeneration(planId: string): Promise<void> {
+  await apiClient.post(`/edit-plans/${planId}/cancel`);
+}
+
+/* ============================================================
+ * 片段 CRUD（后端 EditPlanClip 独立表）
+ * ============================================================ */
+
+/** 片段状态 */
+export type EditPlanClipStatus = "pending" | "processing" | "ready" | "failed";
+
+/** 剪辑片段（后端响应） */
+export interface EditPlanClip {
+  id: string;
+  plan_id: string;
+  clip_type: string; // main / intro / outro / overlay / background / b_roll 等
+  order: number;
+  asset_id: string;
+  text_content: string;
+  start_time: number;
+  duration: number;
+  transition_effect: string;
+  transition_duration: number;
+  playback_speed: number;
+  status: EditPlanClipStatus;
+  config: Record<string, unknown>;
+  created_at?: string;
+  updated_at?: string;
+}
+
+/** 创建片段请求 */
+export interface CreateEditPlanClipRequest {
+  clip_type: string;
+  order: number;
+  asset_id?: string;
+  text_content?: string;
+  start_time?: number;
+  duration?: number;
+  transition_effect?: string;
+  transition_duration?: number;
+  playback_speed?: number;
+  config?: Record<string, unknown>;
+}
+
+/** 更新片段请求 */
+export interface UpdateEditPlanClipRequest {
+  clip_type?: string;
+  order?: number;
+  asset_id?: string;
+  text_content?: string;
+  start_time?: number;
+  duration?: number;
+  transition_effect?: string;
+  transition_duration?: number;
+  playback_speed?: number;
+  config?: Record<string, unknown>;
+}
+
+/** 片段列表响应 */
+export interface EditPlanClipListResponse {
+  items: EditPlanClip[];
+  total: number;
+}
+
+/** 片段列表查询参数 */
+export interface EditPlanClipListParams {
+  status?: string;
+  skip?: number;
+  limit?: number;
+}
+
+/** 获取片段列表 */
+export async function getEditPlanClips(
+  planId: string,
+  params?: EditPlanClipListParams,
+): Promise<EditPlanClipListResponse> {
+  const response = await apiClient.get<EditPlanClipListResponse>(
+    `/edit-plans/${planId}/clips`,
+    { params },
+  );
+  return response.data;
+}
+
+/** 获取单个片段详情 */
+export async function getEditPlanClip(
+  planId: string,
+  clipId: string,
+): Promise<EditPlanClip> {
+  const response = await apiClient.get<EditPlanClip>(
+    `/edit-plans/${planId}/clips/${clipId}`,
+  );
+  return response.data;
+}
+
+/** 创建片段 */
+export async function createEditPlanClip(
+  planId: string,
+  data: CreateEditPlanClipRequest,
+): Promise<EditPlanClip> {
+  const response = await apiClient.post<EditPlanClip>(
+    `/edit-plans/${planId}/clips`,
+    data,
+  );
+  return response.data;
+}
+
+/** 更新片段 */
+export async function updateEditPlanClip(
+  planId: string,
+  clipId: string,
+  data: UpdateEditPlanClipRequest,
+): Promise<EditPlanClip> {
+  const response = await apiClient.put<EditPlanClip>(
+    `/edit-plans/${planId}/clips/${clipId}`,
+    data,
+  );
+  return response.data;
+}
+
+/** 删除片段 */
+export async function deleteEditPlanClip(
+  planId: string,
+  clipId: string,
+): Promise<void> {
+  await apiClient.delete(`/edit-plans/${planId}/clips/${clipId}`);
+}
+
+/* ============================================================
+ * 片段批量操作
+ * ============================================================ */
+
+/** 重排序条目 */
+export interface ClipReorderItem {
+  clip_id: string;
+  new_order: number;
+}
+
+/** 重排序响应 */
+export interface ClipReorderResponse {
+  success: boolean;
+  updated_count: number;
+  message: string;
+}
+
+/** 批量删除响应 */
+export interface ClipBatchDeleteResponse {
+  success: boolean;
+  deleted_count: number;
+  message: string;
+}
+
+/** 从素材批量创建响应 */
+export interface ClipsFromAssetsResponse {
+  success: boolean;
+  created_count: number;
+  message: string;
+  clip_ids: string[];
+}
+
+/** 片段重排序（拖拽排序后一次性提交） */
+export async function reorderEditPlanClips(
+  planId: string,
+  items: ClipReorderItem[],
+): Promise<ClipReorderResponse> {
+  const response = await apiClient.post<ClipReorderResponse>(
+    `/edit-plans/${planId}/clips/reorder`,
+    { items },
+  );
+  return response.data;
+}
+
+/** 批量删除片段 */
+export async function batchDeleteEditPlanClips(
+  planId: string,
+  clipIds: string[],
+): Promise<ClipBatchDeleteResponse> {
+  const response = await apiClient.post<ClipBatchDeleteResponse>(
+    `/edit-plans/${planId}/clips/batch-delete`,
+    { clip_ids: clipIds },
+  );
+  return response.data;
+}
+
+/** 从素材批量创建片段（追加到时间线末尾） */
+export async function createClipsFromAssets(
+  planId: string,
+  assetIds: string[],
+  clipType = "main",
+): Promise<ClipsFromAssetsResponse> {
+  const response = await apiClient.post<ClipsFromAssetsResponse>(
+    `/edit-plans/${planId}/clips/from-assets`,
+    { asset_ids: assetIds, clip_type: clipType },
+  );
+  return response.data;
+}
+
+/* ============================================================
+ * 复制计划
+ * ============================================================ */
+
+/** 复制计划请求 */
+export interface CopyEditPlanRequest {
+  name?: string;
+  project_id?: string;
+}
+
+/** 复制剪辑计划（含所有片段配置） */
+export async function copyEditPlan(
+  planId: string,
+  data?: CopyEditPlanRequest,
+): Promise<EditPlan> {
+  const response = await apiClient.post<EditPlan>(
+    `/edit-plans/${planId}/copy`,
+    data || {},
+  );
+  return response.data;
+}
+
 /**
  * 获取素材库列表 — 调用 GET /api/v1/assets?library_id=xxx
  * 将后端 AssetResponse 映射为前端 MediaAsset 类型
@@ -553,6 +754,7 @@ export const PLAN_STATUS_LABELS: Record<EditPlanStatus, string> = {
   rendering: "渲染中",
   completed: "已完成",
   failed: "失败",
+  cancelled: "已取消",
 };
 
 /** 质量分筛选选项 */

apps/web/src/pages/edit-plans/EditPlans.tsx

@@ -24,12 +24,17 @@ import {
   DeleteOutlined,
   FileTextOutlined,
   ThunderboltOutlined,
+  CopyOutlined,
+  UnorderedListOutlined,
+  StopOutlined,
 } from "@ant-design/icons";
 import type { ColumnsType } from "antd/es/table";
 import {
   getEditPlans,
   deleteEditPlan,
   generateEditPlan,
+  cancelGeneration,
+  copyEditPlan,
   type EditPlan,
   type EditPlanStatus,
   type EditPlanListParams,
@@ -47,6 +52,7 @@ const STATUS_TABS: { key: EditPlanStatus | "all"; label: string }[] = [
   { key: "rendering", label: "渲染中" },
   { key: "completed", label: "已完成" },
   { key: "failed", label: "失败" },
+  { key: "cancelled", label: "已取消" },
 ];
 
 /** 状态标签配置 */
@@ -79,6 +85,11 @@ const STATUS_CONFIG: Record<
     color: "error",
     icon: <CloseCircleOutlined />,
   },
+  cancelled: {
+    label: "已取消",
+    color: "default",
+    icon: <StopOutlined />,
+  },
 };
 
 /* ──────────── 工具函数 ──────────── */
@@ -184,6 +195,33 @@ export default function EditPlans() {
     },
   });
 
+  // 取消生成
+  const cancelMutation = useMutation({
+    mutationFn: cancelGeneration,
+    onSuccess: () => {
+      message.success("已提交取消请求");
+      queryClient.invalidateQueries({ queryKey: ["edit-plans"] });
+    },
+    onError: () => {
+      message.error("取消失败，请稍后重试");
+    },
+  });
+
+  // 复制计划
+  const copyMutation = useMutation({
+    mutationFn: ({ planId, name }: { planId: string; name?: string }) =>
+      copyEditPlan(planId, name ? { name } : undefined),
+    onSuccess: (newPlan) => {
+      message.success("计划已复制");
+      queryClient.invalidateQueries({ queryKey: ["edit-plans"] });
+      // 自动跳转到新计划的编辑器
+      navigate(`/app/editing-planner?planId=${newPlan.id}`);
+    },
+    onError: () => {
+      message.error("复制失败，请稍后重试");
+    },
+  });
+
   // 跳转到剪辑编辑器
   const handleEdit = useCallback(
     (plan: EditPlan) => {
@@ -285,10 +323,21 @@ export default function EditPlans() {
     {
       title: "操作",
       key: "action",
-      width: 180,
+      width: 240,
       fixed: "right",
       render: (_: unknown, record: EditPlan) => (
         <div className="plan-actions">
+          <Tooltip title="片段管理">
+            <Button
+              type="link"
+              size="small"
+              icon={<UnorderedListOutlined />}
+              onClick={() => navigate(`/app/edit-plans/${record.id}/clips`)}
+              className="plan-action-btn"
+            >
+              片段
+            </Button>
+          </Tooltip>
           <Button
             type="link"
             size="small"
@@ -298,7 +347,30 @@ export default function EditPlans() {
           >
             编辑
           </Button>
-          {(record.status === "failed" || record.status === "completed") && (
+          {record.status === "rendering" && (
+            <Popconfirm
+              title="确认取消生成"
+              description="确定要取消当前生成任务吗？此操作不可恢复。"
+              onConfirm={() => cancelMutation.mutate(record.id)}
+              okText="确定"
+              cancelText="再等等"
+              okButtonProps={{ danger: true }}
+            >
+              <Button
+                type="link"
+                size="small"
+                danger
+                icon={<StopOutlined />}
+                loading={cancelMutation.isPending}
+                className="plan-action-btn plan-cancel-btn"
+              >
+                取消生成
+              </Button>
+            </Popconfirm>
+          )}
+          {(record.status === "failed" ||
+            record.status === "completed" ||
+            record.status === "cancelled") && (
             <Popconfirm
               title="确认重新生成"
               description="确定要重新生成这个剪辑计划吗？"
@@ -317,6 +389,28 @@ export default function EditPlans() {
               </Button>
             </Popconfirm>
           )}
+          <Popconfirm
+            title="复制计划"
+            description="确定要复制这个剪辑计划吗？将创建一个编辑中的新副本。"
+            onConfirm={() =>
+              copyMutation.mutate({
+                planId: record.id,
+                name: `${record.name} 副本`,
+              })
+            }
+            okText="确定"
+            cancelText="取消"
+          >
+            <Button
+              type="link"
+              size="small"
+              icon={<CopyOutlined />}
+              loading={copyMutation.isPending}
+              className="plan-action-btn"
+            >
+              复制
+            </Button>
+          </Popconfirm>
           <Popconfirm
             title="确认删除"
             description="确定要删除这个剪辑计划吗？此操作不可恢复。"

apps/web/src/pages/edit-plans/PlanClipsManager.tsx

@@ -0,0 +1,658 @@
+/**
+ * 剪辑计划片段管理页面
+ * 对接后端 PR#389 片段 CRUD API
+ * 功能：列表查看、创建、编辑、删除、批量删除、拖拽排序、从素材导入
+ */
+import { useState, useCallback } from "react";
+import { useParams, useNavigate } from "react-router-dom";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  Table,
+  Button,
+  Space,
+  message,
+  Popconfirm,
+  Modal,
+  Form,
+  Input,
+  InputNumber,
+  Select,
+  Tag,
+  Drawer,
+  Empty,
+  Card,
+} from "antd";
+import {
+  ArrowLeftOutlined,
+  PlusOutlined,
+  DeleteOutlined,
+  EditOutlined,
+  UploadOutlined,
+  OrderedListOutlined,
+  SaveOutlined,
+} from "@ant-design/icons";
+import type { ColumnsType } from "antd/es/table";
+import {
+  getEditPlan,
+  getEditPlanClips,
+  createEditPlanClip,
+  updateEditPlanClip,
+  deleteEditPlanClip,
+  batchDeleteEditPlanClips,
+  reorderEditPlanClips,
+  createClipsFromAssets,
+  getMediaAssets,
+  type EditPlanClip,
+  type EditPlanClipStatus,
+} from "@/api/editPlans";
+import "./plan-clips.css";
+
+/* ──────────── 常量 ──────────── */
+
+const CLIP_TYPE_OPTIONS = [
+  { value: "main", label: "主片段" },
+  { value: "intro", label: "片头" },
+  { value: "outro", label: "片尾" },
+  { value: "overlay", label: "叠加层" },
+  { value: "background", label: "背景" },
+  { value: "b_roll", label: "B-roll" },
+];
+
+const STATUS_COLORS: Record<EditPlanClipStatus, string> = {
+  pending: "default",
+  processing: "processing",
+  ready: "success",
+  failed: "error",
+};
+
+const STATUS_LABELS: Record<EditPlanClipStatus, string> = {
+  pending: "待处理",
+  processing: "处理中",
+  ready: "就绪",
+  failed: "失败",
+};
+
+const TRANSITION_OPTIONS = [
+  { value: "cut", label: "硬切" },
+  { value: "fade", label: "淡入淡出" },
+  { value: "dissolve", label: "溶解" },
+  { value: "zoom", label: "缩放" },
+  { value: "slide_left", label: "左滑" },
+  { value: "slide_right", label: "右滑" },
+  { value: "slide_up", label: "上滑" },
+  { value: "slide_down", label: "下滑" },
+  { value: "wipe_left", label: "左擦除" },
+  { value: "wipe_right", label: "右擦除" },
+  { value: "wipe_up", label: "上擦除" },
+  { value: "wipe_down", label: "下擦除" },
+  { value: "circlecrop", label: "圆形裁切" },
+  { value: "rectcrop", label: "矩形裁切" },
+];
+
+/* ──────────── 组件 ──────────── */
+
+const PlanClipsManager: React.FC = () => {
+  const { planId } = useParams<{ planId: string }>();
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+
+  /* ── 计划信息 ── */
+  const { data: plan, isLoading: planLoading } = useQuery({
+    queryKey: ["editPlan", planId],
+    queryFn: () => getEditPlan(planId!),
+    enabled: !!planId,
+  });
+
+  /* ── 片段列表 ── */
+  const { data: clipsData, isLoading: clipsLoading } = useQuery({
+    queryKey: ["editPlanClips", planId],
+    queryFn: () => getEditPlanClips(planId!, { limit: 500 }),
+    enabled: !!planId,
+  });
+
+  const clips = clipsData?.items ?? [];
+
+  /* ── 选中的片段（批量操作） ── */
+  const [selectedRowKeys, setSelectedRowKeys] = useState<React.Key[]>([]);
+
+  /* ── 编辑弹窗 ── */
+  const [editModalOpen, setEditModalOpen] = useState(false);
+  const [editingClip, setEditingClip] = useState<EditPlanClip | null>(null);
+  const [editForm] = Form.useForm();
+  const [editLoading, setEditLoading] = useState(false);
+
+  /* ── 素材导入抽屉 ── */
+  const [importDrawerOpen, setImportDrawerOpen] = useState(false);
+  const [selectedAssetIds, setSelectedAssetIds] = useState<string[]>([]);
+  const [importLoading, setImportLoading] = useState(false);
+
+  const { data: assets } = useQuery({
+    queryKey: ["mediaAssets"],
+    queryFn: () => getMediaAssets(),
+    enabled: importDrawerOpen,
+  });
+
+  /* ── 重新排序模式 ── */
+  const [reorderMode, setReorderMode] = useState(false);
+  const [reorderItems, setReorderItems] = useState<EditPlanClip[]>([]);
+
+  /* ── 列定义 ── */
+  const columns: ColumnsType<EditPlanClip> = [
+    {
+      title: "序号",
+      dataIndex: "order",
+      width: 70,
+      render: (_, __, index) => index + 1,
+    },
+    {
+      title: "类型",
+      dataIndex: "clip_type",
+      width: 100,
+      render: (type: string) => {
+        const opt = CLIP_TYPE_OPTIONS.find((o) => o.value === type);
+        return <Tag>{opt?.label || type}</Tag>;
+      },
+    },
+    {
+      title: "素材",
+      dataIndex: "asset_id",
+      width: 150,
+      ellipsis: true,
+      render: (assetId: string) =>
+        assetId ? (
+          <code className="clip-asset-id">{assetId.slice(0, 12)}...</code>
+        ) : (
+          <span style={{ color: "#999" }}>无素材</span>
+        ),
+    },
+    {
+      title: "文本内容",
+      dataIndex: "text_content",
+      ellipsis: true,
+      render: (text: string) =>
+        text || <span style={{ color: "#999" }}>-</span>,
+    },
+    {
+      title: "时长",
+      dataIndex: "duration",
+      width: 90,
+      render: (d: number) => `${d?.toFixed(1) || 0}s`,
+    },
+    {
+      title: "转场",
+      dataIndex: "transition_effect",
+      width: 100,
+      render: (effect: string) => {
+        const opt = TRANSITION_OPTIONS.find((o) => o.value === effect);
+        return opt?.label || effect || "硬切";
+      },
+    },
+    {
+      title: "播放速度",
+      dataIndex: "playback_speed",
+      width: 90,
+      render: (s: number) => `${s || 1.0}x`,
+    },
+    {
+      title: "状态",
+      dataIndex: "status",
+      width: 90,
+      render: (status: EditPlanClipStatus) => (
+        <Tag color={STATUS_COLORS[status] || "default"}>
+          {STATUS_LABELS[status] || status}
+        </Tag>
+      ),
+    },
+    {
+      title: "操作",
+      key: "action",
+      width: 140,
+      fixed: "right",
+      render: (_, record) => (
+        <Space size="small">
+          <Button
+            type="link"
+            size="small"
+            icon={<EditOutlined />}
+            onClick={() => handleEditClip(record)}
+          >
+            编辑
+          </Button>
+          <Popconfirm
+            title="删除片段"
+            description="确定删除这个片段吗？"
+            onConfirm={() => handleDeleteClip(record.id)}
+            okText="确定"
+            cancelText="取消"
+            okButtonProps={{ danger: true }}
+          >
+            <Button type="link" size="small" danger icon={<DeleteOutlined />}>
+              删除
+            </Button>
+          </Popconfirm>
+        </Space>
+      ),
+    },
+  ];
+
+  /* ── 编辑片段 ── */
+  const handleEditClip = useCallback(
+    (clip: EditPlanClip) => {
+      setEditingClip(clip);
+      editForm.setFieldsValue({
+        clip_type: clip.clip_type,
+        asset_id: clip.asset_id,
+        text_content: clip.text_content,
+        duration: clip.duration,
+        start_time: clip.start_time,
+        transition_effect: clip.transition_effect,
+        transition_duration: clip.transition_duration,
+        playback_speed: clip.playback_speed,
+      });
+      setEditModalOpen(true);
+    },
+    [editForm],
+  );
+
+  const handleNewClip = useCallback(() => {
+    setEditingClip(null);
+    editForm.resetFields();
+    editForm.setFieldsValue({
+      clip_type: "main",
+      duration: 5,
+      transition_effect: "cut",
+      transition_duration: 0,
+      playback_speed: 1.0,
+    });
+    setEditModalOpen(true);
+  }, [editForm]);
+
+  const handleSaveClip = async () => {
+    if (!planId) return;
+    try {
+      const values = await editForm.validateFields();
+      setEditLoading(true);
+
+      if (editingClip) {
+        // 更新
+        await updateEditPlanClip(planId, editingClip.id, values);
+        message.success("片段已更新");
+      } else {
+        // 新建
+        const maxOrder =
+          clips.length > 0 ? Math.max(...clips.map((c) => c.order)) : -1;
+        await createEditPlanClip(planId, {
+          ...values,
+          order: maxOrder + 1,
+        });
+        message.success("片段已创建");
+      }
+
+      queryClient.invalidateQueries({ queryKey: ["editPlanClips", planId] });
+      setEditModalOpen(false);
+    } catch (err) {
+      console.error(err);
+      message.error(editingClip ? "更新失败" : "创建失败");
+    } finally {
+      setEditLoading(false);
+    }
+  };
+
+  /* ── 删除片段 ── */
+  const handleDeleteClip = async (clipId: string) => {
+    if (!planId) return;
+    try {
+      await deleteEditPlanClip(planId, clipId);
+      message.success("已删除");
+      queryClient.invalidateQueries({ queryKey: ["editPlanClips", planId] });
+      setSelectedRowKeys((prev) => prev.filter((k) => k !== clipId));
+    } catch {
+      message.error("删除失败");
+    }
+  };
+
+  /* ── 批量删除 ── */
+  const handleBatchDelete = async () => {
+    if (!planId || selectedRowKeys.length === 0) return;
+    try {
+      await batchDeleteEditPlanClips(
+        planId,
+        selectedRowKeys.map((k) => String(k)),
+      );
+      message.success(`已删除 ${selectedRowKeys.length} 个片段`);
+      queryClient.invalidateQueries({ queryKey: ["editPlanClips", planId] });
+      setSelectedRowKeys([]);
+    } catch {
+      message.error("批量删除失败");
+    }
+  };
+
+  /* ── 从素材导入 ── */
+  const handleImportFromAssets = async () => {
+    if (!planId || selectedAssetIds.length === 0) return;
+    try {
+      setImportLoading(true);
+      const res = await createClipsFromAssets(planId, selectedAssetIds);
+      message.success(`已导入 ${res.created_count} 个片段`);
+      queryClient.invalidateQueries({ queryKey: ["editPlanClips", planId] });
+      setImportDrawerOpen(false);
+      setSelectedAssetIds([]);
+    } catch {
+      message.error("导入失败");
+    } finally {
+      setImportLoading(false);
+    }
+  };
+
+  /* ── 排序模式 ── */
+  const enterReorderMode = () => {
+    setReorderItems([...clips].sort((a, b) => a.order - b.order));
+    setReorderMode(true);
+  };
+
+  const moveClip = (fromIndex: number, toIndex: number) => {
+    if (toIndex < 0 || toIndex >= reorderItems.length) return;
+    const newItems = [...reorderItems];
+    const [moved] = newItems.splice(fromIndex, 1);
+    newItems.splice(toIndex, 0, moved);
+    setReorderItems(newItems);
+  };
+
+  const saveReorder = async () => {
+    if (!planId) return;
+    const items = reorderItems.map((clip, index) => ({
+      clip_id: clip.id,
+      new_order: index,
+    }));
+    try {
+      await reorderEditPlanClips(planId, items);
+      message.success("排序已保存");
+      queryClient.invalidateQueries({ queryKey: ["editPlanClips", planId] });
+      setReorderMode(false);
+    } catch {
+      message.error("排序保存失败");
+    }
+  };
+
+  const cancelReorder = () => {
+    setReorderMode(false);
+    setReorderItems([]);
+  };
+
+  /* ── 渲染 ── */
+  const displayClips = reorderMode
+    ? reorderItems
+    : [...clips].sort((a, b) => a.order - b.order);
+
+  return (
+    <div className="plan-clips-page">
+      {/* 顶部 */}
+      <div className="plan-clips-header">
+        <div className="plan-clips-header-left">
+          <Button
+            type="text"
+            icon={<ArrowLeftOutlined />}
+            onClick={() => navigate("/app/edit-plans")}
+          >
+            返回计划列表
+          </Button>
+          <div className="plan-clips-title">
+            <h2>{plan?.name || "加载中..."}</h2>
+            <p>
+              {planLoading
+                ? "加载中..."
+                : `共 ${clipsData?.total || 0} 个片段 · ${plan?.status || ""}`}
+            </p>
+          </div>
+        </div>
+        <div className="plan-clips-header-right">
+          <Space>
+            <Button
+              icon={<UploadOutlined />}
+              onClick={() => setImportDrawerOpen(true)}
+            >
+              从素材导入
+            </Button>
+            {reorderMode ? (
+              <>
+                <Button onClick={cancelReorder}>取消排序</Button>
+                <Button
+                  type="primary"
+                  icon={<SaveOutlined />}
+                  onClick={saveReorder}
+                >
+                  保存排序
+                </Button>
+              </>
+            ) : (
+              <>
+                <Button
+                  icon={<OrderedListOutlined />}
+                  onClick={enterReorderMode}
+                  disabled={clips.length === 0}
+                >
+                  调整顺序
+                </Button>
+                <Button
+                  type="primary"
+                  icon={<PlusOutlined />}
+                  onClick={handleNewClip}
+                >
+                  添加片段
+                </Button>
+              </>
+            )}
+          </Space>
+        </div>
+      </div>
+
+      {/* 批量操作栏 */}
+      {!reorderMode && selectedRowKeys.length > 0 && (
+        <div className="plan-clips-batch-bar">
+          <span>已选择 {selectedRowKeys.length} 个片段</span>
+          <Popconfirm
+            title="批量删除"
+            description={`确定删除选中的 ${selectedRowKeys.length} 个片段吗？`}
+            onConfirm={handleBatchDelete}
+            okText="确定"
+            cancelText="取消"
+            okButtonProps={{ danger: true }}
+          >
+            <Button danger icon={<DeleteOutlined />}>
+              批量删除
+            </Button>
+          </Popconfirm>
+        </div>
+      )}
+
+      {/* 排序列表 */}
+      {reorderMode && (
+        <Card className="plan-clips-reorder-card" title="拖拽调整顺序">
+          <div className="plan-clips-reorder-list">
+            {reorderItems.map((clip, index) => (
+              <div key={clip.id} className="plan-clips-reorder-item">
+                <span className="reorder-index">{index + 1}</span>
+                <span className="reorder-type">
+                  {CLIP_TYPE_OPTIONS.find((o) => o.value === clip.clip_type)
+                    ?.label || clip.clip_type}
+                </span>
+                <span className="reorder-content">
+                  {clip.text_content || clip.asset_id || "无内容"}
+                </span>
+                <span className="reorder-duration">
+                  {clip.duration.toFixed(1)}s
+                </span>
+                <Space>
+                  <Button
+                    size="small"
+                    onClick={() => moveClip(index, index - 1)}
+                    disabled={index === 0}
+                  >
+                    ↑
+                  </Button>
+                  <Button
+                    size="small"
+                    onClick={() => moveClip(index, index + 1)}
+                    disabled={index === reorderItems.length - 1}
+                  >
+                    ↓
+                  </Button>
+                </Space>
+              </div>
+            ))}
+          </div>
+        </Card>
+      )}
+
+      {/* 片段列表 */}
+      {!reorderMode && (
+        <div className="plan-clips-table-wrap">
+          <Table
+            rowKey="id"
+            columns={columns}
+            dataSource={displayClips}
+            loading={clipsLoading}
+            rowSelection={{
+              selectedRowKeys,
+              onChange: setSelectedRowKeys,
+            }}
+            pagination={false}
+            locale={{
+              emptyText: (
+                <Empty
+                  description="暂无片段，点击上方按钮添加或从素材导入"
+                  image={Empty.PRESENTED_IMAGE_SIMPLE}
+                />
+              ),
+            }}
+            scroll={{ x: 1000 }}
+          />
+        </div>
+      )}
+
+      {/* 编辑弹窗 */}
+      <Modal
+        title={editingClip ? "编辑片段" : "添加片段"}
+        open={editModalOpen}
+        onCancel={() => setEditModalOpen(false)}
+        onOk={handleSaveClip}
+        confirmLoading={editLoading}
+        okText="保存"
+        cancelText="取消"
+        width={560}
+      >
+        <Form form={editForm} layout="vertical">
+          <Form.Item
+            label="片段类型"
+            name="clip_type"
+            rules={[{ required: true, message: "请选择类型" }]}
+          >
+            <Select options={CLIP_TYPE_OPTIONS} />
+          </Form.Item>
+          <Form.Item label="素材 ID" name="asset_id">
+            <Input placeholder="关联的素材 ID（可选）" />
+          </Form.Item>
+          <Form.Item label="文本内容" name="text_content">
+            <Input.TextArea rows={3} placeholder="字幕/配音文案等" />
+          </Form.Item>
+          <div style={{ display: "flex", gap: 16 }}>
+            <Form.Item
+              label="起始时间（秒）"
+              name="start_time"
+              style={{ flex: 1 }}
+            >
+              <InputNumber min={0} step={0.1} style={{ width: "100%" }} />
+            </Form.Item>
+            <Form.Item label="时长（秒）" name="duration" style={{ flex: 1 }}>
+              <InputNumber min={0} step={0.1} style={{ width: "100%" }} />
+            </Form.Item>
+          </div>
+          <div style={{ display: "flex", gap: 16 }}>
+            <Form.Item
+              label="转场效果"
+              name="transition_effect"
+              style={{ flex: 1 }}
+            >
+              <Select options={TRANSITION_OPTIONS} />
+            </Form.Item>
+            <Form.Item
+              label="转场时长"
+              name="transition_duration"
+              style={{ flex: 1 }}
+            >
+              <InputNumber min={0} step={0.1} style={{ width: "100%" }} />
+            </Form.Item>
+          </div>
+          <Form.Item label="播放速度" name="playback_speed">
+            <InputNumber
+              min={0.1}
+              max={10}
+              step={0.1}
+              style={{ width: "100%" }}
+            />
+          </Form.Item>
+        </Form>
+      </Modal>
+
+      {/* 素材导入抽屉 */}
+      <Drawer
+        title="从素材库导入"
+        open={importDrawerOpen}
+        onClose={() => setImportDrawerOpen(false)}
+        width={480}
+        extra={
+          <Button
+            type="primary"
+            onClick={handleImportFromAssets}
+            loading={importLoading}
+            disabled={selectedAssetIds.length === 0}
+          >
+            导入{" "}
+            {selectedAssetIds.length > 0 ? `(${selectedAssetIds.length})` : ""}
+          </Button>
+        }
+      >
+        {assets && assets.length > 0 ? (
+          <div className="asset-import-list">
+            {assets.map((asset) => (
+              <div
+                key={asset.id}
+                className={`asset-import-item ${
+                  selectedAssetIds.includes(asset.id) ? "selected" : ""
+                }`}
+                onClick={() => {
+                  setSelectedAssetIds((prev) =>
+                    prev.includes(asset.id)
+                      ? prev.filter((id) => id !== asset.id)
+                      : [...prev, asset.id],
+                  );
+                }}
+              >
+                <div className="asset-thumb">
+                  {asset.thumbnail_url ? (
+                    <img src={asset.thumbnail_url} alt={asset.name} />
+                  ) : (
+                    <div className="asset-thumb-placeholder">{asset.type}</div>
+                  )}
+                </div>
+                <div className="asset-info">
+                  <div className="asset-name" title={asset.name}>
+                    {asset.name}
+                  </div>
+                  <div className="asset-meta">
+                    {asset.type}
+                    {asset.duration ? ` · ${asset.duration.toFixed(1)}s` : ""}
+                  </div>
+                </div>
+              </div>
+            ))}
+          </div>
+        ) : (
+          <Empty description="素材库为空" />
+        )}
+      </Drawer>
+    </div>
+  );
+};
+
+export default PlanClipsManager;

apps/web/src/pages/edit-plans/plan-clips.css

@@ -0,0 +1,203 @@
+/* 剪辑计划片段管理页面 */
+
+.plan-clips-page {
+  padding: 24px;
+  min-height: 100vh;
+  background: #f5f7fa;
+}
+
+.plan-clips-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 20px;
+}
+
+.plan-clips-header-left {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.plan-clips-title h2 {
+  margin: 0;
+  font-size: 20px;
+  font-weight: 600;
+  color: #1f2937;
+}
+
+.plan-clips-title p {
+  margin: 4px 0 0;
+  font-size: 13px;
+  color: #6b7280;
+}
+
+.plan-clips-batch-bar {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 12px 20px;
+  margin-bottom: 16px;
+  background: #e6f4ff;
+  border-radius: 8px;
+  font-size: 14px;
+  color: #1677ff;
+}
+
+.plan-clips-table-wrap {
+  background: #fff;
+  border-radius: 12px;
+  padding: 16px;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04);
+}
+
+.clip-asset-id {
+  font-size: 12px;
+  color: #6b7280;
+  background: #f3f4f6;
+  padding: 2px 6px;
+  border-radius: 4px;
+}
+
+/* 排序模式 */
+.plan-clips-reorder-card {
+  margin-bottom: 16px;
+  border-radius: 12px;
+}
+
+.plan-clips-reorder-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.plan-clips-reorder-item {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 12px 16px;
+  background: #f9fafb;
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+  cursor: grab;
+  transition: all 0.2s;
+}
+
+.plan-clips-reorder-item:hover {
+  border-color: #1677ff;
+  background: #f0f7ff;
+}
+
+.reorder-index {
+  width: 28px;
+  height: 28px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #1677ff;
+  color: #fff;
+  border-radius: 50%;
+  font-size: 13px;
+  font-weight: 600;
+  flex-shrink: 0;
+}
+
+.reorder-type {
+  flex-shrink: 0;
+  font-size: 12px;
+  color: #6b7280;
+  padding: 2px 8px;
+  background: #eef2ff;
+  border-radius: 4px;
+}
+
+.reorder-content {
+  flex: 1;
+  font-size: 14px;
+  color: #1f2937;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.reorder-duration {
+  flex-shrink: 0;
+  font-size: 13px;
+  color: #6b7280;
+  font-variant-numeric: tabular-nums;
+}
+
+/* 素材导入 */
+.asset-import-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  max-height: calc(100vh - 200px);
+  overflow-y: auto;
+}
+
+.asset-import-item {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 12px;
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.asset-import-item:hover {
+  border-color: #1677ff;
+  background: #f0f7ff;
+}
+
+.asset-import-item.selected {
+  border-color: #1677ff;
+  background: #e6f4ff;
+}
+
+.asset-thumb {
+  width: 56px;
+  height: 40px;
+  border-radius: 4px;
+  overflow: hidden;
+  background: #f3f4f6;
+  flex-shrink: 0;
+}
+
+.asset-thumb img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.asset-thumb-placeholder {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 11px;
+  color: #9ca3af;
+  text-transform: uppercase;
+}
+
+.asset-info {
+  flex: 1;
+  min-width: 0;
+}
+
+.asset-name {
+  font-size: 14px;
+  color: #1f2937;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.asset-meta {
+  font-size: 12px;
+  color: #9ca3af;
+  margin-top: 2px;
+}

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

@@ -6048,3 +6048,275 @@
   color: #ef4444;
   background: #fef2f2;
 }
+
+/* ── 生成历史取消按钮 ── */
+.ep-gh-td-action {
+  width: 60px;
+  text-align: center;
+}
+.ep-gh-cancel-btn {
+  background: none;
+  border: none;
+  color: var(--color-error, #ff4d4f);
+  cursor: pointer;
+  font-size: 12px;
+  padding: 2px 8px;
+  border-radius: 4px;
+  transition: background 0.2s;
+}
+.ep-gh-cancel-btn:hover:not(:disabled) {
+  background: rgba(255, 77, 79, 0.1);
+}
+.ep-gh-cancel-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.ep-gh-action-placeholder {
+  color: var(--text-tertiary, #bfbfbf);
+}
+
+/* ═══ 生成进度 - 片段状态列表 ═══ */
+
+.ep-gen-clip-list {
+  margin-top: 16px;
+  max-height: 200px;
+  overflow-y: auto;
+  border: 1px solid var(--border-color, #e5e7eb);
+  border-radius: 8px;
+  padding: 4px 0;
+}
+
+.ep-gen-clip-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 6px 12px;
+  font-size: 13px;
+}
+
+.ep-gen-clip-item + .ep-gen-clip-item {
+  border-top: 1px solid var(--border-color-light, #f3f4f6);
+}
+
+.ep-gen-clip-index {
+  width: 22px;
+  height: 22px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--bg-secondary, #f3f4f6);
+  border-radius: 4px;
+  font-size: 11px;
+  color: var(--text-secondary, #6b7280);
+  flex-shrink: 0;
+}
+
+.ep-gen-clip-name {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--text-primary, #1f2937);
+}
+
+.ep-gen-clip-status {
+  flex-shrink: 0;
+  font-size: 12px;
+  font-weight: 500;
+}
+
+.ep-gen-clip-status.status-completed {
+  color: #10b981;
+}
+
+.ep-gen-clip-status.status-failed {
+  color: #ef4444;
+}
+
+.ep-gen-clip-status.status-processing {
+  color: #3b82f6;
+  animation: pulse 1.5s infinite;
+}
+
+.ep-gen-clip-status.status-pending,
+.ep-gen-clip-status.status-queued {
+  color: #9ca3af;
+}
+
+@keyframes pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.5; }
+}
+
+/* ═══ 右侧栏 Tab ═══ */
+.ep-right-panel {
+  width: 260px;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  border-left: 1px solid var(--border-color, #e5e7eb);
+  background: var(--bg-secondary, #f9fafb);
+}
+
+.ep-right-tabs {
+  display: flex;
+  height: 40px;
+  border-bottom: 1px solid var(--border-color, #e5e7eb);
+  background: var(--bg-primary, #fff);
+}
+
+.ep-right-tab {
+  flex: 1;
+  border: none;
+  background: transparent;
+  font-size: 13px;
+  color: var(--text-secondary, #6b7280);
+  cursor: pointer;
+  transition: all 0.2s;
+  border-bottom: 2px solid transparent;
+}
+
+.ep-right-tab:hover {
+  color: var(--text-primary, #111827);
+}
+
+.ep-right-tab.active {
+  color: var(--primary-color, #3b82f6);
+  border-bottom-color: var(--primary-color, #3b82f6);
+  font-weight: 500;
+}
+
+.ep-right-tab-content {
+  flex: 1;
+  overflow-y: auto;
+  min-height: 0;
+}
+
+/* ═══ 编辑器内片段列表 ═══ */
+.ep-clip-list {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+}
+
+.ep-clip-list-toolbar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--border-color, #e5e7eb);
+  background: var(--bg-primary, #fff);
+}
+
+.ep-clip-list-count {
+  font-size: 12px;
+  color: var(--text-secondary, #6b7280);
+}
+
+.ep-clip-list-count b {
+  color: var(--text-primary, #111827);
+  font-weight: 600;
+}
+
+.ep-clip-list-scroll {
+  flex: 1;
+  overflow-y: auto;
+  padding: 6px;
+}
+
+.ep-clip-list-item {
+  background: var(--bg-primary, #fff);
+  border: 1px solid var(--border-color, #e5e7eb);
+  border-radius: 6px;
+  padding: 8px 10px;
+  margin-bottom: 6px;
+  cursor: pointer;
+  transition: all 0.15s;
+}
+
+.ep-clip-list-item:hover {
+  border-color: var(--primary-color, #3b82f6);
+  box-shadow: 0 1px 3px rgba(59, 130, 246, 0.1);
+}
+
+.ep-clip-list-item.selected {
+  border-color: var(--primary-color, #3b82f6);
+  background: rgba(59, 130, 246, 0.04);
+}
+
+.ep-clip-item-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 4px;
+}
+
+.ep-clip-item-index {
+  width: 18px;
+  height: 18px;
+  line-height: 18px;
+  text-align: center;
+  font-size: 11px;
+  font-weight: 600;
+  background: var(--bg-tertiary, #f3f4f6);
+  color: var(--text-secondary, #6b7280);
+  border-radius: 3px;
+  flex-shrink: 0;
+}
+
+.ep-clip-item-type {
+  font-size: 11px;
+  color: var(--text-secondary, #6b7280);
+  display: flex;
+  align-items: center;
+  gap: 3px;
+  flex-shrink: 0;
+}
+
+.ep-clip-item-type-label {
+  font-size: 11px;
+}
+
+.ep-clip-item-duration {
+  margin-left: auto;
+  font-size: 11px;
+  font-weight: 500;
+  color: var(--text-primary, #111827);
+  flex-shrink: 0;
+}
+
+.ep-clip-item-text {
+  font-size: 12px;
+  color: var(--text-secondary, #6b7280);
+  line-height: 1.4;
+  margin-bottom: 6px;
+  overflow: hidden;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+}
+
+.ep-clip-item-actions {
+  display: flex;
+  gap: 2px;
+  justify-content: flex-end;
+  opacity: 0;
+  transition: opacity 0.15s;
+}
+
+.ep-clip-list-item:hover .ep-clip-item-actions,
+.ep-clip-list-item.selected .ep-clip-item-actions {
+  opacity: 1;
+}
+
+.ep-clip-item-btn {
+  width: 24px !important;
+  height: 24px !important;
+  padding: 0 !important;
+  font-size: 11px !important;
+}
+
+.ep-clip-list-empty {
+  padding: 16px;
+  text-align: center;
+}

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

@@ -37,6 +37,13 @@ import {
   generateEditPlan,
   getGenerationStatus,
   getGenerationTaskResults,
+  cancelGeneration,
+  getEditPlanClips,
+  createEditPlanClip,
+  batchDeleteEditPlanClips,
+  type EditPlanClip,
+  type CreateEditPlanClipRequest,
+  type ClipStatusItem,
 } from "@/api/editPlans";
 import { useUndoRedo } from "./hooks/useUndoRedo";
 import type {
@@ -79,10 +86,11 @@ import MediaPanel from "./components/MediaPanel";
 import PreviewPlayer from "./components/PreviewPlayer";
 import TimelinePanel from "./components/TimelinePanel";
 import ClipPropertiesPanel from "./components/ClipPropertiesPanel";
+import EditorClipList from "./components/EditorClipList";
 import BgmSelector from "./components/BgmSelector";
 import SubtitleStylePanel from "./components/SubtitleStylePanel";
-import type { SubtitleStyleConfig } from "./components/SubtitleStylePanel";
-import { DEFAULT_SUBTITLE_STYLE } from "./components/SubtitleStylePanel";
+import type { SubtitleStyleConfig } from "./types/subtitle";
+import { DEFAULT_SUBTITLE_STYLE } from "./types/subtitle";
 import TransitionSelector from "./components/TransitionSelector";
 import SpeedPanel from "./components/SpeedPanel";
 import TtsPanel from "./components/TtsPanel";
@@ -236,6 +244,10 @@ const EditingPlanner: React.FC = () => {
     ...DEFAULT_COVER_CONFIG,
   });
   const [coverDrawerOpen, setCoverDrawerOpen] = useState(false);
+  /* ── 右侧栏 Tab ── */
+  const [rightTab, setRightTab] = useState<"properties" | "clips">(
+    "properties",
+  );
 
   /* ── 保存弹窗 ── */
   const [saveModalOpen, setSaveModalOpen] = useState(false);
@@ -270,6 +282,9 @@ const EditingPlanner: React.FC = () => {
   const [generated, setGenerated] = useState(false);
   const [generatedVideos, setGeneratedVideos] = useState<GeneratedVideo[]>([]);
   const [genError, setGenError] = useState<string | null>(null);
+  const [cancelling, setCancelling] = useState(false);
+  const [genCancelled, setGenCancelled] = useState(false);
+  const [genClipStatuses, setGenClipStatuses] = useState<ClipStatusItem[]>([]);
   const genTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   /* ── 播放 ── */
@@ -408,8 +423,16 @@ const EditingPlanner: React.FC = () => {
    */
   useEffect(() => {
     if (!loadedPlanId) return;
-    getEditPlan(loadedPlanId)
-      .then((plan) => {
+
+    // 并行加载计划基本信息 + 片段列表
+    Promise.all([
+      getEditPlan(loadedPlanId),
+      getEditPlanClips(loadedPlanId, { limit: 500 }).catch(() => ({
+        items: [],
+        total: 0,
+      })),
+    ])
+      .then(([plan, clipsRes]) => {
         // 设置关联的模板（触发模板加载 effect）
         setLoadedTemplateId(plan.template_id);
 
@@ -448,9 +471,54 @@ const EditingPlanner: React.FC = () => {
             music_id: cfg.bgm_config!.music_id || "",
           }));
         }
+        // 还原封面配置
+        if (cfg.cover_config) {
+          setCoverSettings((prev) => ({
+            ...prev,
+            enabled: cfg.cover_config!.enabled ?? prev.enabled,
+            mode: (cfg.cover_config!.mode as CoverConfig["mode"]) || prev.mode,
+            frame_time: cfg.cover_config!.frame_time ?? prev.frame_time,
+            upload_url: cfg.cover_config!.upload_url || prev.upload_url,
+            thumbnail_url:
+              cfg.cover_config!.thumbnail_url || prev.thumbnail_url,
+            ai_suggested_time:
+              cfg.cover_config!.ai_suggested_time ?? prev.ai_suggested_time,
+          }));
+        }
 
-        // 还原片段 — 延迟设置，等模板加载 effect 先执行 resetClips
-        if (cfg.segments && cfg.segments.length > 0) {
+        // 还原片段：优先从后端 clips 表，其次从 config.segments 兜底
+        const backendClips = clipsRes?.items || [];
+        if (backendClips.length > 0) {
+          // 从后端 clips 表还原
+          const sorted = [...backendClips].sort((a, b) => a.order - b.order);
+          const mapped: ClipData[] = sorted.map((clip) => ({
+            id: clip.id,
+            template_segment_id:
+              (clip.config?.template_segment_id as string) || "",
+            type: (clip.clip_type === "voiceover"
+              ? "voice"
+              : "pip") as ClipType,
+            duration: clip.duration || 3,
+            startOffset: 0,
+            script_text: clip.text_content || "",
+            order: clip.order,
+            media_asset_id: clip.asset_id || undefined,
+            transition:
+              clip.transition_effect && clip.transition_effect !== "none"
+                ? {
+                    type: clip.transition_effect as TransitionEffect["type"],
+                    duration: clip.transition_duration || 0.3,
+                  }
+                : undefined,
+            speed: clip.playback_speed
+              ? { rate: clip.playback_speed, pitchCorrection: true }
+              : undefined,
+            tts_config: (clip.config?.tts_config as TtsConfig) || undefined,
+            trim_config: (clip.config?.trim_config as TrimConfig) || undefined,
+          }));
+          setTimeout(() => resetClips(mapped), 100);
+        } else if (cfg.segments && cfg.segments.length > 0) {
+          // 兜底：从 config.segments 还原（老数据兼容）
           const mapped: ClipData[] = cfg.segments.map((seg, idx) => ({
             id: `seg-${idx}`,
             template_segment_id: `seg-${idx}`,
@@ -554,15 +622,27 @@ const EditingPlanner: React.FC = () => {
   };
 
   const handleClipRemove = (clipId: string) => {
-    setClips((prev) => prev.filter((c) => c.id !== clipId));
-    if (selectedClipId === clipId) setSelectedClipId(null);
+    Modal.confirm({
+      title: "删除片段",
+      content: "确定要删除这个片段吗？此操作可通过撤销恢复。",
+      okText: "删除",
+      okType: "danger",
+      cancelText: "取消",
+      onOk: () => {
+        setClips((prev) => prev.filter((c) => c.id !== clipId));
+        if (selectedClipId === clipId) setSelectedClipId(null);
+      },
+    });
   };
 
-  const handleClipUpdate = (clipId: string, data: Partial<ClipData>) => {
-    setClips((prev) =>
-      prev.map((c) => (c.id === clipId ? { ...c, ...data } : c)),
-    );
-  };
+  const handleClipUpdate = useCallback(
+    (clipId: string, data: Partial<ClipData>) => {
+      setClips((prev) =>
+        prev.map((c) => (c.id === clipId ? { ...c, ...data } : c)),
+      );
+    },
+    [setClips],
+  );
 
   /**
    * 添加片段（不绑定任何素材）
@@ -670,7 +750,7 @@ const EditingPlanner: React.FC = () => {
       }
       // 同时更新全局默认转场（供新片段使用）
     },
-    [transitionTargetClipId],
+    [transitionTargetClipId, handleClipUpdate],
   );
 
   /* ── 打开转场选择器 ── */
@@ -686,7 +766,7 @@ const EditingPlanner: React.FC = () => {
         handleClipUpdate(speedTargetClipId, { speed: config });
       }
     },
-    [speedTargetClipId],
+    [speedTargetClipId, handleClipUpdate],
   );
 
   /* ── 打开调速面板 ── */
@@ -701,7 +781,7 @@ const EditingPlanner: React.FC = () => {
       if (!ttsTargetClipId) return;
       handleClipUpdate(ttsTargetClipId, { tts_config: ttsConfig });
     },
-    [ttsTargetClipId],
+    [ttsTargetClipId, handleClipUpdate],
   );
 
   /* ── 打开 TTS 配音面板 ── */
@@ -711,10 +791,13 @@ const EditingPlanner: React.FC = () => {
   }, []);
 
   /* ── 调速应用到所有片段 ── */
-  const handleApplySpeedAll = useCallback((config: SpeedConfig) => {
-    setClips((prev) => prev.map((c) => ({ ...c, speed: { ...config } })));
-    message.success("已应用到所有片段");
-  }, []);
+  const handleApplySpeedAll = useCallback(
+    (config: SpeedConfig) => {
+      setClips((prev) => prev.map((c) => ({ ...c, speed: { ...config } })));
+      message.success("已应用到所有片段");
+    },
+    [setClips],
+  );
 
   /* ── 水印配置变更 ── */
   const handleWatermarkChange = useCallback((config: WatermarkConfig) => {
@@ -928,10 +1011,58 @@ const EditingPlanner: React.FC = () => {
     }
   };
 
+  /**
+   * 将本地编辑的片段同步到后端 clips 表
+   * 策略：先删除后端所有片段，再批量创建（简单可靠，生成前使用）
+   */
+  const syncClipsToBackend = async (planId: string): Promise<void> => {
+    if (clips.length === 0) return;
+
+    // 1. 获取并删除后端现有片段
+    const existing = await getEditPlanClips(planId, { limit: 500 });
+    if (existing.items.length > 0) {
+      await batchDeleteEditPlanClips(
+        planId,
+        existing.items.map((c) => c.id),
+      );
+    }
+
+    // 2. 批量创建新片段（并发 3 个）
+    const clipDataList: CreateEditPlanClipRequest[] = clips.map((c, i) => ({
+      clip_type: c.type === "voice" ? "voiceover" : "main",
+      order: i,
+      asset_id: c.media_asset_id || "",
+      text_content: c.script_text || "",
+      start_time: 0,
+      duration: c.duration,
+      transition_effect: c.transition?.type || "cut",
+      transition_duration: c.transition?.duration || 0,
+      playback_speed: c.speed?.rate || 1.0,
+      config: {
+        tts_config: c.tts_config || null,
+        trim_config: c.trim_config || null,
+        template_segment_id: c.template_segment_id || null,
+      },
+    }));
+
+    // 并发控制：最多同时 3 个请求
+    const results: EditPlanClip[] = [];
+    const concurrency = 3;
+    for (let i = 0; i < clipDataList.length; i += concurrency) {
+      const batch = clipDataList.slice(i, i + concurrency);
+      const batchResults = await Promise.all(
+        batch.map((data) => createEditPlanClip(planId, data)),
+      );
+      results.push(...batchResults);
+    }
+
+    console.log(`[片段同步] 创建了 ${results.length} 个片段`);
+  };
+
   /**
    * 剪辑计划生成
-   * 1. 有 planId → 更新计划配置 + 触发生成
-   * 2. 无 planId（从模板库直接进入）→ 先创建计划 + 触发生成
+   * 1. 有 planId → 更新计划配置 + 同步片段 + 触发生成
+   * 2. 无 planId（从模板库直接进入）→ 先创建计划 + 同步片段 + 触发生成
    * 3. 触发生成后轮询状态，完成后获取视频结果
    */
   const handleGoToGenerate = async () => {
@@ -949,6 +1080,7 @@ const EditingPlanner: React.FC = () => {
     setGeneratedVideos([]);
     setGenError(null);
     setGenProgress(0);
+    setGenCancelled(false);
 
     try {
       const config = buildPlanConfig();
@@ -986,6 +1118,15 @@ const EditingPlanner: React.FC = () => {
         window.history.replaceState(null, "", `?${params.toString()}`);
       }
 
+      // 同步片段到后端 clips 表（生成前必须同步，后端生成从 clips 表读）
+      try {
+        await syncClipsToBackend(planId);
+      } catch (syncErr) {
+        console.warn("[片段同步失败]", syncErr);
+        message.warning("片段同步失败，将使用模板默认配置生成");
+        // 同步失败不阻塞生成，后端有模板兜底
+      }
+
       // 触发生成
       const genRes = await generateEditPlan(planId);
       setGenTotalClips(genRes.clip_count);
@@ -1013,6 +1154,7 @@ const EditingPlanner: React.FC = () => {
         ).length;
         setGenDoneClips(done);
         setGenTotalClips(total);
+        setGenClipStatuses(status.clips || []);
         setGenProgress(total > 0 ? Math.round((done / total) * 100) : 5);
 
         if (status.plan_status === "completed") {
@@ -1041,6 +1183,14 @@ const EditingPlanner: React.FC = () => {
           return; // 停止轮询
         }
 
+        if (status.plan_status === "cancelled") {
+          setGenerating(false);
+          setGenError("生成已取消");
+          setGenCancelled(true);
+          message.info("生成任务已取消");
+          return; // 停止轮询
+        }
+
         // 继续轮询
         genTimerRef.current = setTimeout(poll, 2000);
       } catch (err) {
@@ -1060,6 +1210,33 @@ const EditingPlanner: React.FC = () => {
     };
   }, []);
 
+  /** 取消生成任务 */
+  const handleCancelGeneration = async () => {
+    const targetId = loadedPlanId;
+    if (!targetId) return;
+
+    Modal.confirm({
+      title: "确认取消生成",
+      content: "取消后已开始的生成任务，已生成的片段不会保留。确定要取消吗？",
+      okText: "确认取消",
+      cancelText: "继续生成",
+      okButtonProps: { danger: true },
+      onOk: async () => {
+        try {
+          setCancelling(true);
+          await cancelGeneration(targetId);
+          message.success("已提交取消请求");
+          // 轮询会继续运行直到检测到 cancelled 状态
+        } catch (err) {
+          console.error("[取消失败]", err);
+          message.error("取消失败，请稍后重试");
+        } finally {
+          setCancelling(false);
+        }
+      },
+    });
+  };
+
   /* 查看生成历史 */
   const handleViewGenHistory = async () => {
     const targetId = loadedPlanId || loadedTemplateId;
@@ -1204,43 +1381,87 @@ const EditingPlanner: React.FC = () => {
         </div>
 
         {/* 右栏 260px：设置面板 */}
-        <ClipPropertiesPanel
-          selectedClip={selectedClip}
-          titleSettings={titleSettings}
-          subtitleSettings={subtitleSettings}
-          bgmSettings={bgmSettings}
-          clipsCount={clips.length}
-          totalDuration={totalDuration}
-          currentMode={currentMode}
-          onTitleSettingsChange={(partial) =>
-            setTitleSettings((prev) => ({ ...prev, ...partial }))
-          }
-          onSubtitleSettingsChange={(partial) =>
-            setSubtitleSettings(
-              (prev) => ({ ...prev, ...partial }) as SubtitleStyleConfig,
-            )
-          }
-          onBgmSettingsChange={(partial) =>
-            setBgmSettings((prev) => ({ ...prev, ...partial }))
-          }
-          onClipUpdate={handleClipUpdate}
-          onOpenBgmDrawer={() => setBgmDrawerOpen(true)}
-          onOpenSubtitleDrawer={() => setSubtitleDrawerOpen(true)}
-          voiceMaterials={voiceMaterials}
-          voiceMaterialsLoading={voiceMaterialsQuery.isLoading}
-          onRefreshVoiceMaterials={() => voiceMaterialsQuery.refetch()}
-          onClipVoiceSelect={handleClipVoiceSelect}
-          onOpenTransitionDrawer={handleOpenTransitionDrawer}
-          onOpenSpeedDrawer={handleOpenSpeedDrawer}
-          onOpenTtsDrawer={handleOpenTtsDrawer}
-          onOpenWatermarkDrawer={() => setWatermarkDrawerOpen(true)}
-          onOpenIntroOutroDrawer={() => setIntroOutroDrawerOpen(true)}
-          onOpenPipDrawer={() => setPipDrawerOpen(true)}
-          onOpenFilterDrawer={() => setFilterDrawerOpen(true)}
-          onOpenGreenScreenDrawer={() => setChromaKeyDrawerOpen(true)}
-          onOpenStickerDrawer={() => setStickerDrawerOpen(true)}
-          onOpenCoverDrawer={() => setCoverDrawerOpen(true)}
-        />
+        <div className="ep-right-panel">
+          {/* Tab 切换 */}
+          <div className="ep-right-tabs">
+            <button
+              className={`ep-right-tab${rightTab === "properties" ? " active" : ""}`}
+              onClick={() => setRightTab("properties")}
+            >
+              属性
+            </button>
+            <button
+              className={`ep-right-tab${rightTab === "clips" ? " active" : ""}`}
+              onClick={() => setRightTab("clips")}
+            >
+              片段
+            </button>
+          </div>
+
+          {/* 属性 Tab */}
+          {rightTab === "properties" && (
+            <div className="ep-right-tab-content">
+              <ClipPropertiesPanel
+                selectedClip={selectedClip}
+                titleSettings={titleSettings}
+                subtitleSettings={subtitleSettings}
+                bgmSettings={bgmSettings}
+                clipsCount={clips.length}
+                totalDuration={totalDuration}
+                currentMode={currentMode}
+                onTitleSettingsChange={(partial) =>
+                  setTitleSettings((prev) => ({ ...prev, ...partial }))
+                }
+                onSubtitleSettingsChange={(partial) =>
+                  setSubtitleSettings(
+                    (prev) => ({ ...prev, ...partial }) as SubtitleStyleConfig,
+                  )
+                }
+                onBgmSettingsChange={(partial) =>
+                  setBgmSettings((prev) => ({ ...prev, ...partial }))
+                }
+                onClipUpdate={handleClipUpdate}
+                onOpenBgmDrawer={() => setBgmDrawerOpen(true)}
+                onOpenSubtitleDrawer={() => setSubtitleDrawerOpen(true)}
+                voiceMaterials={voiceMaterials}
+                voiceMaterialsLoading={voiceMaterialsQuery.isLoading}
+                onRefreshVoiceMaterials={() => voiceMaterialsQuery.refetch()}
+                onClipVoiceSelect={handleClipVoiceSelect}
+                onOpenTransitionDrawer={handleOpenTransitionDrawer}
+                onOpenSpeedDrawer={handleOpenSpeedDrawer}
+                onOpenTtsDrawer={handleOpenTtsDrawer}
+                onOpenWatermarkDrawer={() => setWatermarkDrawerOpen(true)}
+                onOpenIntroOutroDrawer={() => setIntroOutroDrawerOpen(true)}
+                onOpenPipDrawer={() => setPipDrawerOpen(true)}
+                onOpenFilterDrawer={() => setFilterDrawerOpen(true)}
+                onOpenGreenScreenDrawer={() => setChromaKeyDrawerOpen(true)}
+                onOpenStickerDrawer={() => setStickerDrawerOpen(true)}
+                onOpenCoverDrawer={() => setCoverDrawerOpen(true)}
+              />
+            </div>
+          )}
+
+          {/* 片段 Tab */}
+          {rightTab === "clips" && (
+            <div className="ep-right-tab-content">
+              <EditorClipList
+                clips={clips}
+                selectedClipId={selectedClipId}
+                onSelect={handleClipSelect}
+                onMoveUp={(clipId) => {
+                  const idx = clips.findIndex((c) => c.id === clipId);
+                  if (idx > 0) handleClipReorder(idx, idx - 1);
+                }}
+                onMoveDown={(clipId) => {
+                  const idx = clips.findIndex((c) => c.id === clipId);
+                  if (idx < clips.length - 1) handleClipReorder(idx, idx + 1);
+                }}
+                onRemove={handleClipRemove}
+                onAdd={() => handleAddClip("pip", 3)}
+              />
+            </div>
+          )}
+        </div>
       </div>
 
       {/* ═══ 第4行：底栏 40px ═══ */}
@@ -1284,12 +1505,42 @@ const EditingPlanner: React.FC = () => {
         loading={genHistoryLoading}
         history={genHistory}
         onClose={() => setGenHistoryOpen(false)}
+        onCancel={async () => {
+          Modal.confirm({
+            title: "确认取消生成",
+            content: "确定要取消这个生成任务吗？此操作不可恢复。",
+            okText: "确认取消",
+            cancelText: "再等等",
+            okButtonProps: { danger: true },
+            onOk: async () => {
+              if (!loadedPlanId) return;
+              try {
+                await cancelGeneration(loadedPlanId);
+                message.success("已提交取消请求");
+                // 刷新历史列表
+                handleViewGenHistory();
+              } catch (err) {
+                console.error("[取消失败]", err);
+                message.error("取消失败，请稍后重试");
+              }
+            },
+          });
+        }}
+        cancelLoading={cancelling}
       />
 
       {/* ═══ 生成进度弹窗 ═══ */}
       <Modal
-        title={genError ? "生成失败" : generated ? "生成完成" : "正在生成视频"}
-        open={generating || generated || !!genError}
+        title={
+          genError
+            ? "生成失败"
+            : genCancelled
+              ? "已取消生成"
+              : generated
+                ? "生成完成"
+                : "正在生成视频"
+        }
+        open={generating || generated || !!genError || genCancelled}
         footer={
           generated
             ? [
@@ -1298,6 +1549,7 @@ const EditingPlanner: React.FC = () => {
                   onClick={() => {
                     setGenerated(false);
                     setGenerating(false);
+                    setGenError(null);
                   }}
                 >
                   关闭
@@ -1324,7 +1576,43 @@ const EditingPlanner: React.FC = () => {
                   </Button>
                 ),
               ]
-            : null
+            : generating
+              ? [
+                  <Button
+                    key="cancel"
+                    danger
+                    loading={cancelling}
+                    onClick={handleCancelGeneration}
+                  >
+                    取消生成
+                  </Button>,
+                ]
+              : genCancelled
+                ? [
+                    <Button
+                      key="close"
+                      type="primary"
+                      onClick={() => {
+                        setGenCancelled(false);
+                        setGenerating(false);
+                      }}
+                    >
+                      关闭
+                    </Button>,
+                  ]
+                : genError
+                  ? [
+                      <Button
+                        key="close"
+                        onClick={() => {
+                          setGenError(null);
+                          setGenerating(false);
+                        }}
+                      >
+                        关闭
+                      </Button>,
+                    ]
+                  : null
         }
         closable={!generating}
         maskClosable={false}
@@ -1336,11 +1624,50 @@ const EditingPlanner: React.FC = () => {
             <p style={{ marginTop: 8, color: "var(--text-secondary)" }}>
               已处理 {genDoneClips}/{genTotalClips} 个片段
             </p>
-            <p style={{ color: "var(--text-secondary)", fontSize: 12 }}>
+            {genClipStatuses.length > 0 && (
+              <div className="ep-gen-clip-list">
+                {genClipStatuses.map((clip, index) => (
+                  <div key={clip.clip_id || index} className="ep-gen-clip-item">
+                    <span className="ep-gen-clip-index">{index + 1}</span>
+                    <span className="ep-gen-clip-name">
+                      {clip.text_content
+                        ? clip.text_content.slice(0, 20)
+                        : clip.clip_type || `片段${index + 1}`}
+                    </span>
+                    <span
+                      className={`ep-gen-clip-status status-${clip.status}`}
+                    >
+                      {clip.status === "completed"
+                        ? "✓ 完成"
+                        : clip.status === "failed"
+                          ? "✗ 失败"
+                          : clip.status === "processing"
+                            ? "⟳ 处理中"
+                            : "⏳ 等待中"}
+                    </span>
+                  </div>
+                ))}
+              </div>
+            )}
+            <p
+              style={{
+                color: "var(--text-secondary)",
+                fontSize: 12,
+                marginTop: 12,
+              }}
+            >
               请耐心等待，生成过程中请勿关闭页面
             </p>
           </div>
         )}
+        {genCancelled && (
+          <div style={{ padding: "24px 0", textAlign: "center" }}>
+            <p>生成已取消</p>
+            <p style={{ color: "var(--text-secondary)", fontSize: 12 }}>
+              你可以继续编辑后重新生成
+            </p>
+          </div>
+        )}
         {generated && generatedVideos.length > 0 && (
           <div style={{ padding: "8px 0" }}>
             <video

apps/web/src/pages/editing-planner/components/EditorClipList.tsx

@@ -0,0 +1,168 @@
+/**
+ * 编辑器右侧栏 — 片段列表 Tab
+ * 紧凑版片段管理：选中、上下移动、删除、添加
+ */
+import React from "react";
+import { Button, Tooltip, Empty } from "antd";
+import {
+  UpOutlined,
+  DownOutlined,
+  DeleteOutlined,
+  PlusOutlined,
+  ScissorOutlined,
+  SoundOutlined,
+  PictureOutlined,
+  VideoCameraOutlined,
+} from "@ant-design/icons";
+import type { ClipData, ClipType } from "../types";
+
+interface EditorClipListProps {
+  clips: ClipData[];
+  selectedClipId: string | null;
+  onSelect: (clipId: string) => void;
+  onMoveUp: (clipId: string) => void;
+  onMoveDown: (clipId: string) => void;
+  onRemove: (clipId: string) => void;
+  onAdd: () => void;
+}
+
+const clipTypeIcon: Record<ClipType | string, React.ReactNode> = {
+  video: <VideoCameraOutlined />,
+  image: <PictureOutlined />,
+  voice: <SoundOutlined />,
+  pip: <ScissorOutlined />,
+};
+
+const clipTypeLabel: Record<ClipType | string, string> = {
+  video: "视频",
+  image: "图片",
+  voice: "配音",
+  pip: "画中画",
+};
+
+const formatDuration = (sec: number) => {
+  if (sec < 60) return `${sec.toFixed(1)}s`;
+  const m = Math.floor(sec / 60);
+  const s = (sec % 60).toFixed(0);
+  return `${m}m${s.padStart(2, "0")}s`;
+};
+
+const EditorClipList: React.FC<EditorClipListProps> = ({
+  clips,
+  selectedClipId,
+  onSelect,
+  onMoveUp,
+  onMoveDown,
+  onRemove,
+  onAdd,
+}) => {
+  if (clips.length === 0) {
+    return (
+      <div className="ep-clip-list-empty">
+        <Empty
+          description="暂无片段"
+          image={Empty.PRESENTED_IMAGE_SIMPLE}
+          style={{ margin: "40px 0" }}
+        />
+        <Button type="primary" icon={<PlusOutlined />} block onClick={onAdd}>
+          添加片段
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="ep-clip-list">
+      {/* 顶部工具栏 */}
+      <div className="ep-clip-list-toolbar">
+        <span className="ep-clip-list-count">
+          共 <b>{clips.length}</b> 个片段
+        </span>
+        <Tooltip title="添加片段">
+          <Button
+            type="primary"
+            size="small"
+            icon={<PlusOutlined />}
+            onClick={onAdd}
+          >
+            添加
+          </Button>
+        </Tooltip>
+      </div>
+
+      {/* 片段列表 */}
+      <div className="ep-clip-list-scroll">
+        {clips.map((clip, index) => (
+          <div
+            key={clip.id}
+            className={`ep-clip-list-item${
+              selectedClipId === clip.id ? " selected" : ""
+            }`}
+            onClick={() => onSelect(clip.id)}
+          >
+            {/* 序号 + 类型图标 */}
+            <div className="ep-clip-item-head">
+              <span className="ep-clip-item-index">{index + 1}</span>
+              <span className="ep-clip-item-type">
+                {clipTypeIcon[clip.type] || <ScissorOutlined />}
+                <span className="ep-clip-item-type-label">
+                  {clipTypeLabel[clip.type] || "片段"}
+                </span>
+              </span>
+              <span className="ep-clip-item-duration">
+                {formatDuration(clip.duration)}
+              </span>
+            </div>
+
+            {/* 文案预览 */}
+            {clip.script_text && (
+              <div className="ep-clip-item-text">
+                {clip.script_text.slice(0, 40)}
+                {clip.script_text.length > 40 ? "..." : ""}
+              </div>
+            )}
+
+            {/* 操作按钮 */}
+            <div
+              className="ep-clip-item-actions"
+              onClick={(e) => e.stopPropagation()}
+            >
+              <Tooltip title="上移">
+                <Button
+                  type="text"
+                  size="small"
+                  icon={<UpOutlined />}
+                  disabled={index === 0}
+                  onClick={() => onMoveUp(clip.id)}
+                  className="ep-clip-item-btn"
+                />
+              </Tooltip>
+              <Tooltip title="下移">
+                <Button
+                  type="text"
+                  size="small"
+                  icon={<DownOutlined />}
+                  disabled={index === clips.length - 1}
+                  onClick={() => onMoveDown(clip.id)}
+                  className="ep-clip-item-btn"
+                />
+              </Tooltip>
+              <Tooltip title="删除">
+                <Button
+                  type="text"
+                  size="small"
+                  danger
+                  icon={<DeleteOutlined />}
+                  onClick={() => onRemove(clip.id)}
+                  className="ep-clip-item-btn"
+                />
+              </Tooltip>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+export default EditorClipList;

apps/web/src/pages/editing-planner/components/GenerationHistoryModal.tsx

@@ -12,6 +12,8 @@ interface GenerationHistoryModalProps {
   loading: boolean;
   history: EditPlanGeneration[];
   onClose: () => void;
+  onCancel?: (taskId: string) => void;
+  cancelLoading?: boolean;
 }
 
 const GenerationHistoryModal: React.FC<GenerationHistoryModalProps> = ({
@@ -19,6 +21,8 @@ const GenerationHistoryModal: React.FC<GenerationHistoryModalProps> = ({
   loading,
   history,
   onClose,
+  onCancel,
+  cancelLoading,
 }) => {
   if (!open) return null;
 
@@ -57,11 +61,14 @@ const GenerationHistoryModal: React.FC<GenerationHistoryModalProps> = ({
                   <th className="ep-gh-th">状态</th>
                   <th className="ep-gh-th">创建时间</th>
                   <th className="ep-gh-th">更新时间</th>
+                  {onCancel && <th className="ep-gh-th">操作</th>}
                 </tr>
               </thead>
               <tbody>
                 {history.map((gen) => {
                   const statusClass = `ep-gh-status-tag--${gen.status}`;
+                  const canCancel =
+                    gen.status === "rendering" || gen.status === "editing";
                   return (
                     <tr key={gen.id} className="ep-gh-table-row">
                       <td className="ep-gh-td ep-gh-td-id">
@@ -82,6 +89,21 @@ const GenerationHistoryModal: React.FC<GenerationHistoryModalProps> = ({
                           ? new Date(gen.updated_at).toLocaleString("zh-CN")
                           : "—"}
                       </td>
+                      {onCancel && (
+                        <td className="ep-gh-td ep-gh-td-action">
+                          {canCancel ? (
+                            <button
+                              className="ep-gh-cancel-btn"
+                              onClick={() => onCancel(gen.id)}
+                              disabled={cancelLoading}
+                            >
+                              取消
+                            </button>
+                          ) : (
+                            <span className="ep-gh-action-placeholder">—</span>
+                          )}
+                        </td>
+                      )}
                     </tr>
                   );
                 })}

apps/web/src/pages/editing-planner/components/SubtitleStylePanel.tsx

@@ -5,46 +5,7 @@
 import React from "react";
 import { Drawer, Slider, ColorPicker, Select } from "antd";
 import type { Color } from "antd/es/color-picker";
-
-/* ──────────── 类型 ──────────── */
-
-export type SubtitleMode = "manual" | "asr";
-
-export interface SubtitleStyleConfig {
-  /** 是否启用字幕 */
-  enabled: boolean;
-  /** 字幕模式：手动输入 / ASR 自动识别 */
-  mode: SubtitleMode;
-  /** 字体大小 px */
-  fontSize: number;
-  /** 字体颜色 */
-  fontColor: string;
-  /** 描边 */
-  stroke: boolean;
-  /** 阴影 */
-  shadow: boolean;
-  /** 字幕位置 */
-  position: "top" | "center" | "bottom";
-  /** 字体 */
-  font: string;
-  /** 动画效果 */
-  animation: string;
-  /** ASR 语言（仅 ASR 模式） */
-  asrLanguage: "zh" | "en";
-}
-
-export const DEFAULT_SUBTITLE_STYLE: SubtitleStyleConfig = {
-  enabled: true,
-  mode: "asr",
-  fontSize: 16,
-  fontColor: "#ffffff",
-  stroke: true,
-  shadow: false,
-  position: "bottom",
-  font: "思源黑体",
-  animation: "none",
-  asrLanguage: "zh",
-};
+import type { SubtitleStyleConfig } from "../types/subtitle";
 
 /* ──────────── 选项常量 ──────────── */
 

apps/web/src/pages/editing-planner/hooks/useEditPlanClips.ts

@@ -0,0 +1,242 @@
+/**
+ * 剪辑计划片段管理 Hook
+ * 对接后端 PR#389 片段 CRUD API，替代原来的 config.segments 模式
+ *
+ * 功能：
+ * - 加载/刷新片段列表
+ * - 单个增删改查
+ * - 批量删除
+ * - 拖拽重排序
+ * - 从素材批量导入
+ * - 乐观更新 + 撤销重做
+ */
+import { useCallback, useState } from "react";
+import { message } from "antd";
+import { useQuery, useQueryClient, useMutation } from "@tanstack/react-query";
+import type {
+  EditPlanClip,
+  CreateEditPlanClipRequest,
+  UpdateEditPlanClipRequest,
+  ClipReorderItem,
+} from "@/api/editPlans";
+import {
+  getEditPlanClips,
+  createEditPlanClip,
+  updateEditPlanClip,
+  deleteEditPlanClip,
+  reorderEditPlanClips,
+  batchDeleteEditPlanClips,
+  createClipsFromAssets,
+} from "@/api/editPlans";
+import { useUndoRedo } from "./useUndoRedo";
+
+const QUERY_KEY = "editPlanClips";
+
+export function useEditPlanClips(planId: string | undefined) {
+  const queryClient = useQueryClient();
+
+  /* ── 片段列表查询 ── */
+  const {
+    data: clipListData,
+    isLoading: clipsLoading,
+    refetch: refetchClips,
+  } = useQuery({
+    queryKey: [QUERY_KEY, planId],
+    queryFn: () => getEditPlanClips(planId!, { limit: 500 }),
+    enabled: !!planId,
+    staleTime: 30_000,
+  });
+
+  const clips: EditPlanClip[] = clipListData?.items ?? [];
+  const clipsTotal = clipListData?.total ?? 0;
+
+  /* ── 选中片段 ── */
+  const [selectedClipId, setSelectedClipId] = useState<string | null>(null);
+  const selectedClip = clips.find((c) => c.id === selectedClipId) ?? null;
+
+  /* ── 本地撤销/重做（用于拖拽等即时操作的回退） ── */
+  const {
+    state: localClips,
+    set: setLocalClips,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    reset: resetLocalClips,
+  } = useUndoRedo<EditPlanClip[]>([]);
+
+  // 当服务端数据变化时同步本地
+  // 注意：实际使用时以服务端为准，本地仅用于拖拽等临时操作
+
+  /* ── 创建片段 ── */
+  const createMutation = useMutation({
+    mutationFn: (data: CreateEditPlanClipRequest) =>
+      createEditPlanClip(planId!, data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] });
+      message.success("片段已添加");
+    },
+    onError: () => {
+      message.error("添加片段失败");
+    },
+  });
+
+  const addClip = useCallback(
+    (data: Omit<CreateEditPlanClipRequest, "order"> & { order?: number }) => {
+      if (!planId) return;
+      const order = data.order ?? clips.length;
+      createMutation.mutate({ ...data, order });
+    },
+    [planId, clips.length, createMutation],
+  );
+
+  /* ── 更新片段 ── */
+  const updateMutation = useMutation({
+    mutationFn: ({
+      clipId,
+      data,
+    }: {
+      clipId: string;
+      data: UpdateEditPlanClipRequest;
+    }) => updateEditPlanClip(planId!, clipId, data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] });
+    },
+    onError: () => {
+      message.error("更新片段失败");
+    },
+  });
+
+  const updateClip = useCallback(
+    (clipId: string, data: UpdateEditPlanClipRequest) => {
+      if (!planId) return;
+      updateMutation.mutate({ clipId, data });
+    },
+    [planId, updateMutation],
+  );
+
+  /* ── 删除片段 ── */
+  const deleteMutation = useMutation({
+    mutationFn: (clipId: string) => deleteEditPlanClip(planId!, clipId),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] });
+      message.success("片段已删除");
+    },
+    onError: () => {
+      message.error("删除片段失败");
+    },
+  });
+
+  const removeClip = useCallback(
+    (clipId: string) => {
+      if (!planId) return;
+      if (selectedClipId === clipId) {
+        setSelectedClipId(null);
+      }
+      deleteMutation.mutate(clipId);
+    },
+    [planId, selectedClipId, deleteMutation],
+  );
+
+  /* ── 批量删除 ── */
+  const batchDeleteMutation = useMutation({
+    mutationFn: (clipIds: string[]) =>
+      batchDeleteEditPlanClips(planId!, clipIds),
+    onSuccess: (res) => {
+      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] });
+      message.success(`已删除 ${res.deleted_count} 个片段`);
+    },
+    onError: () => {
+      message.error("批量删除失败");
+    },
+  });
+
+  const batchRemoveClips = useCallback(
+    (clipIds: string[]) => {
+      if (!planId || clipIds.length === 0) return;
+      if (selectedClipId && clipIds.includes(selectedClipId)) {
+        setSelectedClipId(null);
+      }
+      batchDeleteMutation.mutate(clipIds);
+    },
+    [planId, selectedClipId, batchDeleteMutation],
+  );
+
+  /* ── 重排序（拖拽结束后一次性提交） ── */
+  const reorderMutation = useMutation({
+    mutationFn: (items: ClipReorderItem[]) =>
+      reorderEditPlanClips(planId!, items),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] });
+    },
+    onError: () => {
+      message.error("排序失败");
+      // 失败后刷新回服务端状态
+      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] });
+    },
+  });
+
+  const reorderClips = useCallback(
+    (items: ClipReorderItem[]) => {
+      if (!planId || items.length === 0) return;
+      reorderMutation.mutate(items);
+    },
+    [planId, reorderMutation],
+  );
+
+  /* ── 从素材批量导入 ── */
+  const importFromAssetsMutation = useMutation({
+    mutationFn: (assetIds: string[]) =>
+      createClipsFromAssets(planId!, assetIds),
+    onSuccess: (res) => {
+      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] });
+      message.success(`已导入 ${res.created_count} 个素材片段`);
+    },
+    onError: () => {
+      message.error("导入素材失败");
+    },
+  });
+
+  const importFromAssets = useCallback(
+    (assetIds: string[]) => {
+      if (!planId || assetIds.length === 0) return;
+      importFromAssetsMutation.mutate(assetIds);
+    },
+    [planId, importFromAssetsMutation],
+  );
+
+  return {
+    // 数据
+    clips,
+    clipsTotal,
+    clipsLoading,
+    selectedClipId,
+    selectedClip,
+    // 选中
+    setSelectedClipId,
+    // 操作
+    addClip,
+    updateClip,
+    removeClip,
+    batchRemoveClips,
+    reorderClips,
+    importFromAssets,
+    refetchClips,
+    // 状态
+    isCreating: createMutation.isPending,
+    isUpdating: updateMutation.isPending,
+    isDeleting: deleteMutation.isPending,
+    isReordering: reorderMutation.isPending,
+    isImporting: importFromAssetsMutation.isPending,
+    // 本地撤销重做（供拖拽等场景使用）
+    localClips,
+    setLocalClips,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    resetLocalClips,
+  };
+}
+
+export default useEditPlanClips;

apps/web/src/pages/editing-planner/types.ts

@@ -512,6 +512,8 @@ export interface ClipData {
   type: ClipType; // 片段类型：voice（口播）或 pip（画中画）
   duration: number; // 时长（秒）
   startOffset: number; // 仅 voice 类型：在口播素材中的起始时间（秒）
+  /** 素材库素材 ID（main/pip 类型片段使用） */
+  media_asset_id?: string;
   // 保留兼容字段（后端序列化需要）
   template_segment_id?: string;
   script_text?: string;

apps/web/src/pages/editing-planner/types/subtitle.ts

@@ -0,0 +1,46 @@
+/**
+ * 字幕样式相关类型与常量
+ * 单独抽离以满足 react-refresh/only-export-components 规则
+ */
+
+/* ──────────── 类型 ──────────── */
+
+export type SubtitleMode = "manual" | "asr";
+
+export interface SubtitleStyleConfig {
+  /** 是否启用字幕 */
+  enabled: boolean;
+  /** 字幕模式：手动输入 / ASR 自动识别 */
+  mode: SubtitleMode;
+  /** 字体大小 px */
+  fontSize: number;
+  /** 字体颜色 */
+  fontColor: string;
+  /** 描边 */
+  stroke: boolean;
+  /** 阴影 */
+  shadow: boolean;
+  /** 字幕位置 */
+  position: "top" | "center" | "bottom";
+  /** 字体 */
+  font: string;
+  /** 动画效果 */
+  animation: string;
+  /** ASR 语言（仅 ASR 模式） */
+  asrLanguage: "zh" | "en";
+}
+
+/* ──────────── 默认值 ──────────── */
+
+export const DEFAULT_SUBTITLE_STYLE: SubtitleStyleConfig = {
+  enabled: true,
+  mode: "asr",
+  fontSize: 16,
+  fontColor: "#ffffff",
+  stroke: true,
+  shadow: false,
+  position: "bottom",
+  font: "思源黑体",
+  animation: "none",
+  asrLanguage: "zh",
+};

apps/web/src/router/index.tsx

@@ -163,6 +163,13 @@ export const router = createBrowserRouter([
             Component: m.default,
           })),
       },
+      {
+        path: "edit-plans/:planId/clips",
+        lazy: () =>
+          import("@/pages/edit-plans/PlanClipsManager").then((m) => ({
+            Component: m.default,
+          })),
+      },
       {
         path: "voice-clone",
         lazy: () =>

apps/worker/video_processing/bgm_mixer.py

@@ -88,14 +88,12 @@ def prepare_bgm_track(
 
     # 构建滤镜链
     filter_parts: list[str] = []
-    input_looped: bool = False
 
     if needs_loop:
         # 计算需要循环多少次才能铺满
         loop_count = max(1, int(target_duration / bgm_dur) + 2)
         # aloop 滤镜：循环指定次数
         filter_parts.append(f"aloop=loop={loop_count}:size=0")
-        input_looped = True
 
     # 音量调节
     volume = max(0.0, min(1.0, bgm.volume))

apps/worker/video_processing/color_grade_engine.py

@@ -10,7 +10,7 @@
 from __future__ import annotations
 
 import logging
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import Any
 
 logger = logging.getLogger(__name__)

apps/worker/video_processing/concat_engine.py

@@ -18,10 +18,8 @@
 from __future__ import annotations
 
 import logging
-import tempfile
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
 
 from video_processing.ffmpeg_utils import FFMPEG_BIN, probe_duration, probe_video_info, run_ffmpeg
 from video_processing.path_security import PathSecurityError, is_in_allowed_dirs, safe_resolve_path

apps/worker/video_processing/intro_outro_engine.py

@@ -160,7 +160,6 @@ class IntroOutroEngine:
             是否成功
         """
         duration = config.intro_duration
-        bg = config.intro_background.lstrip("#")
 
         # 转义文字
         title = config.intro_title.replace(":", "\\:").replace("'", "\\'")
@@ -178,9 +177,7 @@ class IntroOutroEngine:
         filter_parts = []
 
         # 背景
-        filter_parts.append(
-            f"color=c={config.intro_background}:s={output_width}x{output_height}:d={duration}[bg]"
-        )
+        filter_parts.append(f"color=c={config.intro_background}:s={output_width}x{output_height}:d={duration}[bg]")
 
         # 标题
         if title:
@@ -357,8 +354,6 @@ class IntroOutroEngine:
         只传了片头或片尾也可以，缺失的自动跳过。
         """
         # 收集所有片段
-        segments: list[tuple[Path, float]] = []  # (path, duration)
-
         # 简单探测时长（用 ffprobe，这里简化处理：直接用 xfade 的 offset）
         # 先添加到列表
         has_intro = intro_video is not None and intro_video.exists()

apps/worker/video_processing/oss_helpers.py

@@ -14,6 +14,9 @@ from pathlib import Path
 from urllib.parse import urlparse
 
 import oss2
+import requests
+
+from packages.shared.config import get_shared_settings
 
 logger = logging.getLogger(__name__)
 
@@ -31,14 +34,18 @@ OSS_MULTIPART_NUM_THREADS = 3  # 分片上传并发数
 def oss_settings() -> tuple[str, str, str, str] | None:
     """获取 OSS 配置。
 
+    统一使用 SharedSettings 读取配置，与 SharedStorageService 保持一致，
+    支持从 .env 文件加载，避免两套配置路径不一致。
+
     Returns:
         (access_key_id, access_key_secret, endpoint, bucket_name) 元组，
         配置缺失时返回 None。
     """
-    access_key_id = os.getenv("OSS_ACCESS_KEY_ID")
-    access_key_secret = os.getenv("OSS_ACCESS_KEY_SECRET")
-    endpoint = os.getenv("OSS_ENDPOINT")
-    bucket_name = os.getenv("OSS_BUCKET_NAME")
+    settings = get_shared_settings()
+    access_key_id = settings.oss_access_key_id
+    access_key_secret = settings.oss_access_key_secret
+    endpoint = settings.oss_endpoint
+    bucket_name = settings.oss_bucket_name
     if not all([access_key_id, access_key_secret, endpoint, bucket_name]):
         return None
     return access_key_id, access_key_secret, endpoint, bucket_name
@@ -90,13 +97,22 @@ def normalize_storage_key(storage_key_or_url: str) -> str:
 def download_asset(asset_storage_key: str, local_path: Path) -> bool:
     """从 OSS 下载素材文件到本地路径。
 
+    自动识别输入类型：
+    - 完整 URL（http:// 或 https:// 开头）→ 走 HTTP 下载（支持预签名URL）
+    - OSS 存储键 → 走 oss2 SDK 下载
+
     Args:
-        asset_storage_key: 素材的存储键（或完整 URL）
+        asset_storage_key: 素材的存储键或完整 URL
         local_path: 本地保存路径
 
     Returns:
         True 表示下载成功，False 表示失败。
     """
+    # 完整URL走HTTP下载（兼容预签名URL）
+    if asset_storage_key.startswith(("http://", "https://")):
+        return _download_via_http(asset_storage_key, local_path)
+
+    # OSS存储键走SDK
     bucket = oss_bucket()
     if bucket is None:
         return False
@@ -108,6 +124,24 @@ def download_asset(asset_storage_key: str, local_path: Path) -> bool:
         return False
 
 
+def _download_via_http(url: str, local_path: Path) -> bool:
+    """通过 HTTP 下载文件（支持预签名 URL）。
+
+    使用流式下载避免大文件内存溢出，超时 300s。
+    """
+    try:
+        resp = requests.get(url, stream=True, timeout=300)
+        resp.raise_for_status()
+        with open(local_path, "wb") as f:
+            for chunk in resp.iter_content(chunk_size=8 * 1024 * 1024):
+                if chunk:
+                    f.write(chunk)
+        return local_path.exists() and local_path.stat().st_size > 0
+    except Exception:
+        logger.exception("HTTP下载素材失败: %s", url)
+        return False
+
+
 def upload_to_oss(local_path: Path, storage_key: str) -> str | None:
     """上传文件到 OSS，返回公开 URL。
 

apps/worker/video_processing/render_adapter.py

@@ -1,23 +1,26 @@
 """统一渲染引擎适配层 — Phase 2.
 
 将 EditPlan + EditPlanClips（来自 DB）适配为 UnifiedRenderService 的输入格式，
-封装素材下载、渲染执行、结果上传的完整流程。
+封装素材下载、BGM 准备、ASR 字幕、渲染执行、结果上传的完整流程。
 
 职责：
   1. 从 DB 读取 EditPlan + EditPlanClips
   2. 下载素材到本地，构建 asset_path_map
-  3. 调用 UnifiedRenderService 执行渲染
-  4. 上传渲染结果到 OSS
-  5. 支持进度回调（对接 JobService）
+  3. 准备 BGM 音频（URL / 素材库 / 预设库）
+  4. 初始化 ASR 服务（自动字幕）
+  5. 调用 UnifiedRenderService 执行渲染
+  6. 上传渲染结果到 OSS
+  7. 支持进度回调（对接 JobService）
 """
 
 from __future__ import annotations
 
 import logging
+import subprocess
 import tempfile
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Callable
+from typing import Any, Callable
 
 from sqlalchemy.orm import Session
 from video_processing.oss_helpers import download_asset, upload_to_oss
@@ -25,11 +28,30 @@ from video_processing.unified_render_service import UnifiedRenderService
 
 from packages.adapters.sqlalchemy_impl.edit_plan_clip_repository import SQLAlchemyEditPlanClipRepository
 from packages.adapters.sqlalchemy_impl.edit_plan_repository import SQLAlchemyEditPlanRepository
+from packages.adapters.sqlalchemy_impl.models import AssetModel
 from packages.domain.edit_plan import EditPlanStatus
 from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
 
 logger = logging.getLogger(__name__)
 
+DEFAULT_OUTPUT_WIDTH = 1080
+DEFAULT_OUTPUT_HEIGHT = 1920
+
+
+def _parse_resolution(resolution_str: str | None) -> tuple[int, int]:
+    """解析分辨率字符串，如 '1080x1920' → (1080, 1920)。解析失败返回默认值。"""
+    if not resolution_str or "x" not in resolution_str:
+        return DEFAULT_OUTPUT_WIDTH, DEFAULT_OUTPUT_HEIGHT
+    try:
+        w, h = resolution_str.lower().split("x", 1)
+        width = int(w.strip())
+        height = int(h.strip())
+        if width <= 0 or height <= 0:
+            return DEFAULT_OUTPUT_WIDTH, DEFAULT_OUTPUT_HEIGHT
+        return width, height
+    except (ValueError, TypeError):
+        return DEFAULT_OUTPUT_WIDTH, DEFAULT_OUTPUT_HEIGHT
+
 
 # ── 数据结构 ──────────────────────────────────────────────────────────────────
 
@@ -46,7 +68,16 @@ class RenderAdapterResult:
     width: int = 0
     height: int = 0
     clip_count: int = 0
+    rendered_clip_ids: list[str] = None  # 成功渲染的 clip id 列表
+    failed_clip_ids: list[str] = None  # 失败的 clip id 列表
     error_message: str = ""
+    error_detail: str = ""  # 详细错误信息（如 ffmpeg stderr），用于排查
+
+    def __post_init__(self):
+        if self.rendered_clip_ids is None:
+            self.rendered_clip_ids = []
+        if self.failed_clip_ids is None:
+            self.failed_clip_ids = []
 
 
 ProgressCallback = Callable[[float, str], None]
@@ -142,22 +173,48 @@ class RenderAdapter:
             self._report_progress(progress_cb, 15.0, f"下载素材（{len(ready_clips)} 个）")
 
             # 2. 下载素材
-            asset_path_map = self._download_assets(ready_clips, work_dir)
+            asset_path_map, rendered_clip_ids, failed_clip_ids = self._download_assets(ready_clips, work_dir)
             if not asset_path_map:
                 return RenderAdapterResult(
                     success=False,
                     error_message="所有素材下载失败",
                     clip_count=len(ready_clips),
+                    rendered_clip_ids=[],
+                    failed_clip_ids=failed_clip_ids,
                 )
 
+            self._report_progress(progress_cb, 35.0, "准备 BGM 音频")
+
+            # 3. 准备 BGM（从 plan.config.bgm 读取配置）
+            bgm_path = self._prepare_bgm(plan, work_dir, plan_id)
+
             self._report_progress(progress_cb, 40.0, "执行视频渲染")
 
-            # 3. 执行统一渲染
+            # 4. 初始化 ASR 服务（用于自动字幕）
+            asr_service = self._get_asr_service()
+
+            # 5. 从 plan.config.export 读取输出分辨率
+            plan_config = plan.config or {}
+            export_config = plan_config.get("export", {}) or {}
+            output_width, output_height = _parse_resolution(export_config.get("resolution"))
+            logger.info(
+                "渲染输出分辨率: plan_id=%s resolution=%dx%d source=%s",
+                plan_id,
+                output_width,
+                output_height,
+                "config" if export_config.get("resolution") else "default",
+            )
+
+            # 6. 执行统一渲染
             render_svc = UnifiedRenderService(
                 plan=plan,
                 clips=ready_clips,
                 asset_path_map=asset_path_map,
                 work_dir=work_dir,
+                output_width=output_width,
+                output_height=output_height,
+                bgm_path=bgm_path,
+                asr_service=asr_service,
             )
             result = render_svc.render()
 
@@ -190,8 +247,24 @@ class RenderAdapter:
                 width=result.width,
                 height=result.height,
                 clip_count=len(ready_clips),
+                rendered_clip_ids=rendered_clip_ids,
+                failed_clip_ids=failed_clip_ids,
             )
 
+        except subprocess.CalledProcessError as exc:
+            stderr_text = (exc.stderr or "").strip()
+            logger.error(
+                "[render-adapter] ffmpeg渲染失败: plan_id=%s job_id=%s exit_code=%d\nstderr:\n%s",
+                plan_id,
+                job_id,
+                exc.returncode,
+                stderr_text[:3000],
+            )
+            return RenderAdapterResult(
+                success=False,
+                error_message=f"FFmpeg渲染失败(exit={exc.returncode}): {stderr_text[:200]}",
+                error_detail=stderr_text[:3000],
+            )
         except Exception as exc:
             logger.exception(
                 "[render-adapter] render failed: plan_id=%s job_id=%s engine=unified error=%s",
@@ -270,30 +343,182 @@ class RenderAdapter:
             except Exception:
                 logger.exception("进度回调失败")
 
-    @staticmethod
-    def _download_assets(clips: list[EditPlanClip], work_dir: Path) -> dict[str, Path]:
-        """下载片段素材到本地，返回 asset_id → local_path 映射。
+    def _download_assets(
+        self, clips: list[EditPlanClip], work_dir: Path
+    ) -> tuple[dict[str, Path], list[str], list[str]]:
+        """下载片段素材到本地。
 
-        只保留下载成功的素材。
+        先通过 asset_id 批量查询 assets 表获取 file_url（OSS存储路径），
+        再用 file_url 作为 OSS key 下载。asset_id 是 UUID 主键，
+        不能直接当作 OSS 存储路径使用。
+
+        Returns:
+            (asset_path_map, rendered_clip_ids, failed_clip_ids)
+            - asset_path_map: asset_id → local_path 映射（下载成功的）
+            - rendered_clip_ids: 下载成功的 clip id 列表
+            - failed_clip_ids: 下载失败的 clip id 列表
         """
         asset_dir = work_dir / "assets"
         asset_dir.mkdir(exist_ok=True)
 
         asset_path_map: dict[str, Path] = {}
+        rendered_clip_ids: list[str] = []
+        failed_clip_ids: list[str] = []
+        seen_asset_ids: set[str] = set()
+
+        # 批量查询素材的 storage_key（OSS 存储路径）
+        # 兼容存量数据：storage_key 为空时 fallback 到 file_url
+        clip_asset_ids = [c.asset_id for c in clips if c.asset_id]
+        asset_storage_map: dict[str, str] = {}
+        if clip_asset_ids:
+            assets = self._db.query(AssetModel).filter(AssetModel.id.in_(clip_asset_ids)).all()
+            asset_storage_map = {
+                a.id: (a.storage_key or a.file_url or "") for a in assets if a.storage_key or a.file_url
+            }
 
         for clip in clips:
             asset_id = clip.asset_id
             if not asset_id:
+                failed_clip_ids.append(clip.id)
                 continue
 
-            # 生成安全的本地文件名
-            safe_name = f"clip_{clip.order:04d}_{abs(hash(asset_id)) % 100000:05d}.mp4"
+            # 同一素材已下载过（多个 clip 共享同一素材）
+            if asset_id in seen_asset_ids:
+                if asset_id in asset_path_map:
+                    rendered_clip_ids.append(clip.id)
+                else:
+                    failed_clip_ids.append(clip.id)
+                continue
+
+            seen_asset_ids.add(asset_id)
+
+            # 从素材表获取 OSS 存储路径（file_url）
+            storage_key = asset_storage_map.get(asset_id)
+            if not storage_key:
+                logger.warning(
+                    "素材无 file_url，跳过下载: clip_id=%s asset_id=%s",
+                    clip.id,
+                    asset_id,
+                )
+                failed_clip_ids.append(clip.id)
+                continue
+
+            # 生成安全的本地文件名（保留原始扩展名）
+            ext = Path(storage_key).suffix or ".mp4"
+            safe_name = f"clip_{clip.order:04d}_{abs(hash(asset_id)) % 100000:05d}{ext}"
             local_path = asset_dir / safe_name
 
-            if download_asset(asset_id, local_path):
+            if download_asset(storage_key, local_path):
                 asset_path_map[asset_id] = local_path
+                rendered_clip_ids.append(clip.id)
                 logger.debug("素材下载成功: clip_id=%s asset_id=%s", clip.id, asset_id[:60])
             else:
+                failed_clip_ids.append(clip.id)
                 logger.warning("素材下载失败: clip_id=%s asset_id=%s", clip.id, asset_id[:60])
 
-        return asset_path_map
+        return asset_path_map, rendered_clip_ids, failed_clip_ids
+
+    def _prepare_bgm(self, plan, work_dir: Path, plan_id: str) -> str | None:
+        """准备 BGM 音频文件（从 plan.config.bgm 读取配置）。
+
+        支持 3 种来源（按优先级）：
+        1. audio_url — 外部直链 URL
+        2. asset_id — 素材库中的音频素材
+        3. preset_id — 预设 BGM 库
+
+        失败不阻断主流程，返回 None。
+        """
+        from urllib.parse import urlparse
+
+        plan_config = plan.config or {}
+        bgm_config = plan_config.get("bgm", {}) or {}
+
+        if not bgm_config.get("enabled", False):
+            return None
+
+        audio_url = bgm_config.get("audio_url", "") or ""
+        asset_id = bgm_config.get("asset_id", "") or ""
+        preset_id = bgm_config.get("preset_id", "") or ""
+
+        bgm_file = work_dir / "bgm.mp3"
+
+        # 优先级1：外部直链 URL
+        if audio_url:
+            try:
+                parsed = urlparse(audio_url)
+                if parsed.scheme in ("http", "https"):
+                    from video_processing.url_security import (
+                        ALLOWED_AUDIO_MIME_TYPES,
+                        safe_download_file,
+                    )
+
+                    logger.info("[plan_id=%s] [BGM] 从URL下载: %s", plan_id, audio_url[:80])
+                    safe_download_file(
+                        audio_url,
+                        str(bgm_file),
+                        purpose="bgm_download",
+                        allowed_mime_types=ALLOWED_AUDIO_MIME_TYPES,
+                        timeout=60.0,
+                    )
+                    if bgm_file.exists() and bgm_file.stat().st_size > 0:
+                        return str(bgm_file)
+            except Exception as e:
+                logger.warning("[plan_id=%s] [BGM] URL下载失败: %s", plan_id, e)
+
+        # 优先级2：素材库素材
+        if asset_id:
+            try:
+                from packages.adapters.sqlalchemy_impl.models import AssetModel
+
+                model = self._db.query(AssetModel).filter(AssetModel.id == asset_id).first()
+                if model and (model.storage_key or model.file_url):
+                    # 兼容存量数据：storage_key 为空时 fallback 到 file_url
+                    storage_key = model.storage_key or model.file_url
+                    logger.info("[plan_id=%s] [BGM] 从素材库下载: asset_id=%s", plan_id, asset_id)
+                    ok = download_asset(storage_key, bgm_file)
+                    if ok and bgm_file.exists() and bgm_file.stat().st_size > 0:
+                        return str(bgm_file)
+            except Exception as e:
+                logger.warning("[plan_id=%s] [BGM] 素材库下载失败: %s", plan_id, e)
+
+        # 优先级3：预设 BGM 库
+        if preset_id:
+            try:
+                from packages.domain.preset_bgm import get_preset_bgm
+
+                preset = get_preset_bgm(preset_id)
+                if preset and preset.audio_url:
+                    from video_processing.url_security import (
+                        ALLOWED_AUDIO_MIME_TYPES,
+                        safe_download_file,
+                    )
+
+                    logger.info("[plan_id=%s] [BGM] 从预设库下载: preset_id=%s", plan_id, preset_id)
+                    safe_download_file(
+                        preset.audio_url,
+                        str(bgm_file),
+                        purpose="bgm_preset_download",
+                        allowed_mime_types=ALLOWED_AUDIO_MIME_TYPES,
+                        timeout=60.0,
+                    )
+                    if bgm_file.exists() and bgm_file.stat().st_size > 0:
+                        return str(bgm_file)
+            except Exception as e:
+                logger.warning("[plan_id=%s] [BGM] 预设库下载失败: %s", plan_id, e)
+
+        logger.warning("[plan_id=%s] [BGM] 所有来源都无法获取BGM，跳过", plan_id)
+        return None
+
+    @staticmethod
+    def _get_asr_service() -> Any | None:
+        """获取 ASR 服务实例（用于自动生成字幕）。
+
+        失败不阻断主流程，返回 None。
+        """
+        try:
+            from services.asr_service_factory import get_asr_service
+
+            return get_asr_service()
+        except Exception as e:
+            logger.warning("ASR 服务初始化失败，自动字幕将不可用: %s", e)
+            return None

apps/worker/video_processing/render_audio.py

@@ -156,7 +156,6 @@ def mix_audio(
         from video_processing.bgm_mixer import BGMConfig, mix_bgm_with_main
 
         bgm_cfg = BGMConfig.from_config_dict(bgm_path, bgm_config)
-        bgm_output = ctx.work_dir / f"audio_with_bgm_{ctx.plan_id}.aac"
 
         try:
             # 这里 main_audio 就是 output_path，先有主音频再混 BGM

apps/worker/video_processing/subtitle_render_engine.py

@@ -24,13 +24,11 @@
 from __future__ import annotations
 
 import logging
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
 from video_processing.path_security import PathSecurityError, is_in_allowed_dirs, safe_resolve_path
-from video_processing.render_subtitles import generate_ass_subtitles
-from video_processing.subtitle_generator import generate_ass_from_timeline
 
 logger = logging.getLogger(__name__)
 

apps/worker/video_processing/unified_render_service.py

@@ -44,7 +44,7 @@ from video_processing.pip_engine import PiPConfig, PiPEngine, PiPLayerConfig
 from video_processing.render_audio import RenderContext, merge_audio_video, mix_audio
 from video_processing.render_subtitles import generate_ass_subtitles
 from video_processing.reverse_engine import ReverseConfig, ReverseEngine
-from video_processing.speed_engine import SpeedConfig, SpeedEngine
+from video_processing.speed_engine import SpeedEngine
 from video_processing.sticker_engine import StickerEngine
 from video_processing.subtitle_generator import generate_ass_from_timeline
 from video_processing.transition_engine import TransitionEngine
@@ -759,6 +759,19 @@ class UnifiedRenderService:
         plan_config = getattr(self.plan, "config", None) or {}
         if isinstance(plan_config, dict) and plan_config.get("stickers"):
             return False
+
+        # 有水印时禁用直通（图片水印需要额外输入，统一走 filter_complex）
+        try:
+            from video_processing.watermark_engine import WatermarkConfig
+
+            wm_config = WatermarkConfig.from_dict(plan_config.get("watermark"))
+            if wm_config is not None and wm_config.validate()[0]:
+                return False
+        except Exception:
+            pass
+
+        # 有调速时仍然可以走直通（视频调速通过 setpts 实现，单输入即可）
+
         return True
 
     def _can_use_stream_copy(
@@ -971,6 +984,11 @@ class UnifiedRenderService:
             filters.append(f"trim=duration={effective_duration}")
             filters.append("setpts=PTS-STARTPTS")
 
+        # 调速 — 与 filter_complex 路径一致
+        speed = UnifiedRenderService._clip_speed(clip)
+        if abs(speed - 1.0) >= 1e-6:
+            filters.append(f"setpts=PTS/{speed:.4f}")
+
         # 倒放滤镜
         reverse_config = ReverseConfig.from_dict(clip.config.get("reverse"))
         if reverse_config.enabled and reverse_config.reverse_video:

apps/worker/video_processing/watermark_engine.py

@@ -243,7 +243,6 @@ class WatermarkEngine:
 
         # 构建滤镜
         # 先缩放水印图
-        wm_input_idx = 1  # 假设水印图是第二个输入（索引1
         filter_parts = [
             f"[1:v]{wm_filter}{wm_pre_label}",
             f"{input_video_label}{wm_pre_label}overlay={overlay_expr}{output_label}",

apps/worker/worker_app/tasks/asset_analyzer.py

@@ -11,7 +11,6 @@ from __future__ import annotations
 import json
 import logging
 import os
-import subprocess
 import tempfile
 from dataclasses import dataclass, field
 

apps/worker/worker_app/tasks/batch_download.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import logging
-import os
 import tempfile
 import uuid
 import zipfile
@@ -25,7 +24,7 @@ def batch_download_videos(self, video_ids: list[str], user_id: str = "") -> dict
     Returns:
         {"download_url": "...", "file_count": N, "total_size": total_bytes}
     """
-    from video_processing.oss_helpers import download_asset, upload_to_oss
+    from video_processing.oss_helpers import upload_to_oss
     from worker_app.db import SessionLocal
 
     from packages.adapters.sqlalchemy_impl.generated_video_repository import (

apps/worker/worker_app/tasks/edit_plan_generation.py

@@ -39,7 +39,6 @@ from video_processing.oss_helpers import (
     download_asset,
     upload_to_oss,
 )
-from video_processing.unified_render_service import UnifiedRenderService
 
 # ── Repository imports (延迟导入避免循环依赖) ─────────────────────────────────
 
@@ -218,9 +217,6 @@ def _finalize_render_success(
 def _render_with_unified(
     plan,
     clips,
-    asset_path_map: dict[str, Path],
-    tmpdir_path: Path,
-    rendered_clip_ids: list[str],
     plan_id: str,
     generation_task_id: str,
     plan_repo,
@@ -228,31 +224,62 @@ def _render_with_unified(
     gen_task_repo,
     db,
 ) -> dict:
-    """统一渲染引擎路径（UnifiedRenderService 图层架构）。"""
-    render_service = UnifiedRenderService(
-        plan=plan,
-        clips=clips,
-        asset_path_map=asset_path_map,
-        work_dir=tmpdir_path,
-        output_width=OUTPUT_WIDTH,
-        output_height=OUTPUT_HEIGHT,
-        output_fps=int(OUTPUT_FPS),
-    )
+    """统一渲染引擎路径（通过 RenderAdapter 调用 UnifiedRenderService）。
+
+    RenderAdapter 内部处理：素材下载、BGM 准备、ASR 自动字幕、渲染执行、OSS 上传。
+    本函数只负责：业务状态更新、查重、收尾。
+    """
+    from video_processing.render_adapter import RenderAdapter
+
+    adapter = RenderAdapter(db)
+
+    # 进度回调：更新 GenerationTask 进度
+    def _progress_cb(progress: float, stage: str):
+        if not generation_task_id:
+            return
+        try:
+            gen_task = gen_task_repo.get(generation_task_id)
+            if gen_task:
+                # 映射到 30%~90% 区间（素材下载前已到 30%）
+                mapped_progress = 30.0 + progress * 0.6
+                gen_task.progress = min(mapped_progress, 95.0)
+                gen_task.append_log(
+                    stage="render_progress",
+                    message=stage,
+                    level="INFO",
+                    progress=mapped_progress,
+                )
+                gen_task_repo.update(gen_task)
+        except Exception:
+            pass
 
     try:
-        render_result = render_service.render()
+        result = adapter.render_plan(
+            plan_id=plan_id,
+            job_id=generation_task_id or plan_id,
+            progress_cb=_progress_cb,
+        )
     except Exception as render_err:
         logger.error("渲染失败(unified): %s — %s", plan_id, render_err)
         _mark_plan_failed(plan_repo, plan_id, gen_task_repo, generation_task_id, f"渲染失败: {render_err}")
         return {"status": "error", "message": f"渲染失败: {render_err}"}
 
-    output_path = render_result.output_path
+    if not result.success:
+        full_error = result.error_message or "渲染失败"
+        if result.error_detail:
+            full_error = f"{full_error}\n--- stderr ---\n{result.error_detail}"
+        logger.error("渲染失败(unified): %s — %s", plan_id, result.error_message)
+        _mark_plan_failed(plan_repo, plan_id, gen_task_repo, generation_task_id, full_error)
+        return {"status": "error", "message": result.error_message or "渲染失败"}
 
-    # 上传到 OSS
+    output_path = result.output_path or Path("")
+    output_url = result.output_url
     storage_key = f"rendered/{plan_id}/output.mp4"
-    output_url = upload_to_oss(output_path, storage_key)
 
-    failed_clip_ids: list[str] = []
+    # 用 adapter 返回的 clip 明细（以 adapter 的结果为准）
+    rendered_clip_ids = result.rendered_clip_ids or []
+    failed_clip_ids = result.failed_clip_ids or []
+
     return _finalize_render_success(
         plan=plan,
         plan_repo=plan_repo,
@@ -262,10 +289,10 @@ def _render_with_unified(
         plan_id=plan_id,
         output_url=output_url or "",
         storage_key=storage_key,
-        duration=render_result.duration,
-        file_size=render_result.file_size,
-        width=render_result.width,
-        height=render_result.height,
+        duration=result.duration,
+        file_size=result.file_size,
+        width=result.width,
+        height=result.height,
         rendered_clip_ids=rendered_clip_ids,
         failed_clip_ids=failed_clip_ids,
         generation_task_id=generation_task_id,
@@ -305,7 +332,34 @@ def _render_with_legacy(
     # 构建 FFmpeg 命令
     output_dir = os.environ.get("VIDEO_OUTPUT_DIR", str(tmpdir_path))
     output_path = Path(output_dir) / f"{plan_id}.mp4"
-    compose_cmd = compose_svc.build_compose_command(plan_id, str(output_path))
+
+    # 从 plan.config.export 读取输出分辨率，兼容 plan 自定义配置
+    plan_config = plan.config or {}
+    export_config = plan_config.get("export", {}) or {}
+    output_width = OUTPUT_WIDTH
+    output_height = OUTPUT_HEIGHT
+    resolution = export_config.get("resolution", "")
+    if resolution and "x" in resolution:
+        try:
+            w_str, h_str = resolution.lower().split("x", 1)
+            output_width = int(w_str)
+            output_height = int(h_str)
+        except (ValueError, TypeError):
+            pass
+
+    fps = export_config.get("fps", 25)
+    try:
+        fps = int(fps)
+    except (ValueError, TypeError):
+        fps = 25
+
+    compose_cmd = compose_svc.build_compose_command(
+        plan_id,
+        str(output_path),
+        output_width=output_width,
+        output_height=output_height,
+        fps=fps,
+    )
 
     logger.info("执行 FFmpeg (legacy): plan_id=%s", plan_id)
     try:
@@ -337,8 +391,8 @@ def _render_with_legacy(
         storage_key=storage_key,
         duration=duration,
         file_size=file_size,
-        width=OUTPUT_WIDTH,
-        height=OUTPUT_HEIGHT,
+        width=output_width,
+        height=output_height,
         rendered_clip_ids=rendered_clip_ids,
         failed_clip_ids=failed_clip_ids,
         generation_task_id=generation_task_id,
@@ -406,106 +460,125 @@ def render_edit_plan(self, plan_id: str) -> dict:
                     )
                     gen_task_repo.update(gen_task)
 
-            # 3. 下载素材并构建 asset_path_map
-            with tempfile.TemporaryDirectory(prefix="edit_plan_") as tmpdir:
-                tmpdir_path = Path(tmpdir)
-                asset_path_map: dict[str, Path] = {}
-                rendered_clip_ids: list[str] = []
-                failed_clip_ids: list[str] = []
+            # 3. 渲染前取消检查
+            if generation_task_id:
+                current_task = gen_task_repo.get(generation_task_id)
+                if current_task:
+                    task_status = (
+                        current_task.status.value if hasattr(current_task.status, "value") else str(current_task.status)
+                    )
+                    if task_status == "cancelled":
+                        logger.info("任务已被取消，中止渲染: plan_id=%s task_id=%s", plan_id, generation_task_id)
 
-                # 预先批量查询所有素材的 storage_key（file_url）
-                from packages.adapters.sqlalchemy_impl.models import AssetModel
+                        if plan.status.value == "rendering":
+                            try:
+                                plan.resume_editing()
+                                plan_repo.update(plan)
+                            except ValueError:
+                                pass
+                        return {"status": "cancelled", "plan_id": plan_id, "message": "任务已取消"}
 
-                clip_asset_ids = [c.asset_id for c in clips if c.asset_id]
-                asset_storage_map: dict[str, str] = {}
-                if clip_asset_ids:
-                    assets = db.query(AssetModel).filter(AssetModel.id.in_(clip_asset_ids)).all()
-                    asset_storage_map = {a.id: a.file_url for a in assets if a.file_url}
+            # 4. 根据引擎选择渲染方式
+            if engine == "unified":
+                # ── unified 路径：RenderAdapter 统一处理（下载 + BGM + ASR + 渲染 + 上传）
+                result = _render_with_unified(
+                    plan=plan,
+                    clips=clips,
+                    plan_id=plan_id,
+                    generation_task_id=generation_task_id,
+                    plan_repo=plan_repo,
+                    clip_repo=clip_repo,
+                    gen_task_repo=gen_task_repo,
+                    db=db,
+                )
+            else:
+                # ── legacy 路径：原有的素材下载 + VideoComposeService
+                with tempfile.TemporaryDirectory(prefix="edit_plan_") as tmpdir:
+                    tmpdir_path = Path(tmpdir)
+                    asset_path_map: dict[str, Path] = {}
+                    rendered_clip_ids: list[str] = []
+                    failed_clip_ids: list[str] = []
 
-                for clip in clips:
-                    if not clip.asset_id:
-                        # 没有素材的片段跳过，标记为失败
-                        clip.mark_failed()
-                        clip_repo.update(clip)
-                        failed_clip_ids.append(clip.id)
-                        continue
+                    # 预先批量查询所有素材的 storage_key
+                    # 兼容存量数据：storage_key 为空时 fallback 到 file_url
+                    from packages.adapters.sqlalchemy_impl.models import AssetModel
 
-                    if clip.asset_id in asset_path_map:
-                        # 同一素材已下载（多个 clip 共享同一素材）
-                        rendered_clip_ids.append(clip.id)
-                        continue
+                    clip_asset_ids = [c.asset_id for c in clips if c.asset_id]
+                    asset_storage_map: dict[str, str] = {}
+                    if clip_asset_ids:
+                        assets = db.query(AssetModel).filter(AssetModel.id.in_(clip_asset_ids)).all()
+                        asset_storage_map = {
+                            a.id: (a.storage_key or a.file_url or "") for a in assets if a.storage_key or a.file_url
+                        }
 
-                    storage_key = asset_storage_map.get(clip.asset_id)
-                    if not storage_key:
-                        logger.warning(
-                            "片段素材无 storage_key，跳过: clip_id=%s asset_id=%s",
-                            clip.id,
-                            clip.asset_id,
-                        )
-                        clip.mark_failed()
-                        clip_repo.update(clip)
-                        failed_clip_ids.append(clip.id)
-                        continue
+                    for clip in clips:
+                        if not clip.asset_id:
+                            # 没有素材的片段跳过，标记为失败
+                            clip.mark_failed()
+                            clip_repo.update(clip)
+                            failed_clip_ids.append(clip.id)
+                            continue
 
-                    # 下载素材
-                    ext = Path(storage_key).suffix or ".mp4"
-                    local_path = tmpdir_path / f"clip_{clip.order:04d}{ext}"
-                    if download_asset(storage_key, local_path):
-                        asset_path_map[clip.asset_id] = local_path
-                        rendered_clip_ids.append(clip.id)
-                    else:
-                        clip.mark_failed()
-                        clip_repo.update(clip)
-                        failed_clip_ids.append(clip.id)
+                        if clip.asset_id in asset_path_map:
+                            # 同一素材已下载（多个 clip 共享同一素材）
+                            rendered_clip_ids.append(clip.id)
+                            continue
 
-                if not asset_path_map:
-                    logger.error("所有片段素材下载失败: %s", plan_id)
-                    plan.mark_failed()
-                    plan_repo.update(plan)
+                        storage_key = asset_storage_map.get(clip.asset_id)
+                        if not storage_key:
+                            logger.warning(
+                                "片段素材无 storage_key，跳过: clip_id=%s asset_id=%s",
+                                clip.id,
+                                clip.asset_id,
+                            )
+                            clip.mark_failed()
+                            clip_repo.update(clip)
+                            failed_clip_ids.append(clip.id)
+                            continue
+
+                        # 下载素材
+                        ext = Path(storage_key).suffix or ".mp4"
+                        local_path = tmpdir_path / f"clip_{clip.order:04d}{ext}"
+                        if download_asset(storage_key, local_path):
+                            asset_path_map[clip.asset_id] = local_path
+                            rendered_clip_ids.append(clip.id)
+                        else:
+                            clip.mark_failed()
+                            clip_repo.update(clip)
+                            failed_clip_ids.append(clip.id)
+
+                    if not asset_path_map:
+                        logger.error("所有片段素材下载失败: %s", plan_id)
+                        plan.mark_failed()
+                        plan_repo.update(plan)
+                        if generation_task_id:
+                            gen_task = gen_task_repo.get(generation_task_id)
+                            if gen_task:
+                                gen_task.status = "failed"
+                                gen_task.error_message = "所有片段素材下载失败"
+                                gen_task.completed_at = datetime.now(timezone.utc)
+                                gen_task.append_log(
+                                    stage="download_failed",
+                                    message="所有片段素材下载失败",
+                                    level="ERROR",
+                                )
+                                gen_task_repo.update(gen_task)
+                        return {"status": "error", "message": "所有片段素材下载失败"}
+
+                    # 素材下载完成，记录日志
                     if generation_task_id:
                         gen_task = gen_task_repo.get(generation_task_id)
                         if gen_task:
-                            gen_task.status = "failed"
-                            gen_task.error_message = "所有片段素材下载失败"
-                            gen_task.completed_at = datetime.now(timezone.utc)
                             gen_task.append_log(
-                                stage="download_failed",
-                                message="所有片段素材下载失败",
-                                level="ERROR",
+                                stage="download_done",
+                                message=f"素材下载完成，成功 {len(asset_path_map)} 个，失败 {len(failed_clip_ids)} 个",
+                                level="INFO",
+                                success_count=len(asset_path_map),
+                                failed_count=len(failed_clip_ids),
                             )
+                            gen_task.progress = 30.0
                             gen_task_repo.update(gen_task)
-                    return {"status": "error", "message": "所有片段素材下载失败"}
 
-                # 素材下载完成，记录日志
-                if generation_task_id:
-                    gen_task = gen_task_repo.get(generation_task_id)
-                    if gen_task:
-                        gen_task.append_log(
-                            stage="download_done",
-                            message=f"素材下载完成，成功 {len(asset_path_map)} 个，失败 {len(failed_clip_ids)} 个",
-                            level="INFO",
-                            success_count=len(asset_path_map),
-                            failed_count=len(failed_clip_ids),
-                        )
-                        gen_task.progress = 30.0
-                        gen_task_repo.update(gen_task)
-
-                # 4. 根据引擎选择渲染方式
-                if engine == "unified":
-                    result = _render_with_unified(
-                        plan=plan,
-                        clips=clips,
-                        asset_path_map=asset_path_map,
-                        tmpdir_path=tmpdir_path,
-                        rendered_clip_ids=rendered_clip_ids,
-                        plan_id=plan_id,
-                        generation_task_id=generation_task_id,
-                        plan_repo=plan_repo,
-                        clip_repo=clip_repo,
-                        gen_task_repo=gen_task_repo,
-                        db=db,
-                    )
-                else:
                     result = _render_with_legacy(
                         plan=plan,
                         clips=clips,
@@ -520,8 +593,8 @@ def render_edit_plan(self, plan_id: str) -> dict:
                         db=db,
                     )
 
-                result["engine"] = engine
-                return result
+            result["engine"] = engine
+            return result
 
         except Exception as exc:
             logger.exception("渲染剪辑计划异常: %s", plan_id)

apps/worker/worker_app/tasks/generation.py

@@ -178,10 +178,136 @@ class _VirtualClip:
     config: dict[str, Any] = field(default_factory=dict)
 
 
+def _load_template_clip_configs(template_id: str) -> list:
+    """从数据库读取模板的片段配置列表。
+
+    失败返回空列表，不阻断主流程。
+    """
+    if not template_id:
+        return []
+    try:
+        from worker_app.db import SessionLocal
+
+        from packages.adapters.sqlalchemy_impl.template_clip_config_repository import (
+            SQLAlchemyTemplateClipConfigRepository,
+        )
+
+        session = SessionLocal()
+        try:
+            repo = SQLAlchemyTemplateClipConfigRepository(session)
+            configs = repo.list_by_template(template_id, limit=200)
+            logger.info("读取模板片段配置: template_id=%s count=%d", template_id, len(configs))
+            return configs
+        finally:
+            session.close()
+    except Exception as e:
+        logger.warning("读取模板片段配置失败，跳过效果层映射: template_id=%s error=%s", template_id, e)
+        return []
+
+
+def _extract_intro_outro_from_clip_configs(clip_configs: list) -> dict[str, Any]:
+    """从模板的 intro/outro 类型 clip_config 中提取 plan 级 intro_outro 配置。
+
+    UnifiedRenderService 已支持 plan.config.intro_outro 路径，
+    这里把 intro/outro 片段配置转为统一格式注入。
+    """
+    intro_configs = [
+        c for c in clip_configs if (c.clip_type.value if hasattr(c.clip_type, "value") else c.clip_type) == "intro"
+    ]
+    outro_configs = [
+        c for c in clip_configs if (c.clip_type.value if hasattr(c.clip_type, "value") else c.clip_type) == "outro"
+    ]
+
+    result: dict[str, Any] = {}
+
+    if intro_configs:
+        intro = intro_configs[0]
+        intro_cfg = intro.config or {}
+        result["has_intro"] = True
+        result["intro_type"] = intro_cfg.get("intro_type", "text")
+        result["intro_duration"] = intro.default_duration or 3.0
+        if intro.text_template:
+            result["intro_text"] = intro.text_template
+        # 透传额外配置
+        for key in ("intro_text_color", "intro_bg_color", "intro_font_size", "intro_video_url", "intro_video_path"):
+            if key in intro_cfg:
+                result[key] = intro_cfg[key]
+
+    if outro_configs:
+        outro = outro_configs[0]
+        outro_cfg = outro.config or {}
+        result["has_outro"] = True
+        result["outro_type"] = outro_cfg.get("outro_type", "text")
+        result["outro_duration"] = outro.default_duration or 3.0
+        if outro.text_template:
+            result["outro_text"] = outro.text_template
+        for key in ("outro_text_color", "outro_bg_color", "outro_font_size", "outro_follow_text"):
+            if key in outro_cfg:
+                result[key] = outro_cfg[key]
+
+    return result
+
+
+def _apply_template_clip_effects(
+    clips: list[_VirtualClip],
+    clip_configs: list,
+    mode: str,
+) -> None:
+    """将模板的 clip 级效果层映射到素材 clips 上（就地修改）。
+
+    映射规则：
+    - 只对素材主体 clips 做映射（ONE_TAKE: main, PIP: main+overlay, VOICE_OVER: main, VOICE_PIP: background+b_roll）
+    - 从模板中筛选 main 类型的 clip_config 作为效果模板
+    - 素材 clips 按顺序循环匹配模板 clip_config（素材多的话重复使用最后一个模板配置）
+    - 映射字段：transition_effect, config.color_grade, config.speed
+    """
+    if not clip_configs or not clips:
+        return
+
+    # 筛选 main 类型的模板配置（作为效果模板池）
+    main_configs = [
+        c
+        for c in clip_configs
+        if (c.clip_type.value if hasattr(c.clip_type, "value") else c.clip_type) in ("main", "showcase", "b_roll")
+    ]
+    if not main_configs:
+        return
+
+    # 确定需要映射的素材 clips（排除 corner_voice 等特殊层）
+    target_clips = [c for c in clips if c.clip_type not in ("corner_voice",)]
+
+    for i, clip in enumerate(target_clips):
+        # 循环匹配：素材多了用最后一个模板配置
+        cfg_idx = min(i, len(main_configs) - 1)
+        template_cfg = main_configs[cfg_idx]
+
+        # 1. 转场效果
+        transition = (
+            template_cfg.transition_effect.value
+            if hasattr(template_cfg.transition_effect, "value")
+            else template_cfg.transition_effect
+        )
+        if transition and transition != "cut":
+            clip.transition_effect = transition
+
+        # 2. clip 级效果配置（滤镜、调速等）
+        template_clip_config = template_cfg.config or {}
+        if template_clip_config:
+            # 合并到 clip.config（保留已有配置如 role 等）
+            existing_config = clip.config or {}
+            # 需要从模板复制的效果层 key
+            effect_keys = ("color_grade", "speed", "playback_speed", "reverse", "chroma_key", "filter")
+            for key in effect_keys:
+                if key in template_clip_config:
+                    existing_config[key] = template_clip_config[key]
+            clip.config = existing_config
+
+
 def _build_plan_and_clips_from_task(
     task_id: str,
     downloaded_paths: list[Path],
     mode: str,
+    template_id: str = "",
 ) -> tuple[_VirtualPlan, list[_VirtualClip], dict[str, Path]]:
     """根据模式和下载的素材路径，构建虚拟 plan + clips + asset_path_map。
 
@@ -269,6 +395,25 @@ def _build_plan_and_clips_from_task(
                 )
             )
 
+    # ── P1: 模板效果层映射 ──
+    if template_id:
+        clip_configs = _load_template_clip_configs(template_id)
+        if clip_configs:
+            # 1. clip级效果层（转场、滤镜、调速等）
+            _apply_template_clip_effects(clips, clip_configs, mode)
+
+            # 2. 片头片尾（从 intro/outro 类型 clip 提取 plan 级配置）
+            intro_outro_config = _extract_intro_outro_from_clip_configs(clip_configs)
+            if intro_outro_config:
+                plan_config = plan.config or {}
+                plan_config["intro_outro"] = intro_outro_config
+                plan.config = plan_config
+                logger.info(
+                    "模板片头片尾配置已注入: has_intro=%s has_outro=%s",
+                    intro_outro_config.get("has_intro", False),
+                    intro_outro_config.get("has_outro", False),
+                )
+
     return plan, clips, asset_path_map
 
 
@@ -392,8 +537,9 @@ def _prepare_bgm_track(
             session = SessionLocal()
             try:
                 model = session.query(AssetModel).filter(AssetModel.id == asset_id).first()
-                if model and model.file_url:
-                    storage_key = model.file_url
+                if model and (model.storage_key or model.file_url):
+                    # 兼容存量数据：storage_key 为空时 fallback 到 file_url
+                    storage_key = model.storage_key or model.file_url
                     logger.info("[task_id=%s] [BGM] 从素材库下载: asset_id=%s", task_id, asset_id)
                     ok = download_asset(storage_key, bgm_file)
                     if ok and bgm_file.exists() and bgm_file.stat().st_size > 0:
@@ -774,6 +920,47 @@ def _validate_template_exists(template_id: str) -> None:
         session.close()
 
 
+def _load_template_plan_config(template_id: str) -> dict:
+    """从模板加载 plan 级配置（BGM、字幕、滤镜等效果层）。
+
+    模板不存在时返回空 dict，不阻塞主流程。
+    """
+    if not template_id:
+        return {}
+    try:
+        from packages.adapters.sqlalchemy_impl.models import TemplateModel
+
+        session = SessionLocal()
+        try:
+            template = (
+                session.query(TemplateModel)
+                .filter(
+                    TemplateModel.id == template_id,
+                    TemplateModel.is_active.is_(True),
+                )
+                .first()
+            )
+            if template is None:
+                logger.warning("模板不存在，跳过配置加载: template_id=%s", template_id)
+                return {}
+            config = template.config or {}
+            if isinstance(config, str):
+                import json
+
+                config = json.loads(config)
+            logger.info(
+                "模板配置加载成功: template_id=%s keys=%s",
+                template_id,
+                list(config.keys()),
+            )
+            return config
+        finally:
+            session.close()
+    except Exception as e:
+        logger.warning("加载模板配置失败，跳过: template_id=%s err=%s", template_id, e)
+        return {}
+
+
 # ── 渲染引擎选择 ─────────────────────────────────────────────────────────────
 
 
@@ -1030,8 +1217,22 @@ def _render_video(
         task_id=task_id,
         downloaded_paths=downloaded_videos,
         mode=editing_mode.value,
+        template_id=template_id,
     )
 
+    # 注入模板配置（BGM、字幕等效果层）
+    if template_id:
+        template_config = _load_template_plan_config(template_id)
+        if template_config:
+            # 合并：现有 config 优先级更高（目前为空，模板配置直接生效）
+            base_config = virtual_plan.config or {}
+            virtual_plan.config = {**template_config, **base_config}
+            logger.info(
+                "[task_id=%s] [渲染] 模板配置已注入: keys=%s",
+                task_id,
+                list(template_config.keys()),
+            )
+
     total_duration = sum(c.duration for c in virtual_clips)
     logger.info(
         "[task_id=%s] [剪辑计划] 片段数=%d, 总时长=%.1fs",

apps/worker/worker_app/tasks/ingest.py

@@ -1,7 +1,10 @@
 import subprocess
+import tempfile
 from datetime import datetime, timezone
+from pathlib import Path
 
 from celery.utils.log import get_task_logger
+from video_processing.oss_helpers import download_asset
 from worker_app.celery_app import celery_app
 from worker_app.core.asset_types import infer_mime_type_from_storage_key
 from worker_app.db import SessionLocal
@@ -15,6 +18,32 @@ from packages.domain import Asset, AssetStatus, IngestJobStatus
 logger = get_task_logger(__name__)
 
 
+# 最小有效文件大小（字节）：小于此值的直接判为无效，避免文本/空文件伪装成媒体
+MIN_VIDEO_FILE_SIZE = 1024  # 1KB
+MIN_AUDIO_FILE_SIZE = 100  # 100B
+MIN_IMAGE_FILE_SIZE = 100  # 100B
+
+# 支持的视频编码格式（白名单）
+# 渲染引擎针对 H.264 优化，其他编码可能导致渲染失败或异常
+SUPPORTED_VIDEO_CODECS = {"h264", "avc1", "avc"}
+
+# 明确不支持的视频编码（用于日志提示）
+UNSUPPORTED_VIDEO_CODECS = {
+    "hevc",
+    "h265",
+    "hev1",
+    "hvc1",  # H.265 / HEVC
+    "vp9",
+    "vp09",  # VP9
+    "av1",
+    "av01",  # AV1
+    "vp8",
+    "vp08",  # VP8
+    "mpeg4",
+    "mp4v",  # MPEG-4
+}
+
+
 def _safe_parse_fps(fps_str: str) -> float:
     """Safely parse fps from a fraction string like \"30/1\" or \"30000/1001\"."""
     try:
@@ -29,7 +58,7 @@ def _safe_parse_fps(fps_str: str) -> float:
         return 0.0
 
 
-def extract_media_metadata(file_url: str, media_type: str) -> dict:
+def extract_media_metadata(file_url: str, media_type: str) -> tuple[dict, bool]:
     """
     提取媒体文件的元数据。
 
@@ -38,9 +67,12 @@ def extract_media_metadata(file_url: str, media_type: str) -> dict:
         media_type: 媒体类型 (video, audio, image)
 
     Returns:
-        提取的元数据字典，失败时返回空字典
+        (metadata_dict, success)
+        - metadata_dict: 提取的元数据字典，失败时返回空字典
+        - success: 是否成功提取到有效元数据
     """
     metadata = {}
+    success = False
 
     try:
         if media_type == "video":
@@ -80,23 +112,66 @@ def extract_media_metadata(file_url: str, media_type: str) -> dict:
                 metadata["size_bytes"] = int(format_info.get("size", 0))
                 metadata["bitrate"] = int(format_info.get("bit_rate", 0))
 
+                # 有效性判断：有视频流 + duration > 0 + size > 0
+                has_video_stream = any(s.get("codec_type") == "video" for s in probe_data.get("streams", []))
+                has_audio_stream = any(s.get("codec_type") == "audio" for s in probe_data.get("streams", []))
+                if (has_video_stream or has_audio_stream) and metadata.get("duration", 0) > 0:
+                    success = True
+
             except Exception as e:
                 logger.warning("视频元数据提取失败: %s", e)
 
+        elif media_type == "audio":
+            from video_processing.ffmpeg_utils import run_ffprobe
+
+            cmd = [
+                "ffprobe",
+                "-v",
+                "quiet",
+                "-print_format",
+                "json",
+                "-show_format",
+                "-show_streams",
+                file_url,
+            ]
+            try:
+                stdout, _ = run_ffprobe(cmd, timeout=30)
+                import json as json_lib
+
+                probe_data = json_lib.loads(stdout)
+
+                has_audio_stream = any(s.get("codec_type") == "audio" for s in probe_data.get("streams", []))
+                format_info = probe_data.get("format", {})
+                metadata["duration"] = float(format_info.get("duration", 0))  # type: ignore[assignment]
+                metadata["size_bytes"] = int(format_info.get("size", 0))
+                metadata["bitrate"] = int(format_info.get("bit_rate", 0))
+                metadata["codec"] = next(
+                    (s.get("codec_name", "") for s in probe_data.get("streams", []) if s.get("codec_type") == "audio"),
+                    "",
+                )
+
+                if has_audio_stream and metadata.get("duration", 0) > 0:
+                    success = True
+
+            except Exception as e:
+                logger.warning("音频元数据提取失败: %s", e)
+
         elif media_type == "image":
             # 使用 Pillow 提取图片元数据
             try:
                 from PIL import Image
 
                 with Image.open(file_url) as img:
-                    metadata["width"] = img.width
-                    metadata["height"] = img.height
-                    metadata["format"] = img.format
-                    metadata["mode"] = img.mode
-                    if hasattr(img, "_getexif") and img._getexif():
-                        exif = img._getexif()
-                        if exif:
-                            metadata["exif"] = {k: str(v) for k, v in exif.items() if isinstance(v, (str, int, float))}  # type: ignore[assignment]
+                    img.verify()  # 验证文件完整性
+                    # verify后需要重新打开才能读尺寸
+                    with Image.open(file_url) as img2:
+                        metadata["width"] = img2.width
+                        metadata["height"] = img2.height
+                        metadata["format"] = img2.format
+                        metadata["mode"] = img2.mode
+                        if img2.width > 0 and img2.height > 0:
+                            success = True
+
             except ImportError:
                 logger.warning("Pillow not available for image metadata extraction")
             except Exception as e:
@@ -109,7 +184,38 @@ def extract_media_metadata(file_url: str, media_type: str) -> dict:
     except Exception as e:
         logger.warning(f"Failed to extract metadata: {e}")
 
-    return metadata
+    return metadata, success
+
+
+def _is_valid_media(metadata: dict, media_type: str) -> bool:
+    """根据元数据判断文件是否为有效媒体文件。
+
+    Args:
+        metadata: extract_media_metadata 返回的元数据
+        media_type: 媒体类型
+
+    Returns:
+        True 表示文件有效
+    """
+    size = int(metadata.get("size_bytes", 0))
+
+    if media_type == "video":
+        duration = float(metadata.get("duration", 0))
+        if size < MIN_VIDEO_FILE_SIZE or duration <= 0:
+            return False
+        # 编码格式校验：仅支持 H.264，其他编码（HEVC/VP9/AV1等）渲染可能失败
+        codec = str(metadata.get("codec", "")).lower()
+        if codec and codec not in SUPPORTED_VIDEO_CODECS:
+            return False
+        return True
+    if media_type == "audio":
+        duration = float(metadata.get("duration", 0))
+        return size >= MIN_AUDIO_FILE_SIZE and duration > 0
+    if media_type == "image":
+        width = int(metadata.get("width", 0))
+        height = int(metadata.get("height", 0))
+        return size >= MIN_IMAGE_FILE_SIZE and width > 0 and height > 0
+    return False
 
 
 @celery_app.task(name="worker.ingest_asset")
@@ -150,17 +256,71 @@ def ingest_asset(job_id: str) -> dict:
         elif mime_type.startswith("audio/"):
             media_type = "audio"
 
-        # Extract metadata (returns empty dict on failure)
-        storage_url = job.storage_key  # Assuming storage_key is usable as URL/path
-        metadata = extract_media_metadata(storage_url, media_type)
+        # 先从 OSS 下载文件到本地临时目录，再提取元数据
+        # （storage_key 是 OSS 内部路径，不能直接传给 ffprobe/Pillow）
+        local_file = None
+        try:
+            suffix = Path(job.storage_key).suffix or ".bin"
+            with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+                local_file = Path(tmp.name)
 
-        # Fill in defaults if metadata extraction failed
-        if not metadata:
-            metadata = {
-                "duration": 0,
-                "width": 0,
-                "height": 0,
-                "size_bytes": 0,
+            download_ok = download_asset(job.storage_key, local_file)
+            if not download_ok:
+                logger.warning("素材下载失败，无法提取元数据: job_id=%s storage_key=%s", job_id, job.storage_key)
+                metadata, extract_success = {}, False
+            else:
+                metadata, extract_success = extract_media_metadata(str(local_file), media_type)
+        finally:
+            if local_file and local_file.exists():
+                try:
+                    local_file.unlink()
+                except OSError:
+                    pass
+
+        # 有效性校验：ffprobe/Pillow 必须成功，且文件大小/时长/尺寸满足最小要求
+        is_valid = extract_success and _is_valid_media(metadata, media_type)
+
+        if not is_valid:
+            # 文件无效，创建 ERROR 状态的 asset 并标记 job 失败
+            error_reason = "metadata extraction failed" if not extract_success else "media validation failed"
+            logger.warning(
+                "素材有效性校验失败，标记为ERROR: job_id=%s storage_key=%s media_type=%s reason=%s",
+                job_id,
+                job.storage_key,
+                media_type,
+                error_reason,
+            )
+
+            asset = Asset.create(
+                project_id=job.project_id,
+                library_id=job.library_id,
+                name=filename,
+                storage_key=job.storage_key,
+                mime_type=mime_type,
+                metadata={"ingest_error": error_reason},
+                file_size=int(metadata.get("size_bytes", 0)),
+                duration=float(metadata.get("duration", 0)),
+                width=int(metadata.get("width", 0)),
+                height=int(metadata.get("height", 0)),
+                codec=metadata.get("codec") or None,
+                status=AssetStatus.ERROR,
+                file_hash=job.file_hash,
+            )
+            asset_repo.create(asset)
+
+            # Update job status to FAILED
+            job.status = IngestJobStatus.FAILED
+            job.error_message = f"Invalid media file: {error_reason}"
+            job.result_asset_id = asset.id
+            job.updated_at = datetime.now(timezone.utc)
+            job_repo.update(job)
+            db.commit()
+
+            return {
+                "status": "failed",
+                "job_id": job.id,
+                "asset_id": asset.id,
+                "error": error_reason,
             }
 
         # Create Asset
@@ -175,6 +335,7 @@ def ingest_asset(job_id: str) -> dict:
             duration=float(metadata.get("duration", 0)),
             width=int(metadata.get("width", 0)),
             height=int(metadata.get("height", 0)),
+            codec=metadata.get("codec") or None,
             status=AssetStatus.READY,
             file_hash=job.file_hash,
         )

apps/worker/worker_app/tasks/voice_extraction.py

@@ -2,7 +2,6 @@
 
 import logging
 import os
-import subprocess
 import tempfile
 
 from celery import Task

docs/schema-metadata-snapshot.json

@@ -186,6 +186,14 @@
           "type": "VARCHAR(1000)",
           "unique": false
         },
+        {
+          "index": false,
+          "name": "storage_key",
+          "nullable": false,
+          "primary_key": false,
+          "type": "VARCHAR(500)",
+          "unique": false
+        },
         {
           "index": false,
           "name": "thumbnail_url",

infra/docker/web.Dockerfile

@@ -3,12 +3,27 @@ FROM git.xiaoxiajianji.com/xiaoxia/base/node:20 AS builder
 WORKDIR /app
 ARG VITE_API_URL=https://saas-api.xiaoxiajianji.com
 ENV VITE_API_URL=$VITE_API_URL
+
+# 先拷依赖清单（缓存友好：依赖不变时直接命中缓存层）
 COPY apps/web/package.json apps/web/package-lock.json ./apps/web/
 WORKDIR /app/apps/web
-RUN npm config set registry https://registry.npmmirror.com \
+
+# 安装依赖：用BuildKit cache mount缓存npm下载和node_modules
+# sharing=locked 防止并发构建竞争写缓存
+RUN --mount=type=cache,target=/root/.npm,sharing=locked \
+    --mount=type=cache,target=/app/apps/web/node_modules,sharing=locked \
+    npm config set registry https://registry.npmmirror.com \
     && npm ci
+
+# 再拷源码
 COPY apps/web/ ./
-RUN npm run build
+
+# 构建：TS增量编译 + Vite构建，tsbuildinfo用cache mount持久化
+RUN --mount=type=cache,target=/app/apps/web/node_modules,sharing=locked \
+    --mount=type=cache,target=/app/apps/web/.tscache,sharing=locked \
+    mkdir -p .tscache \
+    && npx tsc --incremental --tsBuildInfoFile .tscache/tsconfig.tsbuildinfo \
+    && npx vite build
 
 # Production stage with nginx
 FROM git.xiaoxiajianji.com/xiaoxia/base/nginx:alpine AS runner

packages/adapters/sqlalchemy_impl/asset_repository.py

@@ -72,6 +72,7 @@ class SQLAlchemyAssetRepository:
             file_type=(asset.mime_type.split("/")[0] if "/" in asset.mime_type else asset.mime_type),
             file_size=asset.file_size,
             file_url=asset.storage_key,
+            storage_key=asset.storage_key,
             thumbnail_url=asset.thumbnail_url,
             duration=asset.duration,
             width=asset.width,
@@ -100,6 +101,7 @@ class SQLAlchemyAssetRepository:
         model.name = asset.name
         model.file_size = asset.file_size
         model.file_url = asset.storage_key
+        model.storage_key = asset.storage_key
         model.thumbnail_url = asset.thumbnail_url
         model.duration = asset.duration
         model.width = asset.width
@@ -299,7 +301,7 @@ class SQLAlchemyAssetRepository:
             project_id=model.project_id,
             library_id=model.asset_library_id,
             name=model.name,
-            storage_key=model.file_url,
+            storage_key=model.storage_key or model.file_url,
             mime_type=mime_type,
             file_size=int(model.file_size or 0),
             thumbnail_url=model.thumbnail_url,

packages/adapters/sqlalchemy_impl/models.py

@@ -75,6 +75,8 @@ class AssetModel(Base):
     file_size = Column(Integer, nullable=False)
     # file_url: 完整可访问的 URL，用于客户端直接访问文件
     file_url = Column(String(1000), nullable=False)
+    # storage_key: OSS 存储键，用于内部下载上传
+    storage_key = Column(String(500), nullable=False, default="", server_default="")
     thumbnail_url = Column(String(1000), nullable=True)
     duration = Column(Float, nullable=True)
     width = Column(Float, nullable=True)

packages/adapters/sqlalchemy_impl/template_repository.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 import uuid
 from typing import List, Optional
 
-from sqlalchemy import func
 from sqlalchemy.orm import Session
 
 from packages.adapters.sqlalchemy_impl.models import (

packages/adapters/tts/mock_tts_service.py

@@ -161,7 +161,6 @@ class MockTtsService(TtsService):
         tremolo_depth = 0.3  # 30% 深度
 
         # 构建滤镜链
-        filters: list[str] = []
 
         # 生成基频 + 泛音（让声音更丰富）
         # 用多个 sine 波叠加模拟更自然的音色

packages/application/tts_job/streaming_service.py

@@ -11,8 +11,6 @@ import asyncio
 import logging
 from typing import Any, Optional
 
-import httpx
-
 from packages.application.cosyvoice_service import CosyVoiceError, CosyVoiceService
 from packages.application.tts_job.text_splitter import split_text
 from packages.shared.url_security import ALLOWED_AUDIO_MIME_TYPES, safe_download_bytes

packages/application/tts_job/workflow.py

@@ -17,8 +17,6 @@ import tempfile
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from typing import Optional
 
-import httpx
-
 from packages.application.cosyvoice_service import CosyVoiceAuthError, CosyVoiceError, CosyVoiceService
 from packages.application.tts_job.audio_merger import AudioMerger
 from packages.application.tts_job.text_splitter import split_text
@@ -27,10 +25,8 @@ from packages.ports.tts_job_repository import TTSJobRepository
 from packages.shared.storage import SharedStorageService, get_shared_storage_service
 from packages.shared.url_security import (
     ALLOWED_AUDIO_MIME_TYPES,
-    UrlSecurityError,
     safe_download_bytes,
     safe_download_file,
-    validate_url_safety,
 )
 
 logger = logging.getLogger(__name__)

packages/domain/config_schemas.py

@@ -140,6 +140,42 @@ class BGMConfig(BaseModel):
     sidechain_threshold: float = Field(default=-25.0, ge=-60.0, le=0.0, description="人声闪避触发阈值（dB）")
 
 
+class ExportConfig(BaseModel):
+    """导出配置
+
+    视频输出参数设置。
+    """
+
+    resolution: str = Field(default="1080x1920", description="输出分辨率，如 1080x1920 / 720x1280 / 2160x3840")
+    fps: int = Field(default=30, ge=15, le=60, description="输出帧率 15~60")
+    video_bitrate: int = Field(default=8000, ge=1000, le=20000, description="视频码率（kbps）")
+    audio_bitrate: int = Field(default=128, ge=64, le=320, description="音频码率（kbps）")
+    format: str = Field(default="mp4", description="输出格式：mp4 / mov")
+    quality_preset: str = Field(
+        default="balanced",
+        description="质量预设：ultra_fast / fast / balanced / high / best",
+    )
+    watermark_enabled: bool = Field(default=False, description="是否启用水印")
+    watermark_text: str = Field(default="", description="水印文字")
+
+
+class FilterConfig(BaseModel):
+    """滤镜调色配置
+
+    支持全局滤镜和按片段覆盖。
+    强度 0-100，0 表示不应用，100 表示全量应用预设。
+    """
+
+    enabled: bool = Field(default=False, description="是否启用滤镜")
+    preset_id: str = Field(default="filter_none", description="滤镜预设 ID")
+    intensity: int = Field(default=100, ge=0, le=100, description="滤镜强度 0-100")
+    # 自定义微调参数（在预设基础上叠加调整）
+    brightness: float = Field(default=0.0, ge=-1.0, le=1.0, description="亮度微调")
+    contrast: float = Field(default=1.0, ge=0.0, le=2.0, description="对比度微调（倍率）")
+    saturation: float = Field(default=1.0, ge=0.0, le=3.0, description="饱和度微调（倍率）")
+    warmth: float = Field(default=0.0, ge=-1.0, le=1.0, description="色温微调（正=暖，负=冷）")
+
+
 # ── 完整 config 模型 ─────────────────────────────────────────────────────────
 
 
@@ -155,6 +191,8 @@ class EditPlanConfigSchema(BaseModel):
     title: TitleConfig = Field(default_factory=TitleConfig, description="标题配置")
     subtitle: SubtitleConfig = Field(default_factory=SubtitleConfig, description="字幕配置")
     bgm: BGMConfig = Field(default_factory=BGMConfig, description="BGM 配置")
+    export: ExportConfig = Field(default_factory=ExportConfig, description="导出配置")
+    filter: FilterConfig = Field(default_factory=FilterConfig, description="滤镜调色配置")
     editing_mode: str = Field(default="one_take", description="剪辑模式")
 
 
@@ -169,6 +207,8 @@ class EditTemplateConfigSchema(BaseModel):
     title: TitleConfig = Field(default_factory=TitleConfig, description="标题默认配置")
     subtitle: SubtitleConfig = Field(default_factory=SubtitleConfig, description="字幕默认配置")
     bgm: BGMConfig = Field(default_factory=BGMConfig, description="BGM 默认配置")
+    export: ExportConfig = Field(default_factory=ExportConfig, description="导出默认配置")
+    filter: FilterConfig = Field(default_factory=FilterConfig, description="滤镜默认配置")
     editing_mode: str = Field(default="one_take", description="剪辑模式")
     transition_enabled: bool = Field(default=True, description="是否启用转场")
 
@@ -218,6 +258,25 @@ DEFAULT_EDIT_PLAN_CONFIG: dict = {
         "sidechain_release": 0.5,
         "sidechain_threshold": -25.0,
     },
+    "export": {
+        "resolution": "1080x1920",
+        "fps": 30,
+        "video_bitrate": 8000,
+        "audio_bitrate": 128,
+        "format": "mp4",
+        "quality_preset": "balanced",
+        "watermark_enabled": False,
+        "watermark_text": "",
+    },
+    "filter": {
+        "enabled": False,
+        "preset_id": "filter_none",
+        "intensity": 100,
+        "brightness": 0.0,
+        "contrast": 1.0,
+        "saturation": 1.0,
+        "warmth": 0.0,
+    },
     "editing_mode": "one_take",
 }
 

packages/domain/filter_presets.py

@@ -0,0 +1,357 @@
+"""滤镜预设库 — 视频调色滤镜预设清单.
+
+每个滤镜预设对应一组 FFmpeg 滤镜参数，用于视频调色。
+所有参数均可调整强度（0-100），0表示原图，100表示全量应用。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass(frozen=True)
+class FilterPreset:
+    """滤镜预设条目"""
+
+    id: str
+    name: str
+    category: str  # 分类：basic / cinematic / vintage / bw / style
+    description: str = ""
+    tags: List[str] = field(default_factory=list)
+    # FFmpeg eq 滤镜参数（基准值，实际应用时乘以强度系数）
+    brightness: float = 0.0  # -1.0 ~ 1.0
+    contrast: float = 1.0  # 0.0 ~ 2.0，1.0为原值
+    saturation: float = 1.0  # 0.0 ~ 3.0，1.0为原值
+    gamma: float = 1.0  # 0.1 ~ 10.0，1.0为原值
+    gamma_r: float = 1.0  # 红通道伽马
+    gamma_g: float = 1.0  # 绿通道伽马
+    gamma_b: float = 1.0  # 蓝通道伽马
+    hue: float = 0.0  # 色相偏移 -180 ~ 180度
+    # 可选的颜色查找表 LUT（后续扩展）
+    lut_url: str = ""
+
+
+# ── 预设库清单 ────────────────────────────────────────────────────────────────
+
+FILTER_PRESET_LIBRARY: List[FilterPreset] = [
+    # ── 基础 basic ─────────────────────────────────────────────────────
+    FilterPreset(
+        id="filter_none",
+        name="原图",
+        category="basic",
+        description="不应用任何滤镜，保持原始画面",
+        tags=["原图", "无"],
+    ),
+    FilterPreset(
+        id="filter_brighten",
+        name="明亮",
+        category="basic",
+        description="提升画面亮度，适合偏暗的素材",
+        tags=["提亮", "基础"],
+        brightness=0.12,
+        contrast=1.05,
+        saturation=1.05,
+        gamma=1.1,
+    ),
+    FilterPreset(
+        id="filter_warm",
+        name="暖色",
+        category="basic",
+        description="暖色调，增加温暖感",
+        tags=["暖色", "温馨"],
+        gamma_r=1.1,
+        gamma_g=1.02,
+        gamma_b=0.9,
+        saturation=1.05,
+    ),
+    FilterPreset(
+        id="filter_cool",
+        name="冷色",
+        category="basic",
+        description="冷色调，清凉干净",
+        tags=["冷色", "清新"],
+        gamma_r=0.9,
+        gamma_g=1.0,
+        gamma_b=1.1,
+        saturation=1.02,
+    ),
+    FilterPreset(
+        id="filter_contrast",
+        name="高对比",
+        category="basic",
+        description="增强对比度，画面更通透",
+        tags=["对比", "通透"],
+        contrast=1.25,
+        saturation=1.1,
+        gamma=0.95,
+    ),
+    FilterPreset(
+        id="filter_saturate",
+        name="鲜艳",
+        category="basic",
+        description="提升饱和度，色彩更浓郁",
+        tags=["鲜艳", "浓郁"],
+        saturation=1.4,
+        contrast=1.05,
+    ),
+    # ── 电影感 cinematic ─────────────────────────────────────────────
+    FilterPreset(
+        id="filter_cinematic",
+        name="电影感",
+        category="cinematic",
+        description="经典电影色调，青橙对比",
+        tags=["电影", "青橙", "质感"],
+        contrast=1.2,
+        saturation=0.9,
+        gamma_r=1.15,
+        gamma_g=0.95,
+        gamma_b=0.85,
+        brightness=-0.03,
+    ),
+    FilterPreset(
+        id="filter_teal_orange",
+        name="青橙色调",
+        category="cinematic",
+        description="好莱坞经典青橙对比色",
+        tags=["青橙", "好莱坞", "对比"],
+        contrast=1.15,
+        saturation=1.1,
+        gamma_r=1.2,
+        gamma_g=0.9,
+        gamma_b=0.8,
+    ),
+    # ── 复古 vintage ─────────────────────────────────────────────────
+    FilterPreset(
+        id="filter_vintage",
+        name="复古",
+        category="vintage",
+        description="复古胶片色调，怀旧感",
+        tags=["复古", "怀旧", "胶片"],
+        saturation=0.8,
+        contrast=0.9,
+        gamma_r=1.1,
+        gamma_g=1.0,
+        gamma_b=0.85,
+        brightness=-0.02,
+    ),
+    FilterPreset(
+        id="filter_retro",
+        name="怀旧",
+        category="vintage",
+        description="80年代复古感",
+        tags=["怀旧", "80年代"],
+        saturation=0.75,
+        contrast=0.95,
+        gamma_r=1.2,
+        gamma_g=1.05,
+        gamma_b=0.9,
+    ),
+    FilterPreset(
+        id="filter_sepia",
+        name="棕褐色",
+        category="vintage",
+        description="老照片棕褐色调",
+        tags=["棕褐", "老照片", "复古"],
+        saturation=0.3,
+        gamma_r=1.3,
+        gamma_g=1.1,
+        gamma_b=0.8,
+        contrast=0.95,
+    ),
+    # ── 黑白 bw ──────────────────────────────────────────────────────
+    FilterPreset(
+        id="filter_bw",
+        name="黑白",
+        category="bw",
+        description="经典黑白",
+        tags=["黑白", "经典"],
+        saturation=0.0,
+        contrast=1.1,
+    ),
+    FilterPreset(
+        id="filter_bw_high",
+        name="高对比黑白",
+        category="bw",
+        description="高对比度黑白，戏剧感强",
+        tags=["黑白", "高对比", "戏剧"],
+        saturation=0.0,
+        contrast=1.4,
+        gamma=0.9,
+    ),
+    FilterPreset(
+        id="filter_bw_soft",
+        name="柔和黑白",
+        category="bw",
+        description="柔和灰度过渡，细腻质感",
+        tags=["黑白", "柔和", "细腻"],
+        saturation=0.0,
+        contrast=0.9,
+        gamma=1.1,
+    ),
+    # ── 风格化 style ────────────────────────────────────────────────
+    FilterPreset(
+        id="filter_japanese",
+        name="日系",
+        category="style",
+        description="日系清新，低对比高明度",
+        tags=["日系", "清新", "干净"],
+        contrast=0.85,
+        brightness=0.08,
+        saturation=0.85,
+        gamma_r=0.98,
+        gamma_g=1.02,
+        gamma_b=1.08,
+    ),
+    FilterPreset(
+        id="filter_hk",
+        name="港风",
+        category="style",
+        description="90年代港风，暖黄+高饱和",
+        tags=["港风", "复古", "浓郁"],
+        saturation=1.25,
+        contrast=1.1,
+        gamma_r=1.2,
+        gamma_g=1.05,
+        gamma_b=0.85,
+        brightness=-0.02,
+    ),
+    FilterPreset(
+        id="filter_cyberpunk",
+        name="赛博朋克",
+        category="style",
+        description="赛博朋克风，青紫霓虹",
+        tags=["赛博", "霓虹", "未来感"],
+        contrast=1.2,
+        saturation=1.3,
+        gamma_r=1.3,
+        gamma_g=0.7,
+        gamma_b=1.2,
+        brightness=-0.05,
+    ),
+    FilterPreset(
+        id="filter_fresh",
+        name="清新",
+        category="style",
+        description="清新自然，通透干净",
+        tags=["清新", "自然", "通透"],
+        brightness=0.05,
+        saturation=1.05,
+        contrast=1.05,
+        gamma_g=1.03,
+        gamma_b=1.05,
+    ),
+    FilterPreset(
+        id="filter_dramatic",
+        name="戏剧感",
+        category="style",
+        description="强对比暗角，戏剧化氛围",
+        tags=["戏剧", "暗角", "氛围"],
+        contrast=1.35,
+        saturation=0.9,
+        brightness=-0.08,
+        gamma=0.85,
+    ),
+    FilterPreset(
+        id="filter_dreamy",
+        name="梦幻",
+        category="style",
+        description="柔光梦幻感，低对比",
+        tags=["梦幻", "柔光", "唯美"],
+        contrast=0.8,
+        brightness=0.1,
+        saturation=1.1,
+        gamma=1.15,
+    ),
+]
+
+
+# ── 工具函数 ──────────────────────────────────────────────────────────────────
+
+
+def get_filter_preset(preset_id: str) -> Optional[FilterPreset]:
+    """根据 ID 获取滤镜预设"""
+    for p in FILTER_PRESET_LIBRARY:
+        if p.id == preset_id:
+            return p
+    return None
+
+
+def list_filter_presets(
+    *,
+    category: Optional[str] = None,
+    keyword: Optional[str] = None,
+) -> List[FilterPreset]:
+    """筛选滤镜预设列表
+
+    Args:
+        category: 按分类筛选
+        keyword: 关键词搜索（名称/标签/描述）
+
+    Returns:
+        筛选后的预设列表
+    """
+    results = FILTER_PRESET_LIBRARY
+
+    if category:
+        results = [p for p in results if p.category == category]
+
+    if keyword:
+        kw = keyword.lower()
+        results = [
+            p
+            for p in results
+            if kw in p.name.lower() or kw in p.description.lower() or any(kw in t.lower() for t in p.tags)
+        ]
+
+    return results
+
+
+def build_ffmpeg_filter(preset_id: str, intensity: int = 100) -> str:
+    """根据预设和强度生成 FFmpeg eq 滤镜字符串.
+
+    Args:
+        preset_id: 滤镜预设 ID
+        intensity: 强度 0-100，0=原图，100=全量
+
+    Returns:
+        FFmpeg eq 滤镜参数字符串
+    """
+    preset = get_filter_preset(preset_id)
+    if preset is None or intensity <= 0:
+        return ""
+
+    if intensity >= 100:
+        intensity = 100
+
+    factor = intensity / 100.0
+
+    # 计算插值后的参数（向原值插值）
+    brightness = preset.brightness * factor
+    contrast = 1.0 + (preset.contrast - 1.0) * factor
+    saturation = 1.0 + (preset.saturation - 1.0) * factor
+    gamma = 1.0 + (preset.gamma - 1.0) * factor
+    gamma_r = 1.0 + (preset.gamma_r - 1.0) * factor
+    gamma_g = 1.0 + (preset.gamma_g - 1.0) * factor
+    gamma_b = 1.0 + (preset.gamma_b - 1.0) * factor
+
+    parts = []
+    if abs(brightness) > 0.001:
+        parts.append(f"brightness={brightness:.3f}")
+    if abs(contrast - 1.0) > 0.001:
+        parts.append(f"contrast={contrast:.3f}")
+    if abs(saturation - 1.0) > 0.001:
+        parts.append(f"saturation={saturation:.3f}")
+    if abs(gamma - 1.0) > 0.001:
+        parts.append(f"gamma={gamma:.3f}")
+    if abs(gamma_r - 1.0) > 0.001:
+        parts.append(f"gamma_r={gamma_r:.3f}")
+    if abs(gamma_g - 1.0) > 0.001:
+        parts.append(f"gamma_g={gamma_g:.3f}")
+    if abs(gamma_b - 1.0) > 0.001:
+        parts.append(f"gamma_b={gamma_b:.3f}")
+
+    if not parts:
+        return ""
+
+    return f"eq={':'.join(parts)}"

packages/domain/transition_presets.py

@@ -0,0 +1,306 @@
+"""转场特效预设库.
+
+视频片段之间的转场效果，基于 FFmpeg xfade 滤镜实现。
+所有转场预设包含时长范围和默认参数。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass(frozen=True)
+class TransitionPreset:
+    """转场特效预设"""
+
+    id: str
+    name: str
+    category: str  # 分类：basic / fade / slide / zoom / warp / special
+    description: str = ""
+    tags: List[str] = field(default_factory=list)
+    # FFmpeg xfade transition 名称
+    transition: str = "fade"
+    # 默认时长（秒）
+    default_duration: float = 0.5
+    # 支持的时长范围
+    min_duration: float = 0.1
+    max_duration: float = 3.0
+    # 是否需要额外参数
+    has_custom_params: bool = False
+
+
+# ── 预设库清单 ────────────────────────────────────────────────────────────────
+
+TRANSITION_PRESET_LIBRARY: List[TransitionPreset] = [
+    # ── 基础 basic ────────────────────────────────────────────────────
+    TransitionPreset(
+        id="transition_none",
+        name="无转场",
+        category="basic",
+        description="硬切，无过渡效果",
+        tags=["硬切", "无"],
+        transition="none",
+        default_duration=0.0,
+        min_duration=0.0,
+        max_duration=0.0,
+    ),
+    TransitionPreset(
+        id="transition_random",
+        name="随机",
+        category="basic",
+        description="随机选择一个转场效果",
+        tags=["随机", "惊喜"],
+        transition="random",
+        default_duration=0.5,
+    ),
+    # ── 淡入淡出 fade ────────────────────────────────────────────────
+    TransitionPreset(
+        id="transition_fade",
+        name="淡入淡出",
+        category="fade",
+        description="经典交叉淡入淡出",
+        tags=["经典", "柔和"],
+        transition="fade",
+        default_duration=0.5,
+        min_duration=0.2,
+        max_duration=2.0,
+    ),
+    TransitionPreset(
+        id="transition_fadeblack",
+        name="黑场过渡",
+        category="fade",
+        description="经过黑色画面过渡",
+        tags=["黑场", "电影感"],
+        transition="fadeblack",
+        default_duration=0.6,
+        min_duration=0.2,
+        max_duration=2.0,
+    ),
+    TransitionPreset(
+        id="transition_fadewhite",
+        name="白场过渡",
+        category="fade",
+        description="经过白色画面过渡",
+        tags=["白场", "梦幻"],
+        transition="fadewhite",
+        default_duration=0.6,
+        min_duration=0.2,
+        max_duration=2.0,
+    ),
+    TransitionPreset(
+        id="transition_fadegrays",
+        name="灰度过渡",
+        category="fade",
+        description="经过灰度画面过渡",
+        tags=["灰度", "文艺"],
+        transition="fadegrays",
+        default_duration=0.6,
+        min_duration=0.2,
+        max_duration=2.0,
+    ),
+    # ── 滑动 slide ──────────────────────────────────────────────────
+    TransitionPreset(
+        id="transition_slideleft",
+        name="左滑",
+        category="slide",
+        description="画面向左滑动",
+        tags=["滑动", "左"],
+        transition="slideleft",
+        default_duration=0.5,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+    TransitionPreset(
+        id="transition_slideright",
+        name="右滑",
+        category="slide",
+        description="画面向右滑动",
+        tags=["滑动", "右"],
+        transition="slideright",
+        default_duration=0.5,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+    TransitionPreset(
+        id="transition_slideup",
+        name="上滑",
+        category="slide",
+        description="画面向上滑动",
+        tags=["滑动", "上"],
+        transition="slideup",
+        default_duration=0.5,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+    TransitionPreset(
+        id="transition_slidedown",
+        name="下滑",
+        category="slide",
+        description="画面向下滑动",
+        tags=["滑动", "下"],
+        transition="slidedown",
+        default_duration=0.5,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+    # ── 缩放 zoom ───────────────────────────────────────────────────
+    TransitionPreset(
+        id="transition_zoomin",
+        name="放大进入",
+        category="zoom",
+        description="下一段画面从中心放大出现",
+        tags=["放大", "冲击"],
+        transition="zoomin",
+        default_duration=0.5,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+    TransitionPreset(
+        id="transition_zoomout",
+        name="缩小退出",
+        category="zoom",
+        description="当前画面缩小退出",
+        tags=["缩小", "拉远"],
+        transition="zoomout",
+        default_duration=0.5,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+    # ── 擦除 warp ───────────────────────────────────────────────────
+    TransitionPreset(
+        id="transition_dissolve",
+        name="溶解",
+        category="warp",
+        description="像素溶解效果",
+        tags=["溶解", "像素"],
+        transition="dissolve",
+        default_duration=0.8,
+        min_duration=0.3,
+        max_duration=2.0,
+    ),
+    TransitionPreset(
+        id="transition_wipeleft",
+        name="左擦除",
+        category="warp",
+        description="从右向左擦除",
+        tags=["擦除", "左"],
+        transition="wipeleft",
+        default_duration=0.5,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+    TransitionPreset(
+        id="transition_wiperight",
+        name="右擦除",
+        category="warp",
+        description="从左向右擦除",
+        tags=["擦除", "右"],
+        transition="wiperight",
+        default_duration=0.5,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+    TransitionPreset(
+        id="transition_wipeup",
+        name="上擦除",
+        category="warp",
+        description="从下向上擦除",
+        tags=["擦除", "上"],
+        transition="wipeup",
+        default_duration=0.5,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+    TransitionPreset(
+        id="transition_wipedown",
+        name="下擦除",
+        category="warp",
+        description="从上向下擦除",
+        tags=["擦除", "下"],
+        transition="wipedown",
+        default_duration=0.5,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+    TransitionPreset(
+        id="transition_circlecrop",
+        name="圆形展开",
+        category="warp",
+        description="圆形从中心展开",
+        tags=["圆形", "展开"],
+        transition="circlecrop",
+        default_duration=0.6,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+    # ── 特效 special ───────────────────────────────────────────────
+    TransitionPreset(
+        id="transition_hblur",
+        name="水平模糊",
+        category="special",
+        description="水平方向模糊过渡",
+        tags=["模糊", "水平"],
+        transition="hblur",
+        default_duration=0.5,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+    TransitionPreset(
+        id="transition_wipeblur",
+        name="模糊擦除",
+        category="special",
+        description="带模糊效果的擦除",
+        tags=["模糊", "擦除"],
+        transition="wipeblur",
+        default_duration=0.6,
+        min_duration=0.2,
+        max_duration=1.5,
+    ),
+]
+
+
+# ── 工具函数 ──────────────────────────────────────────────────────────────────
+
+
+def get_transition_preset(preset_id: str) -> Optional[TransitionPreset]:
+    """根据 ID 获取转场预设"""
+    for p in TRANSITION_PRESET_LIBRARY:
+        if p.id == preset_id:
+            return p
+    return None
+
+
+def list_transition_presets(
+    *,
+    category: Optional[str] = None,
+    keyword: Optional[str] = None,
+) -> List[TransitionPreset]:
+    """筛选转场预设列表
+
+    Args:
+        category: 按分类筛选
+        keyword: 关键词搜索
+
+    Returns:
+        筛选后的预设列表
+    """
+    results = TRANSITION_PRESET_LIBRARY
+
+    if category:
+        results = [p for p in results if p.category == category]
+
+    if keyword:
+        kw = keyword.lower()
+        results = [
+            p
+            for p in results
+            if kw in p.name.lower() or kw in p.description.lower() or any(kw in t.lower() for t in p.tags)
+        ]
+
+    return results
+
+
+def get_default_transition() -> TransitionPreset:
+    """获取默认转场（无转场/硬切）"""
+    return get_transition_preset("transition_none")  # type: ignore

packages/domain/tts_config.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import Any, Optional
 
 

packages/shared/ffmpeg_utils.py

@@ -11,8 +11,6 @@ from __future__ import annotations
 import logging
 import shutil
 import subprocess  # nosec B404
-from pathlib import Path
-from typing import Any
 
 logger = logging.getLogger(__name__)
 

pyproject.toml

@@ -89,10 +89,8 @@ ignore = [
   "W291",
   "W293",
   "B008",  # function-call-in-default-argument（FastAPI 依赖注入模式，大量使用）
-  "F401",  # unused-import
   "F403",
   "F405",
-  "F841",  # unused-variable
 ]
 
 [tool.ruff.lint.per-file-ignores]

requirements-dev.txt

@@ -11,3 +11,4 @@ pytest==8.3.3
 pytest-asyncio==0.24.0
 pytest-cov==6.0.0
 pytest-timeout==2.3.1
+diff-cover>=8.0

scripts/auto_merge_prs.sh

@@ -1,108 +0,0 @@
-#!/bin/bash
-# 自动合并通过 CI 检查的 PR
-# 用法: ./scripts/auto_merge_prs.sh [target_branch]
-#
-# 合并前必须验证的 CI 检查项：
-#   - CI/CD Pipeline / Validate Code Quality And Tests (push)
-#   - CI/CD Pipeline / Frontend Lint (push)
-# 只有两个检查项均为 success 状态才允许合并
-
-GITEA_API="${GITEA_API_URL:-https://git.xiaoxiajianji.com/api/v1}"
-TOKEN="${GITEA_API_TOKEN:?Please set GITEA_API_TOKEN environment variable}"
-REPO="xiaoxia/xiaoxia-saas"
-TARGET_BRANCH="${1:-develop}"
-
-# 必需的 CI 检查项（context 名称前缀匹配，避免 pipeline 名称变化导致匹配失败）
-REQUIRED_CHECKS=(
-  "Validate Code Quality And Tests"
-  "Frontend Lint"
-)
-
-echo "=== Checking open PRs targeting $TARGET_BRANCH ==="
-
-# 获取所有 open PR
-PRS=$(curl -s -H "Authorization: token $TOKEN" \
-  "$GITEA_API/repos/$REPO/pulls?state=open&sort=updated&direction=desc" | python3 -c "
-import json, sys
-data = json.load(sys.stdin)
-for pr in data:
-    if pr.get('base', {}).get('ref') == '$TARGET_BRANCH':
-        head_sha = pr.get('head', {}).get('sha', '')
-        print(f\"{pr['number']}|{pr['title']}|{head_sha}\")
-")
-
-if [ -z "$PRS" ]; then
-    echo "No open PRs found for $TARGET_BRANCH"
-    exit 0
-fi
-
-merge_count=0
-skip_count=0
-
-echo "$PRS" | while IFS='|' read -r number title head_sha; do
-    echo ""
-    echo "--- PR #$number: $title ---"
-    echo "  Head SHA: $head_sha"
-
-    # 获取该 commit 的 combined CI 状态
-    STATUS_JSON=$(curl -s -H "Authorization: token $TOKEN" \
-      "$GITEA_API/repos/$REPO/commits/$head_sha/status")
-
-    # 检查每个必需的 CI 项是否通过
-    all_passed=true
-    failed_checks=""
-
-    for check_pattern in "${REQUIRED_CHECKS[@]}"; do
-        state=$(echo "$STATUS_JSON" | python3 -c "
-import json, sys
-d = json.load(sys.stdin)
-pattern = '$check_pattern'
-# 在 statuses 中找到匹配的最新状态
-target = None
-for s in d.get('statuses', []):
-    if pattern in s.get('context', ''):
-        target = s
-        break  # status 接口返回的是每个 context 的最新状态，取第一个匹配即可
-if target:
-    print(target.get('state', 'unknown'))
-else:
-    print('not_found')
-")
-
-        if [ "$state" = "success" ]; then
-            echo "  ✅ $check_pattern: $state"
-        else
-            echo "  ❌ $check_pattern: $state"
-            all_passed=false
-            failed_checks="$failed_checks $check_pattern($state)"
-        fi
-    done
-
-    if [ "$all_passed" != "true" ]; then
-        echo "  ⏭️  Skipping - CI not passed:$failed_checks"
-        skip_count=$((skip_count + 1))
-        continue
-    fi
-
-    # CI 全部通过，执行合并
-    echo "  🚀 All CI checks passed, merging..."
-    RESULT=$(curl -s -X POST \
-      -H "Authorization: token $TOKEN" \
-      -H "Content-Type: application/json" \
-      "$GITEA_API/repos/$REPO/pulls/$number/merge" \
-      -d '{"Do": "merge"}')
-
-    if echo "$RESULT" | python3 -c "import json,sys; d=json.load(sys.stdin); sys.exit(0 if d.get('merged', False) or 'id' in d else 1)" 2>/dev/null; then
-        echo "  ✅ PR #$number merged successfully"
-        merge_count=$((merge_count + 1))
-    else
-        echo "  ❌ PR #$number merge failed"
-        # 提取错误信息
-        err_msg=$(echo "$RESULT" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('message', str(d)[:200]))" 2>/dev/null)
-        echo "     Error: $err_msg"
-    fi
-done
-
-echo ""
-echo "=== Done ==="
-echo "Merged: $merge_count | Skipped: $skip_count"

scripts/check_ci_status.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""检查指定commit的CI status状态。
+
+用法: python3 check_ci_status.py <token> <repo> <sha> <context>
+返回: 打印状态 (success/failure/pending/error)
+"""
+
+import json
+import sys
+import urllib.error
+import urllib.request
+
+
+def main():
+    if len(sys.argv) != 5:
+        print("pending")
+        return
+
+    token = sys.argv[1]
+    repo = sys.argv[2]
+    sha = sys.argv[3]
+    target_context = sys.argv[4]
+
+    api_url = f"https://git.xiaoxiajianji.com/api/v1/repos/{repo}/commits/{sha}/statuses?per_page=100"
+    req = urllib.request.Request(api_url, headers={"Authorization": f"token {token}"})
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            statuses = json.loads(resp.read().decode())
+    except Exception:
+        print("pending")
+        return
+
+    # API返回按时间倒序，第一个就是最新的
+    for s in statuses:
+        if s.get("context") == target_context:
+            status = s.get("status", "pending")
+            # skipped 视为通过（条件跳过的任务不需要等）
+            if status == "skipped":
+                print("success")
+            else:
+                print(status)
+            return
+
+    # 找不到这个context说明CI还没开始写状态，返回pending继续等待
+    # （如果workflow真的被跳过，它会有一条status为skipped的记录）
+    print("pending")
+
+
+if __name__ == "__main__":
+    main()

scripts/check_pr_approval.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""检查PR是否有至少N个APPROVED审批。
+
+用法: python3 check_pr_approval.py <token> <repo> <pr_number> <min_approval>
+返回: 打印 "approved" 或 "pending"
+"""
+
+import json
+import sys
+import urllib.request
+
+
+def main():
+    if len(sys.argv) != 5:
+        print("pending")
+        return
+
+    token = sys.argv[1]
+    repo = sys.argv[2]
+    pr_number = sys.argv[3]
+    min_approval = int(sys.argv[4])
+
+    api_url = f"https://git.xiaoxiajianji.com/api/v1/repos/{repo}/pulls/{pr_number}/reviews"
+    req = urllib.request.Request(api_url, headers={"Authorization": f"token {token}"})
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            reviews = json.loads(resp.read().decode())
+    except Exception:
+        print("pending")
+        return
+
+    # 统计APPROVED的人数（去重，同一人多次审批只算一次）
+    approvers = set()
+    for r in reviews:
+        if r.get("state") == "APPROVED":
+            approvers.add(r.get("user", {}).get("login", ""))
+
+    if len(approvers) >= min_approval:
+        print(f"approved ({len(approvers)})")
+    else:
+        print(f"pending ({len(approvers)})")
+
+
+if __name__ == "__main__":
+    main()

scripts/ci/auto_fix_formatting.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""CI中自动修复Python代码格式（black + isort），并推送回PR分支。
+
+只在PR事件中执行，避免直接修改主干。
+当code quality检查因格式问题失败时触发，自动修复后push回原分支。
+"""
+
+import json
+import os
+import subprocess
+import sys
+import urllib.request
+
+
+def run(cmd, check=True, capture=True):
+    """运行shell命令"""
+    result = subprocess.run(cmd, shell=True, capture_output=capture, text=True)
+    if check and result.returncode != 0:
+        print(f"命令失败: {cmd}", file=sys.stderr)
+        if result.stderr:
+            print(result.stderr, file=sys.stderr)
+        sys.exit(1)
+    return result
+
+
+def get_changed_py_files(pr_number, api_url, token):
+    """获取PR中变更的Python文件列表"""
+    url = f"{api_url}/pulls/{pr_number}/files?limit=100"
+    req = urllib.request.Request(url, headers={"Authorization": f"token {token}"})
+    with urllib.request.urlopen(req) as resp:
+        files = json.loads(resp.read())
+    return [f["filename"] for f in files if f["filename"].endswith(".py") and f["status"] != "removed"]
+
+
+def get_pr_head_branch(pr_number, api_url, token):
+    """获取PR的来源分支名"""
+    url = f"{api_url}/pulls/{pr_number}"
+    req = urllib.request.Request(url, headers={"Authorization": f"token {token}"})
+    with urllib.request.urlopen(req) as resp:
+        pr = json.loads(resp.read())
+    return pr["head"]["ref"]
+
+
+def main():
+    # 只在PR事件中执行
+    event_name = os.environ.get("GITHUB_EVENT_NAME", "")
+    if event_name != "pull_request":
+        print("非PR事件，跳过自动修复")
+        return
+
+    github_ref = os.environ.get("GITHUB_REF", "")
+    pr_number = github_ref.split("/")[2] if github_ref.startswith("refs/pull/") else ""
+    if not pr_number:
+        print("无法获取PR号，跳过自动修复")
+        return
+
+    api_url = os.environ.get("GITHUB_API_URL", "")
+    repo = os.environ.get("GITHUB_REPOSITORY", "")
+    token = os.environ.get("GITHUB_TOKEN", "")
+    scan_mode = os.environ.get("SCAN_MODE", "full")
+    changed_py_files = os.environ.get("CHANGED_PY_FILES", "")
+
+    if not token:
+        print("缺少GITHUB_TOKEN，无法推送修复", file=sys.stderr)
+        sys.exit(1)
+
+    print("=== 检测到代码格式问题，尝试自动修复 ===")
+    print(f"PR #{pr_number}")
+    print(f"扫描模式: {scan_mode}")
+
+    # 确定要修复的文件范围
+    if scan_mode == "incremental" and changed_py_files:
+        target_files = changed_py_files.split()
+        print(f"增量模式，修复 {len(target_files)} 个变更的Python文件")
+    else:
+        target_files = ["alembic", "apps", "packages", "tests", "scripts"]
+        print("全量模式，修复所有Python文件")
+
+    # 自动修复
+    target_str = " ".join(target_files)
+    print()
+    print("--- black 格式化 ---")
+    result = run(f"python3 -m black {target_str}", check=False)
+    print(result.stdout[-500:] if result.stdout else "")
+    if result.returncode != 0:
+        print("black执行失败，但继续尝试isort", file=sys.stderr)
+
+    print()
+    print("--- isort 排序 ---")
+    result = run(f"python3 -m isort {target_str}", check=False)
+    print(result.stdout[-500:] if result.stdout else "")
+    if result.returncode != 0:
+        print("isort执行失败", file=sys.stderr)
+
+    # 检查是否有改动
+    result = run("git status --porcelain")
+    if not result.stdout.strip():
+        print()
+        print("没有需要提交的格式改动")
+        return
+
+    print()
+    print("变更文件:")
+    for line in result.stdout.strip().split("\n"):
+        print(f"  {line}")
+
+    # 配置git
+    run('git config user.name "CI Bot"')
+    run('git config user.email "ci-bot@xiaoxiajianji.com"')
+
+    # 提交修复
+    run("git add -A")
+    run('git commit -m "style: auto-format with black + isort [ci skip]"')
+
+    # 获取来源分支并推送
+    head_branch = get_pr_head_branch(pr_number, f"{api_url}/repos/{repo}", token)
+    print(f"\nPR来源分支: {head_branch}")
+
+    run(f'git push origin "HEAD:{head_branch}"')
+
+    print()
+    print("✅ 格式已自动修复并推送回分支")
+    print("新的commit会重新触发CI检查")
+
+
+if __name__ == "__main__":
+    main()

scripts/ci/preview_comment.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""生成预览环境PR评论内容"""
+
+import json
+import os
+import sys
+
+
+def generate_deploy_comment(pr_number, preview_url):
+    """生成部署成功的评论内容"""
+    return f"""🚀 **预览环境已部署**
+
+| 项目 | 详情 |
+|------|------|
+| PR号 | #{pr_number} |
+| 预览链接 | [{preview_url}]({preview_url}) |
+| API环境 | staging |
+
+> 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。
+>
+> 🔄 每次提交新代码后预览环境会自动更新。
+>
+> 🗑️ PR 关闭或合并后，预览环境会自动清理。
+"""
+
+
+def generate_cleanup_comment(pr_number):
+    """生成清理完成的评论内容"""
+    return f"""🗑️ **预览环境已清理**
+
+PR #{pr_number} 已关闭或合并，对应的预览环境已被清理。
+
+> 如有需要，可以重新打开 PR 来重新生成预览环境。
+"""
+
+
+def main():
+    mode = sys.argv[1] if len(sys.argv) > 1 else "deploy"
+    pr_number = os.environ.get("PR_NUMBER", "")
+    preview_url = os.environ.get("PREVIEW_URL", "")
+
+    if mode == "deploy":
+        body = generate_deploy_comment(pr_number, preview_url)
+    elif mode == "cleanup":
+        body = generate_cleanup_comment(pr_number)
+    else:
+        print(f"Unknown mode: {mode}", file=sys.stderr)
+        sys.exit(1)
+
+    print(json.dumps({"body": body}))
+
+
+if __name__ == "__main__":
+    main()

scripts/ci/preview_init_server.sh

@@ -0,0 +1,264 @@
+#!/bin/bash
+# ============================================================
+# 预览环境服务器初始化脚本
+# 用途：在业务服务器上创建预览环境所需的目录和配置
+# 使用方式：bash scripts/ci/preview_init_server.sh
+# ============================================================
+
+set -eu
+
+PREVIEW_ROOT="/var/www/preview"
+NGINX_CONF_PATH="/etc/nginx/conf.d/preview.conf"
+DOMAIN="xiaoxiajianji.com"
+STAGING_API="https://staging-api.xiaoxiajianji.com"
+
+echo "=========================================="
+echo "  预览环境服务器初始化"
+echo "=========================================="
+echo ""
+
+# 1. 创建预览根目录
+echo "[1/4] 创建预览根目录..."
+if [ -d "$PREVIEW_ROOT" ]; then
+  echo "  目录已存在: $PREVIEW_ROOT"
+else
+  mkdir -p "$PREVIEW_ROOT"
+  echo "  已创建: $PREVIEW_ROOT"
+fi
+chown -R root:root "$PREVIEW_ROOT"
+chmod -R 755 "$PREVIEW_ROOT"
+echo ""
+
+# 2. 创建测试页面（验证Nginx配置用）
+echo "[2/4] 创建测试页面..."
+TEST_DIR="${PREVIEW_ROOT}/pr-demo"
+mkdir -p "$TEST_DIR"
+cat > "$TEST_DIR/index.html" <<'EOF'
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>预览环境测试页</title>
+    <style>
+        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+               display: flex; align-items: center; justify-content: center;
+               min-height: 100vh; margin: 0; background: #f5f5f5; }
+        .card { background: white; padding: 40px; border-radius: 12px;
+                box-shadow: 0 4px 6px rgba(0,0,0,0.1); text-align: center; max-width: 400px; }
+        h1 { color: #2d3748; margin-top: 0; }
+        .success { color: #38a169; font-size: 48px; margin: 20px 0; }
+        p { color: #718096; line-height: 1.6; }
+        code { background: #edf2f7; padding: 2px 6px; border-radius: 4px; font-size: 0.9em; }
+    </style>
+</head>
+<body>
+    <div class="card">
+        <div class="success">✅</div>
+        <h1>预览环境配置成功！</h1>
+        <p>如果你能看到这个页面，说明 Nginx 预览环境配置正确。</p>
+        <p>当前站点通过子域名 <code>pr-demo.preview</code> 路由到 <code>/var/www/preview/pr-demo/</code> 目录。</p>
+    </div>
+</body>
+</html>
+EOF
+echo "  测试页面已创建: $TEST_DIR/index.html"
+echo ""
+
+# 3. 检查Nginx是否安装
+echo "[3/4] 检查Nginx环境..."
+if command -v nginx > /dev/null 2>&1; then
+  echo "  Nginx 已安装: $(nginx -v 2>&1)"
+  NGINX_INSTALLED=true
+else
+  echo "  ⚠️  Nginx 未安装，请先安装 Nginx"
+  NGINX_INSTALLED=false
+fi
+echo ""
+
+# 4. 输出Nginx配置建议
+echo "[4/4] Nginx 配置建议"
+echo ""
+echo "----------------------------------------"
+echo "  请将以下配置保存到: $NGINX_CONF_PATH"
+echo "  或复制到 Nginx 配置目录中"
+echo "----------------------------------------"
+echo ""
+
+cat <<'NGINX_CONF'
+# ============================================================
+# 预览环境 Nginx 配置
+# 支持 *.preview.xiaoxiajianji.com 通配符子域名
+# ============================================================
+
+# 从子域名中提取 PR 号（如 pr-123.preview -> pr-123）
+map $host $preview_pr {
+    default "";
+    ~^(?<pr>pr-\d+)\.preview\.xiaoxiajianji\.com$ $pr;
+}
+
+# HTTP 服务器（80端口）
+server {
+    listen 80;
+    server_name *.preview.xiaoxiajianji.com;
+
+    # 根目录根据子域名动态映射
+    root /var/www/preview/$preview_pr;
+
+    # 索引文件
+    index index.html;
+
+    # 字符集
+    charset utf-8;
+
+    # 访问日志
+    access_log /var/log/nginx/preview_access.log;
+    error_log /var/log/nginx/preview_error.log warn;
+
+    # 如果子域名格式不正确，返回404
+    if ($preview_pr = "") {
+        return 404;
+    }
+
+    # 如果预览目录不存在，返回404
+    if (!-d $document_root) {
+        return 404;
+    }
+
+    # API 反向代理到 staging 环境
+    location /api/ {
+        proxy_pass https://staging-api.xiaoxiajianji.com/api/;
+        proxy_http_version 1.1;
+        proxy_set_header Host staging-api.xiaoxiajianji.com;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host;
+
+        # 超时设置
+        proxy_connect_timeout 30s;
+        proxy_send_timeout 60s;
+        proxy_read_timeout 60s;
+
+        # 缓冲设置
+        proxy_buffering on;
+        proxy_buffer_size 4k;
+        proxy_buffers 8 4k;
+
+        # WebSocket 支持（如需要）
+        # proxy_set_header Upgrade $http_upgrade;
+        # proxy_set_header Connection "upgrade";
+    }
+
+    # 静态资源缓存
+    location /assets/ {
+        expires 7d;
+        add_header Cache-Control "public, max-age=604800, immutable";
+        try_files $uri =404;
+    }
+
+    # SPA 路由支持
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # 安全相关响应头
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+
+    # 禁止隐藏文件访问
+    location ~ /\. {
+        deny all;
+        access_log off;
+        log_not_found off;
+    }
+}
+
+# HTTPS 服务器（443端口）
+# 注意：需要先配置 SSL 证书
+# 建议使用 certbot 或手动配置证书
+#
+# server {
+#     listen 443 ssl http2;
+#     server_name *.preview.xiaoxiajianji.com;
+#
+#     # SSL 证书配置（请替换为实际证书路径）
+#     ssl_certificate /path/to/fullchain.pem;
+#     ssl_certificate_key /path/to/privkey.pem;
+#
+#     # SSL 安全配置
+#     ssl_protocols TLSv1.2 TLSv1.3;
+#     ssl_ciphers HIGH:!aNULL:!MD5;
+#     ssl_prefer_server_ciphers on;
+#     ssl_session_cache shared:SSL:10m;
+#     ssl_session_timeout 10m;
+#
+#     # 其余配置与 HTTP 相同
+#     root /var/www/preview/$preview_pr;
+#     index index.html;
+#     charset utf-8;
+#
+#     access_log /var/log/nginx/preview_ssl_access.log;
+#     error_log /var/log/nginx/preview_ssl_error.log warn;
+#
+#     if ($preview_pr = "") {
+#         return 404;
+#     }
+#
+#     if (!-d $document_root) {
+#         return 404;
+#     }
+#
+#     location /api/ {
+#         proxy_pass https://staging-api.xiaoxiajianji.com/api/;
+#         proxy_http_version 1.1;
+#         proxy_set_header Host staging-api.xiaoxiajianji.com;
+#         proxy_set_header X-Real-IP $remote_addr;
+#         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+#         proxy_set_header X-Forwarded-Proto $scheme;
+#         proxy_set_header X-Forwarded-Host $host;
+#         proxy_connect_timeout 30s;
+#         proxy_send_timeout 60s;
+#         proxy_read_timeout 60s;
+#     }
+#
+#     location /assets/ {
+#         expires 7d;
+#         add_header Cache-Control "public, max-age=604800, immutable";
+#         try_files $uri =404;
+#     }
+#
+#     location / {
+#         try_files $uri $uri/ /index.html;
+#     }
+#
+#     add_header X-Frame-Options "SAMEORIGIN" always;
+#     add_header X-Content-Type-Options "nosniff" always;
+#     add_header X-XSS-Protection "1; mode=block" always;
+#
+#     location ~ /\. {
+#         deny all;
+#         access_log off;
+#         log_not_found off;
+#     }
+# }
+NGINX_CONF
+
+echo ""
+echo "----------------------------------------"
+echo "  配置完成后的操作步骤："
+echo "----------------------------------------"
+echo ""
+echo "1. 将上面的 Nginx 配置保存到合适的位置（如 /etc/nginx/conf.d/preview.conf）"
+echo "2. 测试配置: nginx -t"
+echo "3. 重载配置: nginx -s reload"
+echo "4. 配置 DNS 解析: 将 *.preview.xiaoxiajianji.com 指向服务器 IP"
+echo "5. 配置 SSL 证书（推荐使用 Let's Encrypt 通配符证书）"
+echo ""
+echo "测试方式："
+echo "  访问 http://pr-demo.preview.xiaoxiajianji.com 验证配置"
+echo ""
+echo "=========================================="
+echo "  初始化完成"
+echo "=========================================="

scripts/ci/preview_nginx.conf.template

@@ -0,0 +1,226 @@
+# ============================================================
+# 预览环境 Nginx 配置模板
+# 支持 *.preview.xiaoxiajianji.com 通配符子域名
+#
+# 使用方法：
+# 1. 将本文件复制到 Nginx 配置目录（如 /etc/nginx/conf.d/preview.conf）
+# 2. 根据实际情况修改域名和 API 地址
+# 3. 运行 nginx -t 测试配置
+# 4. 运行 nginx -s reload 重载配置
+#
+# 前置条件：
+# - DNS 已配置 *.preview.xiaoxiajianji.com 指向本服务器
+# - 预览根目录已创建：/var/www/preview/
+# - 每个 PR 的静态文件放在 /var/www/preview/pr-{N}/ 下
+# ============================================================
+
+# ---- 变量定义 ----
+# 从子域名中提取 PR 号（如 pr-123.preview -> pr-123）
+map $host $preview_pr {
+    default "";
+    ~^(?<pr>pr-\d+)\.preview\.xiaoxiajianji\.com$ $pr;
+}
+
+# ---- HTTP 服务器（80端口） ----
+server {
+    listen 80;
+    server_name *.preview.xiaoxiajianji.com;
+
+    # 根目录根据子域名动态映射
+    root /var/www/preview/$preview_pr;
+
+    # 索引文件
+    index index.html;
+
+    # 字符集
+    charset utf-8;
+
+    # 访问日志
+    access_log /var/log/nginx/preview_access.log;
+    error_log /var/log/nginx/preview_error.log warn;
+
+    # 如果子域名格式不正确，返回404
+    if ($preview_pr = "") {
+        return 404;
+    }
+
+    # 如果预览目录不存在，返回404
+    if (!-d $document_root) {
+        return 404;
+    }
+
+    # ---- API 反向代理到 staging 环境 ----
+    location /api/ {
+        proxy_pass https://staging-api.xiaoxiajianji.com/api/;
+        proxy_http_version 1.1;
+
+        # 请求头设置
+        proxy_set_header Host staging-api.xiaoxiajianji.com;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host;
+
+        # 超时设置
+        proxy_connect_timeout 30s;
+        proxy_send_timeout 60s;
+        proxy_read_timeout 60s;
+
+        # 缓冲设置
+        proxy_buffering on;
+        proxy_buffer_size 4k;
+        proxy_buffers 8 4k;
+
+        # 重定向跟随
+        proxy_redirect off;
+
+        # WebSocket 支持（如需要，取消注释）
+        # proxy_set_header Upgrade $http_upgrade;
+        # proxy_set_header Connection "upgrade";
+    }
+
+    # ---- 生成文件代理（如需要） ----
+    # location /generated-files/ {
+    #     proxy_pass https://staging-api.xiaoxiajianji.com/generated-files/;
+    #     proxy_http_version 1.1;
+    #     proxy_set_header Host staging-api.xiaoxiajianji.com;
+    #     proxy_set_header X-Real-IP $remote_addr;
+    #     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    #     proxy_set_header X-Forwarded-Proto $scheme;
+    # }
+
+    # ---- 静态资源缓存 ----
+    location /assets/ {
+        expires 7d;
+        add_header Cache-Control "public, max-age=604800, immutable";
+        try_files $uri =404;
+    }
+
+    # ---- SPA 路由支持 ----
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # ---- 安全相关响应头 ----
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+    # ---- 禁止隐藏文件访问 ----
+    location ~ /\. {
+        deny all;
+        access_log off;
+        log_not_found off;
+    }
+
+    # ---- 禁止敏感文件访问 ----
+    location ~* \.(env|log|sql|bak|swp|tmp|zip|tar|gz)$ {
+        deny all;
+        access_log off;
+        log_not_found off;
+    }
+}
+
+# ============================================================
+# HTTPS 服务器配置（可选，需要 SSL 证书）
+#
+# 推荐使用 Let's Encrypt 通配符证书：
+#   certbot certonly --dns-xxx -d "*.preview.xiaoxiajianji.com"
+#
+# 启用方法：取消下方注释，并修改证书路径
+# ============================================================
+#
+# server {
+#     listen 443 ssl http2;
+#     server_name *.preview.xiaoxiajianji.com;
+#
+#     # SSL 证书配置
+#     ssl_certificate /etc/letsencrypt/live/preview.xiaoxiajianji.com/fullchain.pem;
+#     ssl_certificate_key /etc/letsencrypt/live/preview.xiaoxiajianji.com/privkey.pem;
+#
+#     # SSL 安全配置
+#     ssl_protocols TLSv1.2 TLSv1.3;
+#     ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
+#     ssl_prefer_server_ciphers off;
+#     ssl_session_cache shared:SSL:10m;
+#     ssl_session_timeout 10m;
+#     ssl_session_tickets off;
+#
+#     # OCSP Stapling
+#     ssl_stapling on;
+#     ssl_stapling_verify on;
+#
+#     # 根目录根据子域名动态映射
+#     root /var/www/preview/$preview_pr;
+#
+#     # 索引文件
+#     index index.html;
+#
+#     # 字符集
+#     charset utf-8;
+#
+#     # 访问日志
+#     access_log /var/log/nginx/preview_ssl_access.log;
+#     error_log /var/log/nginx/preview_ssl_error.log warn;
+#
+#     # 如果子域名格式不正确，返回404
+#     if ($preview_pr = "") {
+#         return 404;
+#     }
+#
+#     # 如果预览目录不存在，返回404
+#     if (!-d $document_root) {
+#         return 404;
+#     }
+#
+#     # API 反向代理到 staging 环境
+#     location /api/ {
+#         proxy_pass https://staging-api.xiaoxiajianji.com/api/;
+#         proxy_http_version 1.1;
+#         proxy_set_header Host staging-api.xiaoxiajianji.com;
+#         proxy_set_header X-Real-IP $remote_addr;
+#         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+#         proxy_set_header X-Forwarded-Proto $scheme;
+#         proxy_set_header X-Forwarded-Host $host;
+#         proxy_connect_timeout 30s;
+#         proxy_send_timeout 60s;
+#         proxy_read_timeout 60s;
+#         proxy_buffering on;
+#         proxy_buffer_size 4k;
+#         proxy_buffers 8 4k;
+#     }
+#
+#     # 静态资源缓存
+#     location /assets/ {
+#         expires 7d;
+#         add_header Cache-Control "public, max-age=604800, immutable";
+#         try_files $uri =404;
+#     }
+#
+#     # SPA 路由支持
+#     location / {
+#         try_files $uri $uri/ /index.html;
+#     }
+#
+#     # 安全相关响应头
+#     add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+#     add_header X-Frame-Options "SAMEORIGIN" always;
+#     add_header X-Content-Type-Options "nosniff" always;
+#     add_header X-XSS-Protection "1; mode=block" always;
+#     add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+#
+#     # 禁止隐藏文件访问
+#     location ~ /\. {
+#         deny all;
+#         access_log off;
+#         log_not_found off;
+#     }
+#
+#     # 禁止敏感文件访问
+#     location ~* \.(env|log|sql|bak|swp|tmp|zip|tar|gz)$ {
+#         deny all;
+#         access_log off;
+#         log_not_found off;
+#     }
+# }

scripts/ci/select_unit_tests.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""
+根据PR改动文件选择需要运行的单元测试文件。
+
+映射规则：
+1. 改了tests/unit下的测试文件 -> 直接跑这些测试
+2. 改了apps/api/app/api/routes/xxx.py -> 匹配 test_*xxx*.py
+3. 改了apps/api/app/services/xxx.py -> 匹配 test_*xxx*.py
+4. 改了apps/worker/.../xxx.py -> 匹配 test_*xxx*.py
+5. 改了apps/worker/video_processing/xxx_engine.py -> 匹配 test_*xxx*.py
+6. 改了packages/.../xxx.py -> 匹配 test_*xxx*.py
+7. 改了公共核心模块(core/middleware/schemas/config/db/auth/dependencies) -> 全量
+8. 改了依赖文件(requirements*.txt, pyproject.toml) -> 全量
+9. 改了alembic/migrations -> 全量
+10. 匹配不到测试的改动 -> 全量兜底
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+TESTS_DIR = ROOT / "tests" / "unit"
+
+# 触发全量的文件模式（公共核心/基础设施）
+FULL_RUN_PATTERNS = [
+    "apps/api/app/core/",
+    "apps/api/app/middleware/",
+    "apps/api/app/schemas/",
+    "apps/api/app/config.py",
+    "apps/api/app/db.py",
+    "apps/api/app/auth.py",
+    "apps/api/app/dependencies.py",
+    "packages/shared/",
+    "alembic/",
+    "migrations/",
+    "requirements-base.txt",
+    "requirements.txt",
+    "requirements-dev.txt",
+    "pyproject.toml",
+    "setup.cfg",
+    ".gitea/workflows/",
+    "scripts/ci/",
+    "tests/conftest.py",
+]
+
+# 目录到测试文件关键词的映射（模糊匹配）
+DIR_KEYWORD_MAP = {
+    "apps/api/app/api/routes/": "",  # 用文件名匹配
+    "apps/api/app/services/": "",  # 用文件名匹配
+    "apps/worker/worker_app/tasks/": "",
+    "apps/worker/video_processing/": "",
+    "apps/worker/services/": "",
+    "packages/application/": "",
+    "packages/adapters/": "",
+}
+
+
+def get_changed_files():
+    """获取改动文件列表（从环境变量或git diff）。"""
+    # 优先从环境变量读取（CI中传入）
+    changed_env = os.environ.get("CHANGED_FILES", "")
+    if changed_env:
+        return [f.strip() for f in changed_env.split("\n") if f.strip()]
+
+    # 回退到git diff（本地调试用）
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "origin/develop...HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=ROOT,
+        )
+        if result.returncode == 0:
+            return [f.strip() for f in result.stdout.split("\n") if f.strip()]
+    except Exception:
+        pass
+
+    return []
+
+
+def should_full_run(files):
+    """检查是否需要全量运行。"""
+    for f in files:
+        for pattern in FULL_RUN_PATTERNS:
+            if f.startswith(pattern) or f == pattern:
+                print(f"[full-run] 触发全量: {f} 匹配 {pattern}")
+                return True
+    return False
+
+
+def extract_module_name(filepath):
+    """从文件路径提取模块名（用于匹配测试文件）。"""
+    # 去掉扩展名
+    name = Path(filepath).stem
+
+    # 特殊映射
+    special_mappings = {
+        # 路由文件
+        "edit_plans_adjustments": "edit_plan_adjustments",
+        "edit_plans_ai": "edit_plan",
+        "edit_plans_clips_batch": "edit_plan",
+        "edit_plans_cover": "edit_plan_cover",
+        "edit_plans_export": "edit_plan_export",
+        "edit_plans_filter": "edit_plan_filter",
+        "edit_plans_generation": "edit_plan_generation",
+        "edit_plans_transitions": "edit_plan_transitions",
+        "asset_libraries": "asset_library",
+        "classification_jobs": "classification",
+        "chunked_upload": "chunked_upload",
+        "form_upload": "form_upload",
+        # 服务文件
+        "edit_template_service": "edit_template_service",
+        "edit_plan_service": "edit_plan_service",
+        "unified_render_service": "unified_render",
+        "job_service": "job_service",
+        "auto_clip_service": "auto_clip",
+        "cosyvoice_service": "cosyvoice",
+        "video_compose_service": "video_compose",
+        "email_service": "email_service",
+    }
+
+    return special_mappings.get(name, name)
+
+
+def find_matching_tests(keyword, all_test_files):
+    """模糊匹配测试文件。"""
+    keyword_lower = keyword.lower().replace("_", "")
+    matches = []
+    for tf in all_test_files:
+        tf_name = Path(tf).stem.lower().replace("_", "")
+        if keyword_lower in tf_name or tf_name in keyword_lower:
+            matches.append(tf)
+    return matches
+
+
+def get_all_test_files():
+    """获取所有单元测试文件。"""
+    if not TESTS_DIR.exists():
+        return []
+    return sorted(str(f.relative_to(ROOT)) for f in TESTS_DIR.glob("test_*.py"))
+
+
+def select_tests(changed_files):
+    """主函数：选择要运行的测试文件。"""
+    all_tests = get_all_test_files()
+
+    if not changed_files:
+        print("[info] 未找到改动文件，全量运行")
+        return all_tests, "full (no changes detected)"
+
+    if should_full_run(changed_files):
+        return all_tests, "full (core/common files changed)"
+
+    selected = set()
+    test_file_changes = []
+    source_file_changes = []
+
+    for f in changed_files:
+        # 测试文件本身改动
+        if f.startswith("tests/unit/test_") and f.endswith(".py"):
+            test_file_changes.append(f)
+            selected.add(f)
+        # 源码文件改动
+        elif f.endswith(".py"):
+            source_file_changes.append(f)
+            module_name = extract_module_name(f)
+            matches = find_matching_tests(module_name, all_tests)
+            if matches:
+                for m in matches:
+                    selected.add(m)
+                print(f"[map] {f} -> {len(matches)} 个测试: {[Path(m).name for m in matches]}")
+            else:
+                print(f"[nomatch] {f} (module: {module_name}) 未找到匹配的测试文件")
+
+    if not selected:
+        print("[info] 未匹配到任何测试文件，全量运行兜底")
+        return all_tests, "full (no matching tests)"
+
+    return sorted(selected), f"incremental ({len(selected)} test files)"
+
+
+def main():
+    changed_files = get_changed_files()
+    print(f"=== 改动文件 ({len(changed_files)} 个) ===")
+    for f in changed_files[:20]:
+        print(f"  {f}")
+    if len(changed_files) > 20:
+        print(f"  ... 还有 {len(changed_files) - 20} 个")
+    print()
+
+    selected, mode = select_tests(changed_files)
+
+    print()
+    print(f"=== 运行模式: {mode} ===")
+    print(f"=== 选中测试文件: {len(selected)} 个 ===")
+    for t in selected[:20]:
+        print(f"  {t}")
+    if len(selected) > 20:
+        print(f"  ... 还有 {len(selected) - 20} 个")
+
+    # 输出结果文件（供CI后续步骤使用）
+    output_file = os.environ.get("SELECTED_TESTS_OUTPUT", "")
+    if output_file:
+        with open(output_file, "w") as f:
+            for t in selected:
+                f.write(t + "\n")
+        print(f"\n已写入到: {output_file}")
+
+    # 设置环境变量标记
+    gh_output = os.environ.get("GITHUB_OUTPUT", "")
+    if gh_output:
+        with open(gh_output, "a") as f:
+            f.write(f"test_count={len(selected)}\n")
+            f.write("mode=" + ("incremental" if "incremental" in mode else "full") + "\n")
+
+    # 退出码：0=增量, 1=全量（供CI判断）
+    sys.exit(0 if "incremental" in mode else 1)
+
+
+if __name__ == "__main__":
+    main()

scripts/ci_code_review.py

@@ -0,0 +1,687 @@
+#!/usr/bin/env python3
+"""
+CI Code Review Script
+- 从 Gitea 获取 PR diff
+- 调用 LLM 进行代码审查
+- 将审查结果写回 PR 评论
+"""
+
+import argparse
+import json
+import logging
+import os
+import sys
+from typing import Optional, Tuple
+
+import requests
+
+# ============== 日志配置 ==============
+logging.basicConfig(
+    level=logging.INFO,
+    format="[%(asctime)s] [%(levelname)s] %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+logger = logging.getLogger("ci_code_review")
+
+
+# ============== 常量配置 ==============
+# diff 最大字符数（超过则截断）
+MAX_DIFF_CHARS = int(os.getenv("MAX_DIFF_CHARS", "30000"))
+# LLM 调用超时时间（秒）
+LLM_TIMEOUT = int(os.getenv("LLM_TIMEOUT", "120"))
+# Gitea API 超时时间（秒）
+GITEA_TIMEOUT = int(os.getenv("GITEA_TIMEOUT", "30"))
+# 最大重试次数
+MAX_RETRIES = int(os.getenv("MAX_RETRIES", "2"))
+# LLM 提供商: openai (OpenAI兼容) / coze (扣子原生Bot API)
+LLM_PROVIDER = os.getenv("LLM_PROVIDER", "coze").lower()
+
+
+# ============== 工具函数 ==============
+def truncate_diff(diff_text: str, max_chars: int) -> Tuple[str, bool]:
+    """
+    截断过大的 diff 内容，避免超出 LLM 上下文限制。
+    优先保留文件头和前面的变更，末尾加提示。
+    """
+    if len(diff_text) <= max_chars:
+        return diff_text, False
+
+    # 找到一个合适的截断位置（尽量在文件边界）
+    truncated = diff_text[:max_chars]
+    # 尝试在最后一个 "diff --git" 处截断，避免截断到一半
+    last_file_boundary = truncated.rfind("\ndiff --git ")
+    if last_file_boundary > max_chars // 2:
+        truncated = truncated[:last_file_boundary]
+
+    truncated += (
+        f"\n\n... [DIFF TRUNCATED] 原始 diff 共 {len(diff_text)} 字符，"
+        f"已截断至 {len(truncated)} 字符，仅审查前半部分。\n"
+    )
+    return truncated, True
+
+
+def get_env_or_fail(name: str) -> str:
+    """从环境变量获取值，不存在则报错退出。"""
+    value = os.getenv(name)
+    if not value:
+        logger.error(f"环境变量 {name} 未设置")
+        sys.exit(1)
+    return value
+
+
+# ============== Gitea API 相关 ==============
+class GiteaClient:
+    """Gitea API 客户端"""
+
+    def __init__(self, base_url: str, token: str, repo: str):
+        # 确保 base_url 以 / 结尾
+        self.base_url = base_url.rstrip("/") + "/"
+        self.token = token
+        self.repo = repo  # 格式: owner/repo
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "Authorization": f"token {token}",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            }
+        )
+
+    def _api_url(self, path: str) -> str:
+        """拼接 API 路径"""
+        return f"{self.base_url}api/v1/repos/{self.repo}/{path.lstrip('/')}"
+
+    def get_pr_diff(self, pr_number: int) -> str:
+        """
+        获取 PR 的 diff 内容。
+        Gitea API: GET /repos/{owner}/{repo}/pulls/{index}.diff
+        """
+        url = self._api_url(f"pulls/{pr_number}.diff")
+        logger.info(f"获取 PR #{pr_number} diff: {url}")
+
+        resp = self.session.get(
+            url,
+            timeout=GITEA_TIMEOUT,
+            headers={
+                "Accept": "text/plain",
+            },
+        )
+        if resp.status_code != 200:
+            logger.error(f"获取 diff 失败: HTTP {resp.status_code} - {resp.text[:200]}")
+            raise RuntimeError(f"Failed to get PR diff: HTTP {resp.status_code}")
+
+        diff_text = resp.text
+        logger.info(f"获取到 diff，共 {len(diff_text)} 字符")
+        return diff_text
+
+    def get_pr_files(self, pr_number: int) -> list:
+        """
+        获取 PR 修改的文件列表。
+        Gitea API: GET /repos/{owner}/{repo}/pulls/{index}/files
+        """
+        url = self._api_url(f"pulls/{pr_number}/files")
+        logger.info(f"获取 PR #{pr_number} 文件列表")
+
+        resp = self.session.get(url, timeout=GITEA_TIMEOUT)
+        if resp.status_code != 200:
+            logger.warning(f"获取文件列表失败: HTTP {resp.status_code}")
+            return []
+
+        files = resp.json()
+        logger.info(f"PR 修改了 {len(files)} 个文件")
+        return files
+
+    def post_pr_comment(self, pr_number: int, body: str) -> bool:
+        """
+        在 PR 上发布评论。
+        Gitea API: POST /repos/{owner}/{repo}/issues/{index}/comments
+        （Gitea 中 PR 评论走 issues 接口）
+        """
+        url = self._api_url(f"issues/{pr_number}/comments")
+        logger.info(f"发布 PR 评论: {url}")
+
+        payload = {"body": body}
+        resp = self.session.post(
+            url,
+            data=json.dumps(payload),
+            timeout=GITEA_TIMEOUT,
+        )
+        if resp.status_code not in (200, 201):
+            logger.error(f"发布评论失败: HTTP {resp.status_code} - {resp.text[:200]}")
+            return False
+
+        logger.info(f"评论发布成功，评论 ID: {resp.json().get('id', 'unknown')}")
+        return True
+
+    def get_existing_review_comments(self, pr_number: int, marker: str) -> list:
+        """
+        获取 PR 上已有的 AI 审查评论 ID 列表（带标识 marker）。
+        """
+        url = self._api_url(f"issues/{pr_number}/comments")
+        resp = self.session.get(url, timeout=GITEA_TIMEOUT)
+        if resp.status_code != 200:
+            logger.warning(f"获取评论列表失败: HTTP {resp.status_code}")
+            return []
+
+        comments = resp.json()
+        review_comment_ids = []
+        for c in comments:
+            body = c.get("body", "")
+            if marker in body:
+                review_comment_ids.append(c.get("id"))
+        logger.info(f"找到 {len(review_comment_ids)} 条旧的 AI 审查评论")
+        return review_comment_ids
+
+    def delete_pr_comment(self, pr_number: int, comment_id: int) -> bool:
+        """
+        删除 PR 上的指定评论。
+        """
+        url = self._api_url(f"issues/comments/{comment_id}")
+        resp = self.session.delete(url, timeout=GITEA_TIMEOUT)
+        if resp.status_code not in (200, 204):
+            logger.warning(f"删除评论 {comment_id} 失败: HTTP {resp.status_code}")
+            return False
+        return True
+
+
+def call_llm_openai(
+    prompt: str,
+    llm_base_url: str,
+    llm_api_key: str,
+    llm_model: str,
+) -> Optional[str]:
+    """OpenAI 兼容模式调用"""
+    base_url = llm_base_url.rstrip("/") + "/"
+    api_url = f"{base_url}chat/completions"
+
+    headers = {
+        "Authorization": f"Bearer {llm_api_key}",
+        "Content-Type": "application/json",
+    }
+
+    payload = {
+        "model": llm_model,
+        "messages": [
+            {
+                "role": "system",
+                "content": "你是一位严谨的资深代码审查专家，擅长发现代码中的逻辑错误、安全隐患和性能问题。",
+            },
+            {
+                "role": "user",
+                "content": prompt,
+            },
+        ],
+        "temperature": 0.3,
+        "max_tokens": 2048,
+    }
+
+    logger.info(f"调用 LLM (OpenAI兼容): {api_url}, model={llm_model}")
+
+    last_error = None
+    for attempt in range(MAX_RETRIES + 1):
+        try:
+            resp = requests.post(
+                api_url,
+                headers=headers,
+                json=payload,
+                timeout=LLM_TIMEOUT,
+            )
+            if resp.status_code != 200:
+                logger.warning(f"LLM 调用失败 (第 {attempt + 1} 次): " f"HTTP {resp.status_code} - {resp.text[:200]}")
+                last_error = f"HTTP {resp.status_code}"
+                continue
+
+            data = resp.json()
+            choices = data.get("choices", [])
+            if not choices:
+                logger.warning(f"LLM 返回空结果 (第 {attempt + 1} 次)")
+                last_error = "empty choices"
+                continue
+
+            content = choices[0].get("message", {}).get("content", "")
+            if not content.strip():
+                logger.warning(f"LLM 返回空内容 (第 {attempt + 1} 次)")
+                last_error = "empty content"
+                continue
+
+            logger.info(f"LLM 审查完成，结果长度: {len(content)} 字符")
+            return content
+
+        except requests.Timeout:
+            logger.warning(f"LLM 调用超时 (第 {attempt + 1} 次)")
+            last_error = "timeout"
+        except requests.RequestException as e:
+            logger.warning(f"LLM 调用异常 (第 {attempt + 1} 次): {e}")
+            last_error = str(e)
+
+    logger.error(f"LLM 调用最终失败: {last_error}")
+    return None
+
+
+def call_llm_coze(
+    prompt: str,
+    llm_base_url: str,
+    llm_api_key: str,
+    llm_model: str,
+    coze_bot_id: str,
+) -> Optional[str]:
+    """扣子(Coze)原生 Bot API 调用（支持异步轮询）"""
+    import time
+
+    base_url = llm_base_url.rstrip("/") + "/"
+    api_url = f"{base_url}v3/chat"
+
+    headers = {
+        "Authorization": f"Bearer {llm_api_key}",
+        "Content-Type": "application/json",
+    }
+
+    payload = {
+        "bot_id": coze_bot_id,
+        "user_id": "ci-code-review-bot",
+        "stream": False,
+        "additional_messages": [
+            {
+                "role": "user",
+                "content": prompt,
+                "content_type": "text",
+            }
+        ],
+    }
+
+    logger.info(f"调用 LLM (Coze): {api_url}, bot_id={coze_bot_id}")
+
+    last_error = None
+    for attempt in range(MAX_RETRIES + 1):
+        try:
+            resp = requests.post(
+                api_url,
+                headers=headers,
+                json=payload,
+                timeout=LLM_TIMEOUT,
+            )
+            if resp.status_code != 200:
+                logger.warning(f"Coze 调用失败 (第 {attempt + 1} 次): " f"HTTP {resp.status_code} - {resp.text[:300]}")
+                last_error = f"HTTP {resp.status_code}"
+                continue
+
+            data = resp.json()
+            chat_data = data.get("data", {})
+            chat_id = chat_data.get("id", "")
+            conversation_id = chat_data.get("conversation_id", "")
+            status = chat_data.get("status", "")
+
+            # Coze v3 API 异步：先返回 in_progress，需要轮询
+            if status == "in_progress" and conversation_id and chat_id:
+                logger.info(f"Coze 异步处理中，开始轮询... (chat_id={chat_id[:12]}...)")
+                # 轮询 message 列表接口（GET + query参数），最多等 LLM_TIMEOUT 秒
+                poll_url = f"{base_url}v3/chat/message/list"
+                poll_start = time.time()
+                poll_interval = 3  # 每3秒轮询一次
+
+                while time.time() - poll_start < LLM_TIMEOUT:
+                    time.sleep(poll_interval)
+                    poll_params = {
+                        "chat_id": chat_id,
+                        "conversation_id": conversation_id,
+                    }
+                    poll_resp = requests.get(
+                        poll_url,
+                        headers=headers,
+                        params=poll_params,
+                        timeout=GITEA_TIMEOUT,
+                    )
+                    if poll_resp.status_code != 200:
+                        logger.debug(f"轮询返回 HTTP {poll_resp.status_code}: {poll_resp.text[:100]}")
+                        continue
+
+                    poll_data = poll_resp.json()
+                    if poll_data.get("code", 0) != 0:
+                        logger.debug(f"轮询返回错误: {poll_data.get('msg', '')}")
+                        continue
+
+                    messages = poll_data.get("data", []) or []
+
+                    # 找assistant的answer消息
+                    content = None
+                    for msg in messages:
+                        if msg.get("role") == "assistant" and msg.get("type") == "answer":
+                            content = msg.get("content", "")
+                            break
+
+                    if content and content.strip():
+                        logger.info(f"Coze 审查完成，结果长度: {len(content)} 字符")
+                        return content
+
+                logger.warning(f"Coze 轮询超时 ({LLM_TIMEOUT}s)，未拿到结果")
+                last_error = "poll timeout"
+                continue
+
+            # 同步返回的情况（兼容）
+            content = None
+            messages = chat_data.get("messages", []) or data.get("messages", [])
+            for msg in messages:
+                if msg.get("role") == "assistant" and msg.get("type") == "answer":
+                    content = msg.get("content", "")
+                    break
+
+            if not content:
+                content = chat_data.get("content") or data.get("content")
+
+            if not content:
+                choices = data.get("choices", [])
+                if choices:
+                    content = choices[0].get("message", {}).get("content", "")
+
+            if not content or not content.strip():
+                logger.warning(f"Coze 返回空内容 (第 {attempt + 1} 次): {str(data)[:200]}")
+                last_error = "empty content"
+                continue
+
+            logger.info(f"Coze 审查完成，结果长度: {len(content)} 字符")
+            return content
+
+        except requests.Timeout:
+            logger.warning(f"Coze 调用超时 (第 {attempt + 1} 次)")
+            last_error = "timeout"
+        except requests.RequestException as e:
+            logger.warning(f"Coze 调用异常 (第 {attempt + 1} 次): {e}")
+            last_error = str(e)
+
+    logger.error(f"Coze 调用最终失败: {last_error}")
+    return None
+
+
+def build_review_prompt(diff_text: str, pr_number: int, file_list: list) -> str:
+    """
+    构建代码审查的 Prompt。
+    包含：PR 基本信息、修改文件列表、diff 内容、审查要求。
+    """
+    # 提取文件名列表
+    file_names = [f.get("filename", "") for f in file_list] if file_list else []
+    file_list_str = "\n".join(f"  - {fn}" for fn in file_names) if file_names else "  （未获取到文件列表）"
+
+    prompt = f"""请作为资深代码审查专家，对以下 Pull Request 的代码变更进行严格审查。
+
+## PR 基本信息
+- PR 编号: #{pr_number}
+- 修改文件数: {len(file_list) if file_list else '未知'}
+
+## 修改文件列表
+{file_list_str}
+
+## 代码变更（diff）
+```diff
+{diff_text}
+```
+
+## 审查要求
+请从以下维度进行审查，重点关注严重问题：
+
+1. **逻辑正确性**：是否有明显的逻辑错误、边界条件遗漏、空指针/None引用风险
+2. **异常处理**：异常捕获是否合理，是否有裸except，错误处理是否完善
+3. **参数校验**：函数入参、返回值是否有必要的校验
+4. **代码质量**：是否有重复代码、命名不清晰、过于复杂的函数
+5. **性能问题**：是否有明显的性能隐患（如循环内重复计算、不必要的数据库查询）
+6. **安全问题**：是否有注入风险、敏感信息泄露、权限控制问题
+
+## 输出格式
+请使用以下格式输出，语言为中文：
+
+### 📊 审查概览
+- 整体评价：（通过 / 有建议 / 需修改）
+- 严重问题数量：X 个
+- 一般建议数量：X 个
+
+### ❌ 需修改的问题（严重）
+（如果没有严重问题，写"无"）
+1. **[文件: 行号] 问题标题**
+   - 问题描述：...
+   - 修改建议：...
+
+### 💡 改进建议（一般）
+（如果没有建议，写"无"）
+1. **[文件: 行号] 建议标题**
+   - 具体内容：...
+
+### ✅ 良好实践
+（可选，列出值得肯定的地方）
+
+请务必基于代码实际内容审查，不要编造不存在的问题。如果代码质量良好，直接给出通过结论即可。
+"""
+    return prompt
+
+
+def call_llm_for_review(
+    diff_text: str,
+    pr_number: int,
+    file_list: list,
+    llm_base_url: str,
+    llm_api_key: str,
+    llm_model: str,
+    coze_bot_id: str = "",
+) -> Optional[str]:
+    """
+    调用 LLM 进行代码审查，返回审查结果文本。
+    失败时返回 None。
+    根据 LLM_PROVIDER 环境变量选择调用方式。
+    """
+    prompt = build_review_prompt(diff_text, pr_number, file_list)
+    logger.info(f"Prompt 长度: {len(prompt)} 字符")
+
+    provider = LLM_PROVIDER
+
+    if provider == "coze":
+        return call_llm_coze(prompt, llm_base_url, llm_api_key, llm_model, coze_bot_id)
+    else:
+        # 默认 OpenAI 兼容
+        return call_llm_openai(prompt, llm_base_url, llm_api_key, llm_model)
+
+
+# ============== 主流程 ==============
+def main():
+    parser = argparse.ArgumentParser(description="CI AI 代码审查脚本")
+    parser.add_argument("--pr", type=int, help="PR 编号（也可通过 PR_NUMBER 环境变量）")
+    parser.add_argument("--repo", type=str, help="仓库名 owner/repo（也可通过 REPO_NAME 环境变量）")
+    parser.add_argument("--gitea-url", type=str, help="Gitea 地址（也可通过 GITEA_API_URL 环境变量）")
+    parser.add_argument("--gitea-token", type=str, help="Gitea Token（也可通过 GITEA_TOKEN 环境变量）")
+    parser.add_argument("--dry-run", action="store_true", help="只输出审查结果，不发表评论")
+    args = parser.parse_args()
+
+    # 读取配置
+    gitea_url = args.gitea_url or os.getenv("GITEA_API_URL") or os.getenv("GITEA_SERVER_URL")
+    gitea_token = args.gitea_token or os.getenv("GITEA_TOKEN")
+    repo_name = args.repo or os.getenv("REPO_NAME") or os.getenv("GITEA_REPO")
+    pr_number = args.pr or int(os.getenv("PR_NUMBER") or os.getenv("GITEA_PR_NUMBER") or 0)
+
+    llm_base_url = os.getenv("LLM_BASE_URL")
+    llm_api_key = os.getenv("LLM_API_KEY")
+    llm_model = os.getenv("LLM_MODEL", "")
+    coze_bot_id = os.getenv("COZE_BOT_ID", os.getenv("COZE_BOTID", ""))
+
+    # 根据 provider 设置默认值
+    provider = LLM_PROVIDER
+    if provider == "coze":
+        # 扣子模式：默认国内站，key 兼容多种环境变量名
+        if not llm_base_url:
+            llm_base_url = "https://api.coze.cn"
+        if not llm_api_key:
+            llm_api_key = os.getenv("COZE_API_KEY", "") or os.getenv("COZE_PAT", "")
+    else:
+        # OpenAI兼容模式：默认模型
+        if not llm_model:
+            llm_model = "gpt-4o-mini"
+
+    # 必要参数校验
+    missing = []
+    if not gitea_url:
+        missing.append("GITEA_API_URL")
+    if not gitea_token:
+        missing.append("GITEA_TOKEN")
+    if not repo_name:
+        missing.append("REPO_NAME")
+    if not pr_number:
+        missing.append("PR_NUMBER")
+    if not llm_base_url:
+        missing.append("LLM_BASE_URL")
+    if not llm_api_key:
+        missing.append("LLM_API_KEY")
+    if provider == "coze" and not coze_bot_id:
+        missing.append("COZE_BOT_ID (扣子模式需要)")
+
+    if missing:
+        logger.error(f"缺少必要配置: {', '.join(missing)}")
+        sys.exit(1)
+
+    logger.info(f"开始审查 PR #{pr_number}，仓库: {repo_name}")
+    logger.info(f"Gitea: {gitea_url}")
+    logger.info(f"LLM: {llm_base_url} (model={llm_model})")
+
+    try:
+        # 1. 初始化 Gitea 客户端
+        gitea = GiteaClient(gitea_url, gitea_token, repo_name)
+
+        # 2. 获取 PR diff 和文件列表
+        try:
+            diff_text = gitea.get_pr_diff(pr_number)
+            file_list = gitea.get_pr_files(pr_number)
+        except Exception as e:
+            logger.error(f"获取 PR 信息失败: {e}")
+            sys.exit(1)
+
+        # 3. 过滤掉不需要审查的文件（如 lock 文件、生成的文件、二进制文件等）
+        skip_extensions = (
+            ".lock",
+            ".sum",
+            ".min.js",
+            ".min.css",
+            ".map",
+            ".png",
+            ".jpg",
+            ".jpeg",
+            ".gif",
+            ".svg",
+            ".ico",
+            ".woff",
+            ".woff2",
+            ".ttf",
+            ".eot",
+        )
+        skipped_files = []
+        if file_list:
+            skipped_files = [
+                f.get("filename")
+                for f in file_list
+                if f.get("filename", "").endswith(skip_extensions) or f.get("status") == "removed"
+            ]
+            if skipped_files:
+                logger.info(f"跳过 {len(skipped_files)} 个非文本/已删除文件: {', '.join(skipped_files[:5])}...")
+
+        # 实际从 diff 中移除跳过的文件（按文件边界切割）
+        if skipped_files:
+            diff_lines = diff_text.split("\n")
+            filtered_lines = []
+            current_file = None
+            skip_current = False
+            i = 0
+            while i < len(diff_lines):
+                line = diff_lines[i]
+                # 检测新文件开始: diff --git a/xxx b/xxx
+                if line.startswith("diff --git "):
+                    # 提取文件名
+                    parts = line.split(" ")
+                    if len(parts) >= 4:
+                        # b/ 后面的是目标文件名
+                        current_file = parts[3][2:] if parts[3].startswith("b/") else parts[3]
+                        skip_current = any(current_file == sf for sf in skipped_files) or any(
+                            current_file.endswith(ext) for ext in skip_extensions
+                        )
+                    else:
+                        skip_current = False
+                if not skip_current:
+                    filtered_lines.append(line)
+                i += 1
+            original_len = len(diff_text)
+            diff_text = "\n".join(filtered_lines)
+            logger.info(f"Diff 过滤后: {original_len} -> {len(diff_text)} 字符 (减少 {original_len - len(diff_text)})")
+
+        # 4. 截断过大的 diff
+        diff_text, was_truncated = truncate_diff(diff_text, MAX_DIFF_CHARS)
+        if was_truncated:
+            logger.warning(f"Diff 过大，已截断至 {len(diff_text)} 字符")
+
+        # 5. 如果 diff 为空，直接跳过
+        if not diff_text.strip():
+            logger.info("Diff 为空，无需审查")
+            sys.exit(0)
+
+        # 6. 调用 LLM 审查
+        review_result = call_llm_for_review(
+            diff_text=diff_text,
+            pr_number=pr_number,
+            file_list=file_list,
+            llm_base_url=llm_base_url,
+            llm_api_key=llm_api_key,
+            llm_model=llm_model,
+            coze_bot_id=coze_bot_id,
+        )
+
+        if not review_result:
+            logger.error("LLM 审查失败")
+            sys.exit(1)
+
+        # 7. 加上审查时间和标识（便于识别是自动审查）
+        from datetime import datetime
+
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        marker = "<!-- AI_CODE_REVIEW_AUTO_COMMENT -->"
+        full_comment = f"""{review_result}
+
+---
+<sub>🤖 由 AI 代码审查机器人自动生成 | {timestamp} | 模型: {llm_model}</sub>
+
+{marker}
+"""
+
+        # 8. 输出审查结果到日志
+        logger.info("=" * 60)
+        logger.info("审查结果:")
+        for line in review_result.split("\n")[:30]:
+            logger.info(line)
+        if len(review_result.split("\n")) > 30:
+            logger.info(f"... 共 {len(review_result.split(chr(10)))} 行")
+        logger.info("=" * 60)
+
+        # 9. 发布评论（先删除旧的审查评论，避免刷屏）
+        if args.dry_run:
+            logger.info("--dry-run 模式，跳过发布评论")
+            print(full_comment)
+        else:
+            # 去重：删除之前的 AI 审查评论
+            old_comments = gitea.get_existing_review_comments(pr_number, marker)
+            if old_comments:
+                logger.info(f"找到 {len(old_comments)} 条旧的 AI 审查评论，先删除")
+                for cid in old_comments:
+                    gitea.delete_pr_comment(pr_number, cid)
+            # 发布新评论
+            success = gitea.post_pr_comment(pr_number, full_comment)
+            if not success:
+                logger.error("评论发布失败")
+                sys.exit(1)
+
+        # 10. 判断是否有严重问题（可选阻断）
+        # 目前只做建议，不阻断合并，始终返回 0
+        has_critical = "问题" in review_result and ("❌" in review_result or "需修改" in review_result)
+        if has_critical:
+            logger.warning("检测到需修改的问题，但当前配置为仅建议，不阻断合并")
+
+        logger.info("代码审查完成")
+        sys.exit(0)
+
+    except Exception as e:
+        logger.exception(f"审查脚本发生未预期的异常: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/ci_staging_deploy.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 # ===========================================
-# Staging 部署脚本（SSH 模式）
+# Staging 部署脚本（SSH 模式，支持自动回滚）
 # ===========================================
 # 通过 SSH 在 staging 服务器上执行
 #
@@ -12,9 +12,44 @@
 #   ENV_FILE        - 环境变量文件路径
 #   GENERATED_DIR   - 生成文件目录
 #   SKIP_MIGRATION  - 跳过数据库迁移（true/false，默认 false）
+#   SKIP_ROLLBACK   - 失败时跳过自动回滚（true/false，默认 false）
 
 set -eu
 
+# ---- 重试工具函数 ----
+retry_cmd() {
+  local max_attempts=$1
+  local backoff=$2
+  shift 2
+  local attempt=1
+  while [ $attempt -le $max_attempts ]; do
+    if "$@"; then
+      return 0
+    fi
+    echo "  attempt $attempt/$max_attempts failed, retrying in ${backoff}s..."
+    sleep $backoff
+    backoff=$((backoff * 2))
+    attempt=$((attempt + 1))
+  done
+  echo "  ERROR: failed after $max_attempts retries"
+  return 1
+}
+
+retry_docker_login() {
+  echo "Logging in to registry (up to 3 retries)"
+  if retry_cmd 3 5 sh -c "printf %s "$REGISTRY_TOKEN" | docker login "$REGISTRY_HOST" -u "$REGISTRY_USER" --password-stdin"; then
+    return 0
+  fi
+  echo "WARN: docker login failed after retries, will try pull anyway"
+  return 0
+}
+
+retry_docker_pull() {
+  local image=$1
+  echo "Pulling $image (up to 3 retries)"
+  retry_cmd 3 10 docker pull "$image"
+}
+
 IMAGE_TAG="${IMAGE_TAG:-}"
 REGISTRY="${REGISTRY:-xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji}"
 REGISTRY_USER="${ACR_USERNAME:-${REGISTRY_USER:-nick0415343655}}"
@@ -25,6 +60,7 @@ GENERATED_DIR="${GENERATED_DIR:-/var/lib/xiaoxia-saas-staging/generated}"
 LEGACY_ASSETS_DIR="${LEGACY_ASSETS_DIR:-/var/lib/xiaoxia-saas-staging/legacy-assets}"
 
 SKIP_MIGRATION="${SKIP_MIGRATION:-false}"
+SKIP_ROLLBACK="${SKIP_ROLLBACK:-false}"
 
 if [ -z "$IMAGE_TAG" ]; then
   echo "ERROR: IMAGE_TAG is required"
@@ -35,17 +71,165 @@ test -f "$ENV_FILE"
 mkdir -p "$GENERATED_DIR"
 mkdir -p "$LEGACY_ASSETS_DIR"
 
-echo "=========================================="
+echo "==========================================="
 echo "  Staging 部署 - $IMAGE_TAG"
-echo "=========================================="
+echo "==========================================="
+
+# ---- 记录当前运行的镜像版本（用于回滚） ----
+echo "Recording current image versions for rollback..."
+PREV_API_IMAGE=""
+PREV_WORKER_IMAGE=""
+PREV_WEB_IMAGE=""
+for c in xiaoxia-api-staging xiaoxia-worker-staging xiaoxia-web-staging; do
+  if docker inspect "$c" >/dev/null 2>&1; then
+    img=$(docker inspect -f '{{.Config.Image}}' "$c")
+    case "$c" in
+      xiaoxia-api-staging) PREV_API_IMAGE="$img" ;;
+      xiaoxia-worker-staging) PREV_WORKER_IMAGE="$img" ;;
+      xiaoxia-web-staging) PREV_WEB_IMAGE="$img" ;;
+    esac
+    echo "  $c -> $img"
+  else
+    echo "  $c -> (not running)"
+  fi
+done
+
+# ---- 回滚函数 ----
+rollback() {
+  echo ""
+  echo "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
+  echo "  部署失败，正在自动回滚到上一版本..."
+  echo "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
+  echo ""
+
+  if [ "$SKIP_ROLLBACK" = "true" ]; then
+    echo "SKIP_ROLLBACK=true，跳过自动回滚"
+    exit 1
+  fi
+
+  # 停止当前（失败的）新容器
+  echo "Stopping new containers..."
+  docker rm -f xiaoxia-api-staging 2>/dev/null || true
+  docker rm -f xiaoxia-worker-staging 2>/dev/null || true
+  docker rm -f xiaoxia-web-staging 2>/dev/null || true
+
+  LOG_OPTS="--log-driver json-file --log-opt max-size=50m --log-opt max-file=3"
+
+  # 恢复 API
+  if [ -n "$PREV_API_IMAGE" ]; then
+    echo "Rolling back API to: $PREV_API_IMAGE"
+    docker run -d \
+      --name xiaoxia-api-staging \
+      --env-file "$ENV_FILE" \
+      --network xiaoxia-net-staging \
+      -p 127.0.0.1:8000:8000 \
+      -e APP_ENV=staging \
+      -e APP_VERSION="$(echo $PREV_API_IMAGE | grep -oE '[^:]+$')" \
+      -e GENERATED_FILES_DIR=/app/generated \
+      -e GENERATED_FILES_URL_PREFIX=/generated-files \
+      -e PUBLIC_API_BASE_URL=https://staging-api.xiaoxiajianji.com \
+      -v "$GENERATED_DIR:/app/generated" \
+      --restart unless-stopped \
+      --health-cmd "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=5)\"" \
+      --health-interval 30s \
+      --health-timeout 10s \
+      --health-retries 3 \
+      --health-start-period 40s \
+      $LOG_OPTS \
+      "$PREV_API_IMAGE"
+  else
+    echo "No previous API image to roll back to"
+  fi
+
+  # 恢复 Worker
+  if [ -n "$PREV_WORKER_IMAGE" ]; then
+    echo "Rolling back Worker to: $PREV_WORKER_IMAGE"
+    docker run -d \
+      --name xiaoxia-worker-staging \
+      --env-file "$ENV_FILE" \
+      --network xiaoxia-net-staging \
+      -e APP_ENV=staging \
+      -e APP_VERSION="$(echo $PREV_WORKER_IMAGE | grep -oE '[^:]+$')" \
+      -e WORKER_CONCURRENCY=1 \
+      -e WORKER_MAX_TASKS_PER_CHILD=100 \
+      -e GENERATED_FILES_DIR=/app/generated \
+      -e GENERATED_FILES_URL_PREFIX=/generated-files \
+      -e PUBLIC_API_BASE_URL=https://staging-api.xiaoxiajianji.com \
+      -v "$GENERATED_DIR:/app/generated" \
+      --restart unless-stopped \
+      --health-cmd "sh -c \"grep -q celery /proc/1/cmdline || exit 1\"" \
+      --health-interval 30s \
+      --health-timeout 10s \
+      --health-retries 3 \
+      --health-start-period 30s \
+      $LOG_OPTS \
+      "$PREV_WORKER_IMAGE"
+  else
+    echo "No previous Worker image to roll back to"
+  fi
+
+  # 恢复 Web
+  if [ -n "$PREV_WEB_IMAGE" ]; then
+    echo "Rolling back Web to: $PREV_WEB_IMAGE"
+    LEGACY_VOLUME=""
+    if [ -d "$LEGACY_ASSETS_DIR" ] && [ "$(ls -A "$LEGACY_ASSETS_DIR" 2>/dev/null)" ]; then
+      LEGACY_VOLUME="-v ${LEGACY_ASSETS_DIR}:/usr/share/nginx/html/assets-legacy/assets:ro"
+    fi
+    docker run -d \
+      --name xiaoxia-web-staging \
+      --network xiaoxia-net-staging \
+      -p 127.0.0.1:3001:80 \
+      --restart unless-stopped \
+      $LEGACY_VOLUME \
+      --health-cmd "wget --spider -q http://127.0.0.1:80" \
+      --health-interval 30s \
+      --health-timeout 5s \
+      --health-retries 3 \
+      $LOG_OPTS \
+      "$PREV_WEB_IMAGE"
+  else
+    echo "No previous Web image to roll back to"
+  fi
+
+  # 等待 API 回滚后恢复健康
+  if [ -n "$PREV_API_IMAGE" ]; then
+    echo "Waiting for rolled-back API to become healthy..."
+    i=0
+    while [ "$i" -lt 40 ]; do
+      if curl -sf --max-time 5 http://127.0.0.1:8000/health >/dev/null 2>&1; then
+        echo "Rolled-back API is healthy!"
+        break
+      fi
+      i=$((i + 1))
+      echo "  Waiting... ($i/40)"
+      sleep 3
+    done
+    if [ "$i" -ge 40 ]; then
+      echo "WARN: Rolled-back API did not become healthy within 120s"
+      docker logs --tail 30 xiaoxia-api-staging
+    fi
+  fi
+
+  echo ""
+  echo "==========================================="
+  echo "  回滚完成"
+  echo "==========================================="
+  echo "Previous API:    ${PREV_API_IMAGE:-none}"
+  echo "Previous Worker: ${PREV_WORKER_IMAGE:-none}"
+  echo "Previous Web:    ${PREV_WEB_IMAGE:-none}"
+  echo ""
+  echo "部署失败，已自动回滚到上一版本"
+  docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep staging
+  exit 1
+}
 
 # ---- 登录 Registry ----
 if [ -n "$REGISTRY_TOKEN" ]; then
-  echo "Logging in to registry: $REGISTRY"
+  echo "=========================================="
+  echo "  Login to Registry (with retries)"
+  echo "=========================================="
   REGISTRY_HOST=$(echo "$REGISTRY" | cut -d/ -f1)
-  printf %s "$REGISTRY_TOKEN" | docker login "$REGISTRY_HOST" -u "$REGISTRY_USER" --password-stdin 2>/dev/null || {
-    echo "WARN: docker login failed, will try to pull anyway"
-  }
+  retry_docker_login
 fi
 
 # ---- Pull 新版本镜像 ----
@@ -57,12 +241,12 @@ LOCAL_API="xiaoxia-saas-api:${IMAGE_TAG}"
 LOCAL_WORKER="xiaoxia-saas-worker:${IMAGE_TAG}"
 LOCAL_WEB="xiaoxia-saas-web:${IMAGE_TAG}"
 
-echo "Pulling API image..."
-docker pull "$REGISTRY_API"
-echo "Pulling Worker image..."
-docker pull "$REGISTRY_WORKER"
-echo "Pulling Web image..."
-docker pull "$REGISTRY_WEB"
+echo "=========================================="
+echo "  Pull images (with retries)"
+echo "=========================================="
+retry_docker_pull "$REGISTRY_API"
+retry_docker_pull "$REGISTRY_WORKER"
+retry_docker_pull "$REGISTRY_WEB"
 
 # Re-tag 成本地名
 docker tag "$REGISTRY_API" "$LOCAL_API"
@@ -117,7 +301,12 @@ if [ "$SKIP_MIGRATION" != "true" ]; then
     --env-file "$ENV_FILE" \
     --network xiaoxia-net-staging \
     -e APP_ENV=staging \
-    "$LOCAL_API" sh -c "cd /app && alembic upgrade head"
+    "$LOCAL_API" sh -c "cd /app && alembic upgrade head" || {
+    echo "ERROR: Database migration failed"
+    echo "Note: Migration failures are NOT automatically rolled back (data safety)"
+    echo "Please manually check and fix the migration, then redeploy"
+    exit 1
+  }
   echo "Migrations completed."
 else
   echo "Skipping migrations (SKIP_MIGRATION=true)"
@@ -151,7 +340,7 @@ docker run -d \
   --health-retries 3 \
   --health-start-period 40s \
   $LOG_OPTS \
-  "$LOCAL_API"
+  "$LOCAL_API" || rollback
 
 # ---- 启动 Worker ----
 echo "Starting Worker container..."
@@ -174,7 +363,7 @@ docker run -d \
   --health-retries 3 \
   --health-start-period 30s \
   $LOG_OPTS \
-  "$LOCAL_WORKER"
+  "$LOCAL_WORKER" || rollback
 
 # ---- 启动 Web ----
 LEGACY_VOLUME=""
@@ -197,7 +386,7 @@ docker run -d \
   --health-timeout 5s \
   --health-retries 3 \
   $LOG_OPTS \
-  "$LOCAL_WEB"
+  "$LOCAL_WEB" || rollback
 
 # ---- 等待 API 健康 ----
 echo "Waiting for API to become healthy..."
@@ -215,7 +404,7 @@ done
 if [ "$i" -ge 40 ]; then
   echo "ERROR: API did not become healthy within 120s"
   docker logs --tail 50 xiaoxia-api-staging
-  exit 1
+  rollback
 fi
 
 # ---- 等待 Web 健康 ----
@@ -234,7 +423,7 @@ done
 if [ "$i" -ge 15 ]; then
   echo "ERROR: Web did not become healthy within 30s"
   docker logs --tail 30 xiaoxia-web-staging
-  exit 1
+  rollback
 fi
 
 # ---- 清理旧镜像 ----

scripts/ci_trigger_monitor.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""
+CI触发可靠性监控 - 定时检查PR的CI触发状态
+- 监控open PR的最新commit是否在5分钟内触发了CI
+- 异常时通过飞书webhook告警
+
+环境变量:
+  GITEA_API_TOKEN - Gitea API Token (必填)
+  GITEA_REPO - 仓库路径，如 xiaoxia/xiaoxia-saas
+  GITEA_URL - Gitea地址，如 https://git.xiaoxiajianji.com
+  CI_NOTIFY_WEBHOOK - 飞书告警webhook (必填)
+  CHECK_INTERVAL_MIN - 检查间隔（分钟），默认5
+  STALE_THRESHOLD_MIN - CI未触发告警阈值（分钟），默认5
+"""
+
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+
+
+def get_env(name, default=""):
+    return os.environ.get(name, default)
+
+
+def api_get(path):
+    """调用Gitea API"""
+    token = get_env("GITEA_API_TOKEN")
+    base_url = get_env("GITEA_URL", "https://git.xiaoxiajianji.com")
+    repo = get_env("GITEA_REPO", "xiaoxia/xiaoxia-saas")
+
+    url = f"{base_url}/api/v1/repos/{repo}{path}"
+    req = urllib.request.Request(url)
+    req.add_header("Authorization", f"token {token}")
+
+    for attempt in range(3):
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                return json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            if e.code >= 500 and attempt < 2:
+                time.sleep(2**attempt)
+                continue
+            raise
+        except Exception as e:
+            if attempt < 2:
+                time.sleep(2**attempt)
+                continue
+            raise
+
+
+def get_open_prs():
+    """获取所有open PR"""
+    prs = []
+    page = 1
+    while True:
+        batch = api_get(f"/pulls?state=open&sort=updated&direction=desc&limit=50&page={page}")
+        if not batch:
+            break
+        prs.extend(batch)
+        if len(batch) < 50:
+            break
+        page += 1
+    return prs
+
+
+def get_commit_status(sha):
+    """获取commit的CI状态"""
+    try:
+        return api_get(f"/commits/{sha}/status")
+    except Exception as e:
+        print(f"  ⚠️  获取commit状态失败: {e}")
+        return {"state": "error", "statuses": []}
+
+
+def has_ci_started(statuses):
+    """判断是否有CI job已经启动（pending/running/success/failure都算启动了）"""
+    pr_statuses = [s for s in statuses if "pull_request" in s.get("context", "")]
+    if not pr_statuses:
+        return False
+    # 只要有非pending且非空的状态，就算启动了
+    for s in pr_statuses:
+        if s.get("status") in ["success", "failure", "running"]:
+            return True
+        if s.get("status") == "pending" and "Has started running" in s.get("description", ""):
+            return True
+    # 全是"Blocked by required conditions"的pending也算（说明CI系统收到了事件）
+    for s in pr_statuses:
+        if "Blocked" in s.get("description", ""):
+            return True
+    return False
+
+
+def send_alert(pr_num, pr_title, pr_url, head_sha, commit_age_min):
+    """发送飞书告警"""
+    webhook = get_env("CI_NOTIFY_WEBHOOK")
+    if not webhook:
+        print("  ⚠️  未配置CI_NOTIFY_WEBHOOK，跳过告警")
+        return
+
+    gitea_url = get_env("GITEA_URL", "https://git.xiaoxiajianji.com")
+
+    content = {
+        "msg_type": "interactive",
+        "card": {
+            "header": {
+                "title": {"tag": "plain_text", "content": f"⚠️ CI告警 - PR#{pr_num} CI未触发"},
+                "template": "red",
+            },
+            "elements": [
+                {
+                    "tag": "div",
+                    "text": {
+                        "tag": "lark_md",
+                        "content": f"**PR**: [{pr_title}]({pr_url})\n**最新commit**: `{head_sha[:12]}`\n**已等待**: {commit_age_min:.0f} 分钟仍无CI启动\n**可能原因**: Gitea Actions事件丢失 / Webhook失败 / Runner资源不足",
+                    },
+                },
+                {
+                    "tag": "action",
+                    "actions": [
+                        {
+                            "tag": "button",
+                            "text": {"tag": "plain_text", "content": "查看PR"},
+                            "url": pr_url,
+                            "type": "primary",
+                        },
+                        {
+                            "tag": "button",
+                            "text": {"tag": "plain_text", "content": "查看Actions"},
+                            "url": f"{pr_url}/files",
+                            "type": "default",
+                        },
+                    ],
+                },
+                {
+                    "tag": "note",
+                    "elements": [
+                        {"tag": "plain_text", "content": f"CI触发监控 | 检测时间: {time.strftime('%Y-%m-%d %H:%M:%S')}"}
+                    ],
+                },
+            ],
+        },
+    }
+
+    try:
+        data = json.dumps(content).encode()
+        req = urllib.request.Request(webhook, data=data, method="POST")
+        req.add_header("Content-Type", "application/json")
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            resp.read()
+        print(f"  📢 告警已发送: PR#{pr_num}")
+    except Exception as e:
+        print(f"  ⚠️  告警发送失败: {e}")
+
+
+def main():
+    stale_threshold = int(get_env("STALE_THRESHOLD_MIN", "5"))
+
+    print("=" * 60)
+    print(f"CI触发监控 - 检测时间: {time.strftime('%Y-%m-%d %H:%M:%S')}")
+    print(f"告警阈值: {stale_threshold}分钟无CI启动")
+    print("=" * 60)
+
+    # 获取open PR列表
+    try:
+        prs = get_open_prs()
+    except Exception as e:
+        print(f"❌ 获取PR列表失败: {e}")
+        sys.exit(0)  # 告警脚本不阻断CI
+
+    print(f"\n共 {len(prs)} 个open PR\n")
+
+    stale_prs = []
+    now = time.time()
+
+    for pr in prs:
+        pr_num = pr["number"]
+        pr_title = pr["title"]
+        pr_url = pr["html_url"]
+        head_sha = pr["head"]["sha"]
+        updated_at = pr["updated_at"]
+
+        # 解析updated_at（ISO格式）
+        try:
+            # 2026-07-17T09:22:43+08:00
+            from datetime import datetime, timedelta, timezone
+
+            # 简化处理：直接用字符串解析
+            ts_str = updated_at.replace("Z", "+00:00")
+            # 手动解析
+            dt = datetime.fromisoformat(ts_str)
+            commit_time = dt.timestamp()
+        except Exception as e:
+            print(f"  ⚠️  PR#{pr_num} 时间解析失败: {e}")
+            continue
+
+        age_min = (now - commit_time) / 60
+
+        print(f"PR#{pr_num:3d} | {pr_title[:45]:45s} | 更新于 {age_min:.0f}min前")
+
+        # 少于2分钟的跳过，给CI一点启动时间
+        if age_min < 2:
+            print(f"  ⏳ 刚更新，等待CI启动...")
+            continue
+
+        # 获取commit状态
+        status = get_commit_status(head_sha)
+        statuses = status.get("statuses", [])
+
+        if has_ci_started(statuses):
+            print(f"  ✅ CI已启动 (state={status.get('state')})")
+            continue
+
+        # CI未启动，判断是否超过阈值
+        if age_min >= stale_threshold:
+            print(f"  🚨 CI未触发！已等待 {age_min:.0f} 分钟")
+            stale_prs.append({"num": pr_num, "title": pr_title, "url": pr_url, "sha": head_sha, "age_min": age_min})
+        else:
+            print(f"  ⏳ CI尚未启动 ({age_min:.0f}min < {stale_threshold}min阈值)")
+
+    # 发送告警
+    print(f"\n{'=' * 60}")
+    print(f"检测结果: {len(stale_prs)} 个PR CI未触发超过阈值")
+
+    if stale_prs:
+        print("\n告警列表:")
+        for pr in stale_prs:
+            print(f"  - PR#{pr['num']}: {pr['title'][:40]} ({pr['age_min']:.0f}min)")
+            send_alert(pr["num"], pr["title"], pr["url"], pr["sha"], pr["age_min"])
+    else:
+        print("✅ 所有PR CI触发正常")
+
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

setup.cfg

@@ -1,18 +0,0 @@
-[flake8]
-max-line-length = 120
-extend-ignore = E203,W503,E501,E302,E402,E722,W291,W293,F401,F403,F405,F841
-exclude =
-    .git,
-    .cache,
-    __pycache__,
-    .venv,
-    .venv-ci-root,
-    build,
-    dist,
-    apps/api/app/api/routes/auth.py,
-    apps/api/app/api/routes/workspaces.py,
-    apps/api/app/middleware/auth.py
-per-file-ignores =
-    */__init__.py:F401,F403,F405
-    tests/*:E402,F401,F841
-    packages/ports/*:E301,E704

test_cleanup_readme.md

@@ -0,0 +1 @@
+# Cleanup Test

tests/unit/test_asset_repository_storage_key.py

@@ -0,0 +1,92 @@
+"""Unit tests for SQLAlchemyAssetRepository - storage_key field coverage."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+from packages.adapters.sqlalchemy_impl.asset_repository import SQLAlchemyAssetRepository
+from packages.adapters.sqlalchemy_impl.models import Base
+from packages.domain import Asset, AssetStatus
+
+
+def _repository():
+    engine = create_engine("sqlite:///:memory:")
+    Base.metadata.create_all(engine)
+    session = sessionmaker(bind=engine)()
+    return SQLAlchemyAssetRepository(session)
+
+
+def test_asset_repository_create_preserves_storage_key():
+    """create时storage_key字段正确写入数据库。"""
+    repository = _repository()
+    asset = Asset.create(
+        project_id="proj-1",
+        library_id="lib-1",
+        name="test_video.mp4",
+        storage_key="assets/proj-1/test_video.mp4",
+        mime_type="video/mp4",
+        file_size=102400,
+    )
+
+    repository.create(asset)
+    saved = repository.get(asset.id)
+
+    assert saved is not None
+    assert saved.storage_key == "assets/proj-1/test_video.mp4"
+
+
+def test_asset_repository_update_preserves_storage_key():
+    """update时storage_key字段正确更新。"""
+    repository = _repository()
+    asset = Asset.create(
+        project_id="proj-1",
+        library_id="lib-1",
+        name="test_video.mp4",
+        storage_key="assets/proj-1/old_key.mp4",
+        mime_type="video/mp4",
+    )
+    repository.create(asset)
+
+    # 更新storage_key
+    asset.storage_key = "assets/proj-1/new_key.mp4"
+    repository.update(asset)
+
+    saved = repository.get(asset.id)
+    assert saved.storage_key == "assets/proj-1/new_key.mp4"
+
+
+def test_asset_repository_to_domain_fallback_to_file_url():
+    """_to_domain中storage_key为空时fallback到file_url（兼容存量数据）。"""
+    from sqlalchemy.orm import sessionmaker
+
+    engine = create_engine("sqlite:///:memory:")
+    Base.metadata.create_all(engine)
+    session = sessionmaker(bind=engine)()
+    repository = SQLAlchemyAssetRepository(session)
+
+    # 直接插入一条storage_key为空的记录（模拟存量数据）
+    from packages.adapters.sqlalchemy_impl.models import AssetModel
+
+    model = AssetModel(
+        id="asset-legacy-001",
+        project_id="proj-1",
+        asset_library_id="lib-1",
+        name="legacy_asset.mp4",
+        file_type="video",
+        file_size=204800,
+        file_url="legacy/storage/key.mp4",  # 老数据file_url存的是storage_key
+        storage_key="",  # 新字段为空
+        status="ready",
+        classification_status="pending",
+        uploaded_by_user_id="user-1",
+    )
+    session.add(model)
+    session.commit()
+
+    saved = repository.get("asset-legacy-001")
+    assert saved is not None
+    assert saved.storage_key == "legacy/storage/key.mp4"  # fallback到file_url

tests/unit/test_auto_select_assets.py

@@ -0,0 +1,428 @@
+"""自动选素材逻辑单元测试 — 过滤不支持的编码格式."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
+
+import pytest
+
+from packages.domain import Asset, AssetLibrary, AssetLibraryKind, AssetStatus
+
+
+def _make_asset(
+    asset_id: str,
+    *,
+    status=AssetStatus.READY,
+    mime_type: str = "video/mp4",
+    codec: str | None = None,
+    metadata: dict | None = None,
+    width: int = 1080,
+    height: int = 1920,
+    created_at=None,
+) -> Asset:
+    """构造测试用 Asset 对象."""
+    from datetime import datetime, timezone
+
+    return Asset(
+        id=asset_id,
+        project_id="proj-1",
+        library_id="lib-video",
+        name=f"{asset_id}.mp4",
+        storage_key=f"uploads/{asset_id}.mp4",
+        mime_type=mime_type,
+        status=status,
+        codec=codec,
+        metadata=metadata or {},
+        width=width,
+        height=height,
+        created_at=created_at or datetime.now(timezone.utc),
+    )
+
+
+def _make_mock_repo(assets: list[Asset]):
+    """构造 mock asset_repo."""
+    mock_repo = MagicMock()
+    mock_repo.find_by_library.return_value = assets
+    return mock_repo
+
+
+def _make_mock_lib_repo():
+    """构造 mock asset_library_repo，返回一个视频素材库."""
+    video_lib = AssetLibrary(
+        id="lib-video",
+        project_id="proj-1",
+        name="视频",
+        kind=AssetLibraryKind.VIDEO,
+    )
+    mock_repo = MagicMock()
+    mock_repo.find_by_project.return_value = [video_lib]
+    return mock_repo
+
+
+class TestAutoSelectVideoAssetsCodecFilter:
+    """自动选素材 — 编码格式过滤."""
+
+    def test_h264_assets_selected(self):
+        """H.264 编码素材 → 正常选中."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset("a1", codec="h264"),
+            _make_asset("a2", codec="h264"),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert len(result) == 2
+        assert "a1" in result
+        assert "a2" in result
+
+    def test_hevc_assets_filtered_by_codec_field(self):
+        """HEVC 编码素材（codec 字段有值） → 被过滤掉."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset("a1", codec="h264"),
+            _make_asset("a2", codec="hevc"),
+            _make_asset("a3", codec="h265"),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert len(result) == 1
+        assert result[0] == "a1"
+
+    def test_hevc_assets_filtered_by_metadata(self):
+        """HEVC 编码素材（codec 字段为空，但 metadata 里有） → 被过滤掉（兼容存量数据）."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset("a1", codec=None, metadata={"codec": "h264"}),
+            _make_asset("a2", codec=None, metadata={"codec": "hevc"}),
+            _make_asset("a3", codec=None, metadata={"codec": "vp9"}),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert len(result) == 1
+        assert result[0] == "a1"
+
+    def test_codec_field_takes_precedence_over_metadata(self):
+        """codec 字段优先于 metadata 里的 codec."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        # codec 字段是 h264，但 metadata 里是 hevc → 以 codec 字段为准（应该被选中）
+        assets = [
+            _make_asset("a1", codec="h264", metadata={"codec": "hevc"}),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert len(result) == 1
+        assert result[0] == "a1"
+
+    def test_vp9_av1_assets_filtered(self):
+        """VP9 / AV1 编码素材 → 被过滤掉."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset("a1", codec="vp9"),
+            _make_asset("a2", codec="av1"),
+            _make_asset("a3", codec="h264"),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert len(result) == 1
+        assert result[0] == "a3"
+
+    def test_missing_codec_kept(self):
+        """codec 字段和 metadata 里都没有 → 暂时放过（兼容存量数据）."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset("a1", codec=None, metadata={}),
+            _make_asset("a2", codec="h264"),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert len(result) == 2
+
+    def test_codec_case_insensitive(self):
+        """编码格式过滤不区分大小写."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset("a1", codec="HEVC"),
+            _make_asset("a2", codec="H264"),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert len(result) == 1
+        assert result[0] == "a2"
+
+    def test_only_ready_assets_selected(self):
+        """只有 READY 状态的素材才会被选中."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset("a1", status=AssetStatus.READY, codec="h264"),
+            _make_asset("a2", status=AssetStatus.PROCESSING, codec="h264"),
+            _make_asset("a3", status=AssetStatus.ERROR, codec="h264"),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert len(result) == 1
+        assert result[0] == "a1"
+
+    def test_only_video_mime_selected(self):
+        """只有 video/* mime_type 的素材才会被选中."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset("a1", mime_type="video/mp4", codec="h264"),
+            _make_asset("a2", mime_type="image/jpeg"),
+            _make_asset("a3", mime_type="audio/mpeg"),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert len(result) == 1
+        assert result[0] == "a1"
+
+    def test_empty_project_returns_empty(self):
+        """空 project_id → 返回空列表."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        asset_repo = _make_mock_repo([])
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert result == []
+
+    def test_no_video_library_returns_empty(self):
+        """没有视频素材库 → 返回空列表."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        image_lib = AssetLibrary(
+            id="lib-image",
+            project_id="proj-1",
+            name="图片",
+            kind=AssetLibraryKind.IMAGE,
+        )
+        lib_repo = MagicMock()
+        lib_repo.find_by_project.return_value = [image_lib]
+
+        asset_repo = _make_mock_repo([])
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert result == []
+
+    def test_sorted_by_created_at_desc(self):
+        """结果按创建时间倒序（新素材在前）."""
+        from datetime import datetime, timedelta, timezone
+
+        from app.api.routes._helpers import auto_select_video_assets
+
+        now = datetime.now(timezone.utc)
+        assets = [
+            _make_asset("oldest", codec="h264", created_at=now - timedelta(hours=2)),
+            _make_asset("newest", codec="h264", created_at=now),
+            _make_asset("middle", codec="h264", created_at=now - timedelta(hours=1)),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert result == ["newest", "middle", "oldest"]
+
+    def test_landscape_videos_filtered_out(self):
+        """横屏视频（width > height）被过滤掉."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset("portrait1", codec="h264", width=1080, height=1920),
+            _make_asset("landscape1", codec="h264", width=1920, height=1080),
+            _make_asset("portrait2", codec="h264", width=720, height=1280),
+            _make_asset("landscape2", codec="h264", width=1280, height=720),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert set(result) == {"portrait1", "portrait2"}
+        assert len(result) == 2
+
+    def test_square_videos_allowed(self):
+        """正方形视频（width == height）不被过滤."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset("square", codec="h264", width=720, height=720),
+            _make_asset("portrait", codec="h264", width=1080, height=1920),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert "square" in result
+        assert "portrait" in result
+
+    def test_unknown_size_not_filtered(self):
+        """尺寸未知的素材不被过滤（避免误杀存量数据）."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset("unknown", codec="h264", width=0, height=0),
+            _make_asset("portrait", codec="h264", width=1080, height=1920),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert "unknown" in result
+        assert "portrait" in result
+
+    def test_metadata_size_fallback(self):
+        """width/height字段为空时从metadata兜底读取."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset(
+                "landscape_in_meta",
+                codec="h264",
+                width=0,
+                height=0,
+                metadata={"width": 1920, "height": 1080},
+            ),
+            _make_asset(
+                "portrait_in_meta",
+                codec="h264",
+                width=0,
+                height=0,
+                metadata={"width": 1080, "height": 1920},
+            ),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert "landscape_in_meta" not in result
+        assert "portrait_in_meta" in result
+
+    def test_codec_and_landscape_combined_filter(self):
+        """编码过滤 + 横屏过滤同时生效."""
+        from app.api.routes._helpers import auto_select_video_assets
+
+        assets = [
+            _make_asset("good", codec="h264", width=1080, height=1920),
+            _make_asset("bad_codec", codec="hevc", width=1080, height=1920),
+            _make_asset("bad_landscape", codec="h264", width=1920, height=1080),
+            _make_asset("bad_both", codec="hevc", width=1920, height=1080),
+        ]
+        asset_repo = _make_mock_repo(assets)
+        lib_repo = _make_mock_lib_repo()
+
+        result = auto_select_video_assets(
+            project_id="proj-1",
+            asset_library_repo=lib_repo,
+            asset_repo=asset_repo,
+        )
+
+        assert result == ["good"]

tests/unit/test_edit_plan_adjustments_api.py

@@ -0,0 +1,491 @@
+"""
+片段调整 API 单元测试
+
+覆盖：
+- PUT /clips/{clip_id}/speed - 调速
+- PUT /clips/{clip_id}/volume - 音量调节
+- PUT /clips/{clip_id}/trim - 裁剪
+- PUT /clips/{clip_id}/adjustments - 统一调整
+- POST /{plan_id}/clips/batch-speed - 批量调速
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+from unittest.mock import MagicMock
+
+os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")
+os.environ.setdefault("DATABASE_URL", "sqlite:///test.db")
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from packages.domain.config_schemas import normalize_plan_config
+from packages.domain.edit_plan import EditPlan, EditPlanStatus
+from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
+
+# ---------------------------------------------------------------------------
+# Stub Repository
+# ---------------------------------------------------------------------------
+
+
+class StubEditPlanRepository:
+    def __init__(self, plans: dict[str, EditPlan] | None = None):
+        self._plans = plans or {}
+
+    def get(self, plan_id: str) -> Optional[EditPlan]:
+        return self._plans.get(plan_id)
+
+    def create(self, plan: EditPlan) -> EditPlan:
+        self._plans[plan.id] = plan
+        return plan
+
+    def update(self, plan: EditPlan) -> EditPlan:
+        self._plans[plan.id] = plan
+        return plan
+
+    def list_all(self, *, status=None, skip=0, limit=50):
+        return list(self._plans.values())[skip : skip + limit]
+
+    def list_by_template(self, template_id, *, status=None, skip=0, limit=50):
+        return [p for p in self._plans.values() if p.template_id == template_id][skip : skip + limit]
+
+    def delete(self, plan_id: str) -> bool:
+        return self._plans.pop(plan_id, None) is not None
+
+    def count(self, *, status=None, template_id=None):
+        return len(self._plans)
+
+
+class StubEditPlanClipRepository:
+    def __init__(self, clips: dict[str, EditPlanClip] | None = None):
+        self._clips = clips or {}
+
+    def list_by_plan(self, plan_id, *, status=None, skip=0, limit=100):
+        items = [c for c in self._clips.values() if c.plan_id == plan_id]
+        items.sort(key=lambda c: c.order)
+        return items[skip : skip + limit]
+
+    def count(self, plan_id, *, status=None):
+        return len([c for c in self._clips.values() if c.plan_id == plan_id])
+
+    def get(self, clip_id: str) -> Optional[EditPlanClip]:
+        return self._clips.get(clip_id)
+
+    def create(self, clip: EditPlanClip) -> EditPlanClip:
+        self._clips[clip.id] = clip
+        return clip
+
+    def update(self, clip: EditPlanClip) -> EditPlanClip:
+        self._clips[clip.id] = clip
+        return clip
+
+    def delete(self, clip_id: str) -> bool:
+        return self._clips.pop(clip_id, None) is not None
+
+    def delete_by_plan(self, plan_id: str) -> int:
+        before = len(self._clips)
+        self._clips = {k: v for k, v in self._clips.items() if v.plan_id != plan_id}
+        return before - len(self._clips)
+
+
+# ---------------------------------------------------------------------------
+# Test Fixtures
+# ---------------------------------------------------------------------------
+
+
+def _make_sample_plan(plan_id="plan-001"):
+    return EditPlan(
+        id=plan_id,
+        template_id="tpl-001",
+        name="测试计划",
+        status=EditPlanStatus.EDITING,
+        total_duration=30.0,
+        config=normalize_plan_config({}),
+        project_id="",
+        created_by_user_id="user-001",
+        created_at=datetime(2026, 7, 16, 10, 0, 0),
+        updated_at=datetime(2026, 7, 16, 10, 0, 0),
+    )
+
+
+def _make_clip(clip_id, plan_id="plan-001", order=0, duration=10.0, speed=1.0):
+    return EditPlanClip(
+        id=clip_id,
+        plan_id=plan_id,
+        clip_type="video",
+        order=order,
+        asset_id="asset-001",
+        text_content="",
+        start_time=0.0,
+        duration=duration,
+        transition_effect="cut",
+        transition_duration=0.0,
+        playback_speed=speed,
+        status=EditPlanClipStatus.READY,
+        config={},
+        created_at=datetime(2026, 7, 16, 10, 0, 0),
+        updated_at=datetime(2026, 7, 16, 10, 0, 0),
+    )
+
+
+def _create_test_app():
+    import app.services.edit_plan_service as service_module
+    from app.api.routes.edit_plans import router
+
+    plan = _make_sample_plan()
+    clips = {
+        "clip-001": _make_clip("clip-001", order=0, duration=10.0),
+        "clip-002": _make_clip("clip-002", order=1, duration=15.0),
+        "clip-003": _make_clip("clip-003", order=2, duration=20.0),
+    }
+    stub_plan_repo = StubEditPlanRepository({plan.id: plan})
+    stub_clip_repo = StubEditPlanClipRepository(clips)
+
+    original_plan_repo = service_module.SQLAlchemyEditPlanRepository
+    original_clip_repo = service_module.SQLAlchemyEditPlanClipRepository
+    original_gen_repo = service_module.SQLAlchemyGenerationTaskRepository
+    service_module.SQLAlchemyEditPlanRepository = lambda db: stub_plan_repo
+    service_module.SQLAlchemyEditPlanClipRepository = lambda db: stub_clip_repo
+    service_module.SQLAlchemyGenerationTaskRepository = lambda db: MagicMock()
+
+    app = FastAPI()
+    app.include_router(router, prefix="/api/v1/edit-plans")
+
+    def _mock_auth():
+        mock = MagicMock()
+        mock.user.id = "user-001"
+        return mock
+
+    import app.api.routes._helpers as helpers_module
+
+    original_check = helpers_module.check_project_access
+    helpers_module.check_project_access = lambda *a, **kw: None
+
+    from app.api.routes import edit_plans as main_module
+
+    app.dependency_overrides[main_module.get_current_user] = _mock_auth
+    app.dependency_overrides[main_module.get_db_session] = lambda: MagicMock()
+    app.dependency_overrides[main_module.get_project_repository] = lambda: MagicMock()
+
+    import app.api.routes.edit_plans_adjustments as adj_module
+
+    app.dependency_overrides[adj_module.get_current_user] = _mock_auth
+    app.dependency_overrides[adj_module.get_db_session] = lambda: MagicMock()
+    app.dependency_overrides[adj_module.get_project_repository] = lambda: MagicMock()
+
+    def cleanup():
+        service_module.SQLAlchemyEditPlanRepository = original_plan_repo
+        service_module.SQLAlchemyEditPlanClipRepository = original_clip_repo
+        service_module.SQLAlchemyGenerationTaskRepository = original_gen_repo
+        helpers_module.check_project_access = original_check
+
+    return app, stub_plan_repo, stub_clip_repo, cleanup
+
+
+@pytest.fixture
+def adj_client():
+    app, plan_repo, clip_repo, cleanup = _create_test_app()
+    yield TestClient(app), plan_repo, clip_repo
+    cleanup()
+
+
+# ---------------------------------------------------------------------------
+# 调速测试
+# ---------------------------------------------------------------------------
+
+
+class TestAdjustSpeed:
+    def test_speed_up(self, adj_client):
+        c, _, clip_repo = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/speed",
+            json={"speed": 2.0},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["speed"] == 2.0
+        assert data["clip_id"] == "clip-001"
+
+        clip = clip_repo.get("clip-001")
+        assert clip.playback_speed == 2.0
+
+    def test_slow_down(self, adj_client):
+        c, _, clip_repo = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/speed",
+            json={"speed": 0.5},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["speed"] == 0.5
+
+    def test_speed_clip_not_found(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-nonexist/speed",
+            json={"speed": 1.5},
+        )
+        assert resp.status_code == 404
+
+    def test_speed_out_of_range_low(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/speed",
+            json={"speed": 0.1},
+        )
+        assert resp.status_code == 422
+
+    def test_speed_out_of_range_high(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/speed",
+            json={"speed": 5.0},
+        )
+        assert resp.status_code == 422
+
+    def test_speed_default_value(self, adj_client):
+        c, _, clip_repo = adj_client
+        # 验证默认 speed
+        clip = clip_repo.get("clip-001")
+        assert clip.playback_speed == 1.0
+
+
+# ---------------------------------------------------------------------------
+# 音量调节测试
+# ---------------------------------------------------------------------------
+
+
+class TestAdjustVolume:
+    def test_set_volume(self, adj_client):
+        c, _, clip_repo = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/volume",
+            json={"volume": 0.5},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["volume"] == 0.5
+
+        clip = clip_repo.get("clip-001")
+        assert clip.config["volume"] == 0.5
+
+    def test_mute(self, adj_client):
+        c, _, clip_repo = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/volume",
+            json={"volume": 0.0},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["volume"] == 0.0
+
+    def test_boost_volume(self, adj_client):
+        c, _, clip_repo = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/volume",
+            json={"volume": 1.5},
+        )
+        assert resp.status_code == 200
+        assert resp.json()["volume"] == 1.5
+
+    def test_volume_out_of_range(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/volume",
+            json={"volume": 3.0},
+        )
+        assert resp.status_code == 422
+
+    def test_volume_clip_not_found(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-nonexist/volume",
+            json={"volume": 1.0},
+        )
+        assert resp.status_code == 404
+
+    def test_default_volume(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/speed",
+            json={"speed": 1.0},
+        )
+        data = resp.json()
+        # 默认音量应该是 1.0
+        assert data["volume"] == 1.0
+
+
+# ---------------------------------------------------------------------------
+# 裁剪测试
+# ---------------------------------------------------------------------------
+
+
+class TestAdjustTrim:
+    def test_trim_start(self, adj_client):
+        c, _, clip_repo = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/trim",
+            json={"trim_start": 2.0, "trim_end": 0.0},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["trim_start"] == 2.0
+        assert data["trim_end"] == 0.0
+
+        clip = clip_repo.get("clip-001")
+        assert clip.config["trim_start"] == 2.0
+
+    def test_trim_both_ends(self, adj_client):
+        c, _, clip_repo = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/trim",
+            json={"trim_start": 1.5, "trim_end": 2.5},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["trim_start"] == 1.5
+        assert data["trim_end"] == 2.5
+
+    def test_trim_exceeds_duration(self, adj_client):
+        c, _, _ = adj_client
+        # 片段时长 10 秒，裁剪 8+3 = 11 > 10
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/trim",
+            json={"trim_start": 8.0, "trim_end": 3.0},
+        )
+        assert resp.status_code == 400
+        assert "不能大于等于片段总时长" in resp.json()["detail"]
+
+    def test_trim_clip_not_found(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-nonexist/trim",
+            json={"trim_start": 1.0},
+        )
+        assert resp.status_code == 404
+
+    def test_default_trim_zero(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/speed",
+            json={"speed": 1.0},
+        )
+        data = resp.json()
+        assert data["trim_start"] == 0.0
+        assert data["trim_end"] == 0.0
+
+
+# ---------------------------------------------------------------------------
+# 统一调整测试
+# ---------------------------------------------------------------------------
+
+
+class TestAdjustAll:
+    def test_adjust_speed_and_volume(self, adj_client):
+        c, _, clip_repo = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/adjustments",
+            json={"speed": 1.5, "volume": 0.8},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["speed"] == 1.5
+        assert data["volume"] == 0.8
+
+        clip = clip_repo.get("clip-001")
+        assert clip.playback_speed == 1.5
+        assert clip.config["volume"] == 0.8
+
+    def test_adjust_all_four(self, adj_client):
+        c, _, clip_repo = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/adjustments",
+            json={"speed": 2.0, "volume": 0.5, "trim_start": 1.0, "trim_end": 1.0},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["speed"] == 2.0
+        assert data["volume"] == 0.5
+        assert data["trim_start"] == 1.0
+        assert data["trim_end"] == 1.0
+
+        clip = clip_repo.get("clip-001")
+        assert clip.playback_speed == 2.0
+        assert clip.config["volume"] == 0.5
+        assert clip.config["trim_start"] == 1.0
+        assert clip.config["trim_end"] == 1.0
+
+    def test_adjust_empty_body(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/adjustments",
+            json={},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        # 保持默认值
+        assert data["speed"] == 1.0
+        assert data["volume"] == 1.0
+
+    def test_adjust_trim_exceeds(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-001/adjustments",
+            json={"trim_start": 9.0, "trim_end": 2.0},
+        )
+        assert resp.status_code == 400
+
+    def test_adjust_clip_not_found(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.put(
+            "/api/v1/edit-plans/clips/clip-nonexist/adjustments",
+            json={"speed": 1.5},
+        )
+        assert resp.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# 批量调速测试
+# ---------------------------------------------------------------------------
+
+
+class TestBatchSpeed:
+    def test_batch_speed_all(self, adj_client):
+        c, _, clip_repo = adj_client
+        resp = c.post(
+            "/api/v1/edit-plans/plan-001/clips/batch-speed",
+            json={"speed": 1.5},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["updated_count"] == 3
+        assert data["plan_id"] == "plan-001"
+
+        for cid in ["clip-001", "clip-002", "clip-003"]:
+            clip = clip_repo.get(cid)
+            assert clip.playback_speed == 1.5
+
+    def test_batch_speed_plan_not_found(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.post(
+            "/api/v1/edit-plans/plan-nonexist/clips/batch-speed",
+            json={"speed": 2.0},
+        )
+        assert resp.status_code == 404
+
+    def test_batch_speed_invalid(self, adj_client):
+        c, _, _ = adj_client
+        resp = c.post(
+            "/api/v1/edit-plans/plan-001/clips/batch-speed",
+            json={"speed": 10.0},
+        )
+        assert resp.status_code == 422