fix(ci): auto-fix checkout加--force + black格式对齐

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

.gitea/workflows/auto-approve.yml

@@ -1,174 +0,0 @@
-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

@@ -1,174 +0,0 @@
-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=10
-
-          # 轮询等待，最多30分钟（180次x10秒）
-          for attempt in $(seq 1 180); do
-            ALL_SUCCESS=true
-            ANY_FAILED=false
-            ANY_PENDING=false
-
-            echo "--- 第${attempt}次检查 ($(date '+%H:%M:%S')) ---"
-
-            # 检查CI状态
-            for ctx in "${CONTEXTS[@]}"; do
-              STATE=$(python3 scripts/check_ci_status.py "$GITHUB_TOKEN" "$GITHUB_REPOSITORY" "$PR_HEAD_SHA" "$ctx")
-              echo "  CI: ${ctx##*/}: $STATE"
-              if [ "$STATE" != "success" ]; then
-                ALL_SUCCESS=false
-              fi
-              if [ "$STATE" = "failure" ] || [ "$STATE" = "error" ]; then
-                ANY_FAILED=true
-              fi
-              if [ "$STATE" = "pending" ]; then
-                ANY_PENDING=true
-              fi
-            done
-
-            # 检查审批状态
-            APPROVAL_RESULT=$(python3 scripts/check_pr_approval.py "$MERGE_TOKEN" "$GITHUB_REPOSITORY" "$PR_NUMBER" 1)
-            echo "  审批: $APPROVAL_RESULT"
-            HAS_APPROVAL=false
-            if echo "$APPROVAL_RESULT" | grep -q '^approved'; then
-              HAS_APPROVAL=true
-            fi
-
-            # 全部满足 → 合并
-            if [ "$ALL_SUCCESS" = "true" ] && [ "$HAS_APPROVAL" = "true" ]; then
-              echo
-              echo "CI全绿 + 审批通过，执行自动合并"
-              echo "等待60秒冷却，给Gitea内部状态同步时间..."
-              sleep 60
-
-              # 幂等检查：PR是否还是open
-              PR_STATE=$(curl -s -H "Authorization: token ${MERGE_TOKEN}" \
-                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" \
-                | python3 -c "import sys,json; print(json.load(sys.stdin).get('state',''))")
-
-              if [ "$PR_STATE" != "open" ]; then
-                echo "PR状态为 ${PR_STATE}，无需合并"
-                exit 0
-              fi
-
-              # 执行squash merge
-              HTTP_CODE=$(curl -s -o /tmp/merge_resp.json -w "%{http_code}" \
-                -X POST \
-                -H "Authorization: token ${MERGE_TOKEN}" \
-                -H "Content-Type: application/json" \
-                -d '{"do":"squash","merge_title_field":"","merge_message_field":"","delete_branch_after_merge":true,"force_merge":false}' \
-                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/merge")
-
-              echo "合并API HTTP状态: $HTTP_CODE"
-
-              if [ "$HTTP_CODE" = "200" ]; then
-                echo "自动合并成功"
-                exit 0
-              elif [ "$HTTP_CODE" = "405" ]; then
-                MERGE_405_COUNT=$((MERGE_405_COUNT + 1))
-                echo "⚠️  合并返回405（第${MERGE_405_COUNT}次），可能CI状态尚未同步或有未解决的门禁，继续等待重试..."
-                cat /tmp/merge_resp.json 2>/dev/null || true
-                echo
-                if [ "$MERGE_405_COUNT" -ge "$MAX_405_RETRIES" ]; then
-                  echo "⚠️  连续${MAX_405_RETRIES}次合并返回405，放弃自动合并（需人工确认，非代码问题）"
-                  curl -s -X POST \
-                    -H "Authorization: token ${MERGE_TOKEN}" \
-                    -H "Content-Type: application/json" \
-                    -d '{"body": "Auto merge skipped after multiple 405 errors: PR may have conflicts or unresolved checks. Please review manually. This is not a CI failure."}' \
-                    "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null 2>&1 || true
-                  exit 0
-                fi
-                sleep 30
-                continue
-              else
-                echo "自动合并失败 (HTTP $HTTP_CODE)"
-                cat /tmp/merge_resp.json 2>/dev/null || true
-                curl -s -X POST \
-                  -H "Authorization: token ${MERGE_TOKEN}" \
-                  -H "Content-Type: application/json" \
-                  -d "{\"body\": \"Auto merge failed (HTTP ${HTTP_CODE}), please check manually.\"}" \
-                  "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null 2>&1 || true
-                exit 1
-              fi
-            else
-              # 本轮不满足合并条件，重置405计数器
-              MERGE_405_COUNT=0
-            fi
-
-            if [ "$ANY_FAILED" = "true" ]; then
-              echo
-              echo "CI有失败项，不自动合并"
-              exit 0
-            fi
-
-            sleep 10
-          done
-
-          echo
-          echo "等待超时（30分钟）"
-          exit 0

.gitea/workflows/ci-cd.yml

@@ -1,640 +0,0 @@
-name: CI/CD Pipeline
-on:
-  push:
-    branches:
-    - main
-    - develop
-    tags:
-    - v*
-  pull_request:
-    branches:
-    - main
-    - develop
-  workflow_dispatch:
-    inputs:
-      reason:
-        description: "触发原因"
-        required: false
-        default: "手动触发 - CI漏触发补跑"
-permissions:
-  contents: read
-concurrency:
-  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 }}
-      skip_frontend: ${{ steps.check.outputs.skip_frontend }}
-    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 "skip_frontend=false" >> $GITHUB_OUTPUT
-          echo "✅ 纯前端改动，跳过后端检查"
-        elif [ "$FRONTEND_COUNT" = "0" ] && [ "$BACKEND_COUNT" -gt "0" ]; then
-          echo "skip_backend=false" >> $GITHUB_OUTPUT
-          echo "skip_frontend=true" >> $GITHUB_OUTPUT
-          echo "🔧 纯后端改动，跳过前端检查"
-        else
-          echo "skip_backend=false" >> $GITHUB_OUTPUT
-          echo "skip_frontend=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: 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'
-    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: Record job start time
-      shell: sh
-      run: 'set -eu
-
-        echo "JOB_START_TIME=$(date +%s)" >> $GITHUB_ENV
-
-        echo "Job started at $(date)"
-
-        '
-    - name: Verify CI environment
-      shell: sh
-      run: 'set -eu
-
-        python3 --version
-
-        python3 -m pip --version
-
-        echo "CI environment is ready"
-
-        '
-    - name: Install dependencies
-      shell: sh
-      run: 'set -eu
-
-        python3 -m pip install -q -r requirements-base.txt
-
-        python3 -m pip install -q -r requirements.txt
-
-        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
-
-        python3 -m ruff --version
-
-        bandit --version
-
-        pytest --version
-
-        '
-    - name: Secret detection (detect-secrets)
-      shell: sh
-      run: "set -eu\necho \"=== Installing detect-secrets ===\"\npython3 -m pip install -q detect-secrets\ndetect-secrets --version\necho \"\"\necho \"=== Running secret scan ===\"\ndetect-secrets scan \\\n  --all-files \\\n  --exclude-files '(^|/)(tests|test|e2e|__tests__|spec|docs|node_modules|site-packages|migrations|alembic|.gitea|.git|.pytest_cache|.next|dist|build)/' \\\n  --exclude-files '\\.(md|rst|txt|lock|example|sample|min\\.js|min\\.css|spec\\.ts|test\\.ts|test\\.py)$' \\\n  --exclude-files '(package-lock|yarn\\.lock|poetry\\.lock|Pipfile\\.lock)$' \\\n  --disable-plugin Base64HighEntropyString \\\n  --disable-plugin HexHighEntropyString \\\n  --disable-plugin BasicAuthDetector \\\n  --disable-plugin KeywordDetector \\\n  --disable-plugin IPPublicDetector \\\n  > /tmp/secrets-scan.json 2>&1\n\nFOUND=$(python3 -c \"\nimport json\ntry:\n    with open('/tmp/secrets-scan.json') as f:\n        data = json.load(f)\n    results = data.get('results', {})\n    total = sum(len(v) for\
-        \ v in results.values())\n    print(total)\nexcept Exception:\n    print('error')\n\")\necho \"\"\necho \"Secrets detected: $FOUND\"\nif [ \"$FOUND\" != \"0\" ] && [ \"$FOUND\" != \"error\" ]; then\n  echo \"\"\n  echo \"=== Secret details ===\"\n  python3 -c \"\nimport json\nwith open('/tmp/secrets-scan.json') as f:\n    data = json.load(f)\nfor fpath, items in data.get('results', {}).items():\n    for item in items:\n        line = item.get('line_number', '?')\n        stype = item.get('type', '?')\n        hashed = item.get('hashed_secret', '')[:16]\n        print(f'  {fpath}:{line} [{stype}] {hashed}...')\n\"\n  echo \"\"\n  echo \"ERROR: Potential secrets detected in code!\"\n  echo \"If these are false positives, add exclusions in the CI workflow.\"\n  exit 1\nfi\necho \"Secret scan completed - no secrets detected\"\n"
-    - name: Calculate changed Python files (incremental scan)
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: "set -eu\nSCAN_MODE=\"full\"\nCHANGED_PY_FILES=\"\"\n\nif [ \"${GITHUB_EVENT_NAME:-}\" = \"pull_request\" ] && [ -n \"${GITHUB_REF_NAME:-}\" ]; then\n  echo \"PR mode (#${GITHUB_REF_NAME}) - fetching changed files from API\"\n\n  PR_NUMBER=$(echo \"$GITHUB_REF\" | sed 's|refs/pull/||; s|/.*||')\n  API_URL=\"${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?limit=100\"\n\n  set +e\n  RESPONSE=$(curl -s -w \"\\n%{http_code}\" -H \"Authorization: token ${GITHUB_TOKEN}\" \"${API_URL}\")\n  HTTP_CODE=$(echo \"$RESPONSE\" | tail -n1)\n  BODY=$(echo \"$RESPONSE\" | sed '$d')\n  set -e\n\n  if [ \"$HTTP_CODE\" = \"200\" ]; then\n    CHANGED_PY_FILES=$(echo \"$BODY\" | python3 -c \"\nimport json, sys\ntry:\n    files = json.load(sys.stdin)\n    py_files = [f['filename'] for f in files\n                if f['filename'].endswith('.py') and f['status'] != 'removed']\n    print(' '.join(py_files))\nexcept Exception:\n    print('')\n\")\n    if [ -n \"$CHANGED_PY_FILES\" ]; then\n      SCAN_MODE=\"incremental\"\n      FILE_COUNT=$(echo \"$CHANGED_PY_FILES\" | wc -w)\n      echo \"Changed Python files: ${FILE_COUNT}\"\n      echo \"$CHANGED_PY_FILES\" | tr ' ' '\\n' | grep -v '^$'\n    else\n      SCAN_MODE=\"skip_py\"\n      echo \"No Python files changed in this PR\"\n    fi\n  else\n    echo \"WARN: API returned HTTP $HTTP_CODE, falling back to full scan\"\n  fi\nelse\n  echo \"Full scan mode (not a PR event)\"\nfi\n\necho \"SCAN_MODE=$SCAN_MODE\" >> $GITHUB_ENV\necho \"CHANGED_PY_FILES=$CHANGED_PY_FILES\" >> $GITHUB_ENV\n"
-    - 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
-      run: "bash scripts/ci/mypy_check.sh"
-    - name: Run security scan (bandit)
-      shell: sh
-      run: 'set -eu
-
-        bandit -r apps packages -q -ll
-
-        '
-    - name: Python dependency vulnerability scan (pip-audit)
-      shell: sh
-      run: "set -eu\necho \"=== Installing pip-audit ===\"\npython3 -m pip install -q pip-audit\npip-audit --version\necho \"\"\necho \"=== Scanning Python dependencies ===\"\nEXIT_CODE=0\nfor req_file in requirements.txt requirements-base.txt requirements-dev.txt; do\n  if [ -f \"$req_file\" ]; then\n    echo \"--- Scanning $req_file ---\"\n    pip-audit -r \"$req_file\" --desc on 2>&1 | head -40 || EXIT_CODE=$?\n    echo \"\"\n  fi\ndone\necho \"pip-audit scan completed (advisory mode - warnings only, not blocking CI)\"\nif [ \"$EXIT_CODE\" != \"0\" ]; then\n  echo \"WARNING: Potential vulnerabilities found in dependencies.\"\nfi\nexit 0\n"
-    - name: Dead code detection (vulture)
-      if: always()
-      shell: sh
-      run: "set +e\necho \"=== Installing vulture ===\"\npython3 -m pip install -q vulture\nvulture --version\necho \"\"\necho \"=== Running vulture dead code scan (confidence >= 70%) ===\"\necho \"告警模式，不阻断CI。置信度>=90%建议尽快确认。\"\necho \"\"\n# 按置信度从高到低输出，便于优先查看高价值条目\nvulture apps packages scripts \\\n  --exclude \"tests,test,migrations,.gitea,docs,node_modules,site-packages,*/test_*.py,*/conftest.py\" \\\n  --min-confidence 70 \\\n  2>&1 | sort -t'(' -k2 -rn | head -80\nEXIT_CODE=$?\necho \"\"\necho \"=== vulture scan summary ===\"\nif [ \"$EXIT_CODE\" != \"0\" ]; then\n  echo \"发现潜在死代码（可能包含框架装饰器注册的函数，为误报）\"\n  echo \"建议：定期人工审查高置信度（>=90%）条目\"\nelse\n  echo \"未发现明显死代码 ✅\"\nfi\nexit 0\n"
-    - name: Validate release scripts syntax
-      shell: sh
-      run: 'set -eu
-
-        bash -n scripts/backup_postgres.sh
-
-        bash -n scripts/restore_postgres_plan.sh
-
-        bash -n scripts/init_production_env.sh
-
-        '
-    - name: Validate Alembic migrations (with isolated PG)
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: |
-        set -eu
-        PG_CONTAINER=ci-pg-validate-${GITHUB_RUN_ID:-$$}
-        docker rm -f "$PG_CONTAINER" 2>/dev/null || true
-        docker run -d --name "$PG_CONTAINER" \
-          --shm-size=256m \
-          -e POSTGRES_USER=postgres \
-          -e POSTGRES_PASSWORD=postgres \
-          -e POSTGRES_DB=xiaoxia_saas \
-          -P \
-          --health-cmd "pg_isready -U postgres" \
-          --health-interval 3s \
-          --health-timeout 3s \
-          --health-retries 20 \
-          postgres:16-alpine
-        PG_PORT=$(docker port "$PG_CONTAINER" 5432/tcp | cut -d: -f2)
-        echo "PostgreSQL port: $PG_PORT"
-        export DATABASE_URL=postgresql+psycopg://postgres:postgres@127.0.0.1:$PG_PORT/xiaoxia_saas
-        for i in $(seq 1 30); do
-          if docker inspect --format='{{.State.Health.Status}}' "$PG_CONTAINER" 2>/dev/null | grep -q healthy; then
-            echo "PostgreSQL is ready on port $PG_PORT"
-            break
-          fi
-            echo "Waiting for PostgreSQL... ($i/30)"
-          sleep 2
-        done
-        docker inspect --format='{{.State.Health.Status}}' "$PG_CONTAINER" | grep -q healthy
-        python3 -m alembic upgrade head --sql > /tmp/alembic-upgrade.sql
-        test -s /tmp/alembic-upgrade.sql
-        grep -q "Running upgrade" /tmp/alembic-upgrade.sql
-        python3 scripts/check_schema_metadata.py
-        # Initialize git for migration safety diff (CI checkout is tar.gz without .git)
-        git init > /dev/null 2>&1
-        git remote add origin https://git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas.git > /dev/null 2>&1
-        git fetch origin develop:refs/remotes/origin/develop --depth=100 > /dev/null 2>&1
-        git add -A > /dev/null 2>&1
-        git -c user.email=ci@local -c user.name=CI commit -m "ci-tmp" > /dev/null 2>&1
-        python3 scripts/check_migration_safety.py --allow-medium-risk --diff-against origin/develop
-        docker rm -f "$PG_CONTAINER" 2>/dev/null || true
-        echo "PostgreSQL container cleaned up"
-
-    - name: Job duration summary
-      if: always()
-      shell: sh
-      run: "set +eu\nif [ -n \"$JOB_START_TIME\" ]; then\n  END_TIME=$(date +%s)\n  DURATION=$((END_TIME - JOB_START_TIME))\n  MINS=$((DURATION / 60))\n  SECS=$((DURATION % 60))\n  echo \"JOB_DURATION_SECONDS=$DURATION\" >> $GITHUB_ENV\n  echo \"=== Job Duration: ${MINS}m${SECS}s ===\"\nelse\n  echo \"JOB_DURATION_SECONDS=0\" >> $GITHUB_ENV\n  echo \"=== Job Duration: unknown ===\"\nfi\n"
-    - name: Notify on failure
-      continue-on-error: true
-      if: failure()
-      shell: sh
-      env:
-        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
-      run: 'set +e
-
-        NOTIFY_MODE=failure JOB_NAME="Validate Code Quality And Tests" python3 scripts/ci_notify.py
-
-        '
-  unit-tests:
-    needs: check-frontend-only
-    if: always() && needs.check-frontend-only.outputs.skip_backend != 'true'
-    name: Unit Tests
-    runs-on: ci-l2
-    timeout-minutes: 8
-    env:
-      USE_IN_MEMORY_DB: 'true'
-      OSS_ACCESS_KEY_ID: placeholder
-      OSS_ACCESS_KEY_SECRET: placeholder
-      OSS_BUCKET_NAME: xiaoxia-autocut
-      OSS_ENDPOINT: oss-cn-hangzhou.aliyuncs.com
-    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: Record job start time
-      shell: sh
-      run: 'set -eu
-
-        echo "JOB_START_TIME=$(date +%s)" >> $GITHUB_ENV
-
-        echo "Job started at $(date)"
-
-        '
-    - name: Install ffmpeg
-      shell: sh
-      run: "set +e\nif command -v ffmpeg > /dev/null 2>&1; then\n  echo \"ffmpeg already installed: $(ffmpeg -version | head -1)\"\n  exit 0\nfi\nif command -v apt-get > /dev/null 2>&1; then\n  apt-get update -qq && apt-get install -y -qq ffmpeg\nelif command -v yum > /dev/null 2>&1; then\n  yum install -y -q epel-release 2>/dev/null\n  yum install -y -q ffmpeg 2>/dev/null\n  if [ $? -ne 0 ] && command -v dnf > /dev/null 2>&1; then\n    dnf install -y -q --nogpgcheck https://download1.rpmfusion.org/free/el/rpmfusion-free-release-$(rpm -E %rhel).noarch.rpm 2>/dev/null\n    dnf install -y -q ffmpeg 2>/dev/null\n  fi\nelif command -v dnf > /dev/null 2>&1; then\n  dnf install -y -q ffmpeg 2>/dev/null\nfi\nif command -v ffmpeg > /dev/null 2>&1; then\n  echo \"ffmpeg installed successfully: $(ffmpeg -version | head -1)\"\nelse\n  echo \"Warning: ffmpeg installation failed or not available, some tests may be skipped\"\nfi\n"
-    - name: Install dependencies
-      shell: sh
-      run: 'set -eu
-
-        python3 -m pip install -q -r requirements-base.txt
-
-        python3 -m pip install -q -r requirements.txt
-
-        python3 -m pip install -q -r requirements-dev.txt
-
-        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
-        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
-      env:
-        GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
-        CI_WEBHOOK_URL: ${{ secrets.CI_WEBHOOK_URL }}
-      run: 'set +e
-
-        FAILED_JOB="Unit Tests" python3 scripts/ci_notify_failure.py
-
-        '
-    - name: Job duration summary
-      if: always()
-      shell: sh
-      run: "set +eu\nif [ -n \"$JOB_START_TIME\" ]; then\n  END_TIME=$(date +%s)\n  DURATION=$((END_TIME - JOB_START_TIME))\n  MINS=$((DURATION / 60))\n  SECS=$((DURATION % 60))\n  echo \"JOB_DURATION_SECONDS=$DURATION\" >> $GITHUB_ENV\n  echo \"=== Job Duration: ${MINS}m${SECS}s ===\"\nelse\n  echo \"JOB_DURATION_SECONDS=0\" >> $GITHUB_ENV\n  echo \"=== Job Duration: unknown ===\"\nfi\n"
-    - 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="Unit Tests" python3 scripts/ci_notify.py
-
-        '
-  integration-tests:
-    name: Integration Tests
-    runs-on: ci-l2
-    timeout-minutes: 30
-    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'
-      OSS_ACCESS_KEY_ID: placeholder
-      OSS_ACCESS_KEY_SECRET: placeholder
-      OSS_BUCKET_NAME: xiaoxia-autocut
-      OSS_ENDPOINT: oss-cn-hangzhou.aliyuncs.com
-    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: Record job start time
-      shell: sh
-      run: 'set -eu
-
-        echo "JOB_START_TIME=$(date +%s)" >> $GITHUB_ENV
-
-        echo "Job started at $(date)"
-
-        '
-    - name: Verify CI environment
-      shell: sh
-      run: 'set -eu
-
-        python3 --version
-
-        python3 -m pip --version
-
-        echo "CI environment is ready"
-
-        '
-    - name: Install dependencies
-      shell: sh
-      run: 'set -eu
-
-        python3 -m pip install -q -r requirements-base.txt
-
-        python3 -m pip install -q -r requirements.txt
-
-        python3 -m pip install -q -r requirements-dev.txt
-
-        pytest --version
-
-        '
-    - name: Install ffmpeg
-      shell: sh
-      run: "set +e\nif command -v ffmpeg > /dev/null 2>&1; then\n  echo \"ffmpeg already installed: $(ffmpeg -version | head -1)\"\n  exit 0\nfi\nif command -v apt-get > /dev/null 2>&1; then\n  apt-get update -qq && apt-get install -y -qq ffmpeg\nelif command -v yum > /dev/null 2>&1; then\n  yum install -y -q epel-release 2>/dev/null\n  yum install -y -q ffmpeg 2>/dev/null\n  if [ $? -ne 0 ] && command -v dnf > /dev/null 2>&1; then\n    dnf install -y -q --nogpgcheck https://download1.rpmfusion.org/free/el/rpmfusion-free-release-$(rpm -E %rhel).noarch.rpm 2>/dev/null\n    dnf install -y -q ffmpeg 2>/dev/null\n  fi\nelif command -v dnf > /dev/null 2>&1; then\n  dnf install -y -q ffmpeg 2>/dev/null\nfi\nif command -v ffmpeg > /dev/null 2>&1; then\n  echo \"ffmpeg installed successfully: $(ffmpeg -version | head -1)\"\nelse\n  echo \"Warning: ffmpeg installation failed or not available, some tests may be skipped\"\nfi\n"
-    - name: Start Redis
-      shell: sh
-      run: "set -eu\nREDIS_CONTAINER=\"ci-redis-${GITHUB_RUN_ID:-$$}\"\necho \"REDIS_CONTAINER=$REDIS_CONTAINER\" >> \"$GITHUB_ENV\"\ndocker rm -f \"$REDIS_CONTAINER\" 2>/dev/null || true\ndocker run -d --name \"$REDIS_CONTAINER\" \\\n  -P \\\n  --health-cmd \"redis-cli ping\" \\\n  --health-interval 2s \\\n  --health-timeout 2s \\\n  --health-retries 10 \\\n  redis:7-alpine\nREDIS_PORT=$(docker port \"$REDIS_CONTAINER\" 6379/tcp | cut -d: -f2)\necho \"Redis port: $REDIS_PORT\"\necho \"REDIS_URL=redis://127.0.0.1:$REDIS_PORT/0\" >> \"$GITHUB_ENV\"\nfor i in $(seq 1 15); do\n  if docker inspect --format='{{.State.Health.Status}}' \"$REDIS_CONTAINER\" 2>/dev/null | grep -q healthy; then\n    echo \"Redis is ready on port $REDIS_PORT\"\n    break\n  fi\n  echo \"Waiting for Redis... ($i/15)\"\n  sleep 2\ndone\ndocker inspect --format='{{.State.Health.Status}}' \"$REDIS_CONTAINER\" | grep -q healthy\n"
-    - name: Start PostgreSQL for integration tests
-      shell: sh
-      run: "set -eu\nPG_CONTAINER=\"ci-pg-${GITHUB_RUN_ID:-$$}\"\necho \"PG_CONTAINER=$PG_CONTAINER\" >> \"$GITHUB_ENV\"\ndocker rm -f \"$PG_CONTAINER\" 2>/dev/null || true\ndocker run -d --name \"$PG_CONTAINER\" \\\n  --shm-size=256m \\\n  -e POSTGRES_USER=postgres \\\n  -e POSTGRES_PASSWORD=postgres \\\n  -e POSTGRES_DB=xiaoxia_saas \\\n  -P \\\n  --health-cmd \"pg_isready -U postgres\" \\\n  --health-interval 5s \\\n  --health-timeout 5s \\\n  --health-retries 12 \\\n  postgres:16\n# 获取随机映射的端口\nPG_PORT=$(docker port \"$PG_CONTAINER\" 5432/tcp | cut -d: -f2)\necho \"PostgreSQL port: $PG_PORT\"\necho \"DATABASE_URL=postgresql+psycopg://postgres:postgres@127.0.0.1:$PG_PORT/xiaoxia_saas\" >> \"$GITHUB_ENV\"\nfor i in $(seq 1 30); do\n  if docker inspect --format='{{.State.Health.Status}}' \"$PG_CONTAINER\" 2>/dev/null | grep -q healthy; then\n    echo \"PostgreSQL is ready on port $PG_PORT\"\n    break\n  fi\n  echo \"Waiting for PostgreSQL... ($i/30)\"\n  sleep 2\ndone\ndocker inspect --format='{{.State.Health.Status}}'\
-        \ \"$PG_CONTAINER\" | grep -q healthy\n"
-    - name: Apply migrations for integration tests
-      shell: sh
-      run: 'set -eu
-
-        PYTHONPATH="$PWD/apps/api:$PWD" python3 -m alembic upgrade head
-
-        '
-    - name: Run integration tests
-      shell: sh
-      run: "set -eu\npython3 -m pip install -q pytest-rerunfailures\nPYTHONPATH=\"$PWD/apps/api:$PWD\" python3 -m coverage run --append \\\n  --source=apps/api/app,packages \\\n  --omit=\"*/migrations/*,*/tests/*,*/test_*.py,*/site-packages/*\" \\\n  --branch \\\n  -m pytest tests/integration -q --timeout=60 -x --reruns 2 --reruns-delay 1 -m \"not performance\"\npython3 -m coverage report --show-missing\npython3 -m coverage xml -o coverage.xml\npython3 -m coverage report --fail-under=40 > /dev/null  # 集成测试覆盖率门槛较低，核心目标是功能验证\n"
-    - name: Run API performance baseline tests
-      shell: sh
-      continue-on-error: true
-      run: "set +e\necho \"=== API 性能基线测试 ===\"\nPERF_OUTPUT=$(mktemp)\nPYTHONPATH=\"$PWD/apps/api:$PWD\" python3 -m pytest tests/integration/test_api_performance.py \\\n  -v --timeout=120 -p no:cacheprovider 2>&1 | tee \"$PERF_OUTPUT\"\nPERF_EXIT=$?\n\n# 提取性能统计\necho \"\"\necho \"=== 性能测试摘要 ===\"\ngrep \"PERF_STATS:\" \"$PERF_OUTPUT\" || echo \"PERF_STATS: 未找到统计数据\"\ngrep \"PERF_RESULT:\" \"$PERF_OUTPUT\" || echo \"PERF_RESULT: 未找到详细结果\"\n\n# 统计通过率\nTOTAL=$(grep -c \"PERF_RESULT:\" \"$PERF_OUTPUT\" || echo 0)\nPASSED=$(grep \"PERF_RESULT: PASS\" \"$PERF_OUTPUT\" | wc -l)\nFAILED=$(grep \"PERF_RESULT: FAIL\" \"$PERF_OUTPUT\" | wc -l)\n\necho \"\"\necho \"性能测试结果: $PASSED/$TOTAL 通过, $FAILED 未达标\"\n\nif [ \"$FAILED\" -gt 0 ]; then\n  echo \"\"\n  echo \"⚠️  警告: $FAILED 个接口性能未达标，请关注以下接口:\"\n  grep \"PERF_RESULT: FAIL\" \"$PERF_OUTPUT\" | while read line; do\n    echo \"   $line\"\n  done\n  echo \"\"\n  echo \"性能测试失败不阻塞主流水线，但建议尽快优化。\"\nelse\n  echo \"✅ 所有接口性能达标！\"\nfi\n\nrm -f \"$PERF_OUTPUT\"\
-        \n# 始终返回 0，不阻塞流水线\nexit 0\n"
-    - name: Cleanup PostgreSQL & Redis
-      if: always()
-      shell: sh
-      run: 'docker rm -f "${PG_CONTAINER:-ci-pg-validate}" 2>/dev/null || true
-
-        docker rm -f "${REDIS_CONTAINER:-ci-redis-int}" 2>/dev/null || true
-
-        echo "PostgreSQL container cleaned up"
-
-        echo "Redis container cleaned up"
-
-        '
-    - name: Coverage summary
-      if: always()
-      shell: sh
-      env:
-        COVERAGE_THRESHOLD: '40'
-      run: 'set +e
-
-        echo "=== 覆盖率汇总 ==="
-
-        python3 scripts/ci_coverage_summary.py
-
-        '
-    - name: Job duration summary
-      if: always()
-      shell: sh
-      run: "set +eu\nif [ -n \"$JOB_START_TIME\" ]; then\n  END_TIME=$(date +%s)\n  DURATION=$((END_TIME - JOB_START_TIME))\n  MINS=$((DURATION / 60))\n  SECS=$((DURATION % 60))\n  echo \"JOB_DURATION_SECONDS=$DURATION\" >> $GITHUB_ENV\n  echo \"=== Job Duration: ${MINS}m${SECS}s ===\"\nelse\n  echo \"JOB_DURATION_SECONDS=0\" >> $GITHUB_ENV\n  echo \"=== Job Duration: unknown ===\"\nfi\n"
-    - 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="Integration Tests" python3 scripts/ci_notify.py
-
-        '
-  frontend-lint:
-    name: Frontend Lint
-    runs-on: ci-check
-    timeout-minutes: 10
-    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: Record job start time
-      shell: sh
-      run: 'set -eu
-
-        echo "JOB_START_TIME=$(date +%s)" >> $GITHUB_ENV
-
-        echo "Job started at $(date)"
-
-        '
-    - name: Install dependencies
-      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 '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 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"
-    - name: Run Prettier 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 prettier --check \"src/**/*.{ts,tsx,md}\"'\n"
-    - name: Run Vitest tests
-      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 vitest run src/test'\n"
-    - name: Job duration summary
-      if: always()
-      shell: sh
-      run: "set +eu\nif [ -n \"$JOB_START_TIME\" ]; then\n  END_TIME=$(date +%s)\n  DURATION=$((END_TIME - JOB_START_TIME))\n  MINS=$((DURATION / 60))\n  SECS=$((DURATION % 60))\n  echo \"JOB_DURATION_SECONDS=$DURATION\" >> $GITHUB_ENV\n  echo \"=== Job Duration: ${MINS}m${SECS}s ===\"\nelse\n  echo \"JOB_DURATION_SECONDS=0\" >> $GITHUB_ENV\n  echo \"=== Job Duration: unknown ===\"\nfi\n"
-    - 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="Frontend Lint" python3 scripts/ci_notify.py
-
-        '
-
-
-  frontend-unit-test:
-    name: Frontend Unit Tests
-    runs-on: ci-check
-    timeout-minutes: 15
-    needs: check-frontend-only
-    if: always() && needs.check-frontend-only.outputs.skip_frontend != 'true'
-    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: Record job start time
-      shell: sh
-      run: 'set -eu
-
-        echo "JOB_START_TIME=$(date +%s)" >> $GITHUB_ENV
-
-        echo "Job started at $(date)"
-
-        '
-    - name: Install dependencies
-      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 '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/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\n  if [ ! -x \"node_modules/.bin/vitest\" ]; then\n    echo \"Post-install check failed: vitest 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 Vitest with coverage
-      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 vitest run --coverage'\n"
-    - name: Job duration summary
-      if: always()
-      shell: sh
-      run: "set +eu\nif [ -n \"$JOB_START_TIME\" ]; then\n  END_TIME=$(date +%s)\n  DURATION=$((END_TIME - JOB_START_TIME))\n  MINS=$((DURATION / 60))\n  SECS=$((DURATION % 60))\n  echo \"JOB_DURATION_SECONDS=$DURATION\" >> $GITHUB_ENV\n  echo \"=== Job Duration: ${MINS}m${SECS}s ===\"\nelse\n  echo \"JOB_DURATION_SECONDS=0\" >> $GITHUB_ENV\n  echo \"=== Job Duration: unknown ===\"\nfi\n"
-    - 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="Frontend Unit Tests" python3 scripts/ci_notify.py
-
-        '

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

@@ -34,3 +34,15 @@ jobs:
           python3 scripts/ci_trigger_monitor.py
           # 监控脚本永远不fail，避免告警风暴
           exit 0
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ ${{ job.status }} = "success" ] || STATUS="error"
+          START_TIME=""
+          [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+

.gitea/workflows/code-review.yml

@@ -51,3 +51,15 @@ jobs:
           python3 scripts/ci_code_review.py
         # 审查脚本异常不影响 CI 通过
         continue-on-error: true
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ ${{ job.status }} = "success" ] || STATUS="error"
+          START_TIME=""
+          [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+

.gitea/workflows/daily-check.yml

@@ -106,6 +106,18 @@ jobs:
           echo "======================================"
           exit $SMOKE_EXIT
 
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ ${{ job.status }} = "success" ] || STATUS="error"
+          START_TIME=""
+          [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+
   # ── 2. Staging API 集成测试 ─────────────────────────────────────────
   staging-api-tests:
     name: Staging API Integration Tests
@@ -243,6 +255,18 @@ jobs:
             echo "report=FAIL" >> "${GITHUB_OUTPUT}"
           fi
 
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ ${{ job.status }} = "success" ] || STATUS="error"
+          START_TIME=""
+          [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+
   # ── 3. Staging 浏览器 E2E ──────────────────────────────────────────
   staging-e2e:
     name: Staging Browser E2E
@@ -332,6 +356,18 @@ jobs:
           echo "=========================================="
           exit $EXIT_CODE
 
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ ${{ job.status }} = "success" ] || STATUS="error"
+          START_TIME=""
+          [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+
   # ── 4. 性能基线巡检 ────────────────────────────────────────────────
   performance-check:
     name: Performance Baseline Check
@@ -580,6 +616,18 @@ jobs:
             exit 0
           fi
 
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ ${{ job.status }} = "success" ] || STATUS="error"
+          START_TIME=""
+          [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+
   # ── 5. 每日巡检汇总报告 ────────────────────────────────────────────
   daily-report:
     name: Daily Check Report
@@ -656,3 +704,15 @@ jobs:
             # 不 exit 1，因为我们用了 always()，保持 report job 成功，
             # 但其他失败的 job 已经让整体流水线标记为失败
           fi
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ ${{ job.status }} = "success" ] || STATUS="error"
+          START_TIME=""
+          [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+

.gitea/workflows/pr-automation.yml

@@ -0,0 +1,369 @@
+name: PR Automation
+
+on:
+  pull_request:
+    types: [synchronize, opened, ready_for_review, review_requested]
+
+permissions:
+  contents: read
+
+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: |
+          curl -sH "Authorization: token $GITHUB_TOKEN"             "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}"             | bash
+
+      - 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的时间
+          echo "等待30秒让CI启动..."
+          sleep 30
+
+          # 轮询等待，最多20分钟（120次x10秒）
+          for attempt in $(seq 1 120); do
+            ALL_SUCCESS=true
+            ANY_FAILED=false
+            ANY_PENDING=false
+
+            echo "--- 第${attempt}次检查 ($(date '+%H:%M:%S')) ---"
+
+            # 调用辅助脚本检查每个context状态
+            for ctx in "${CONTEXTS[@]}"; do
+              STATE=$(python3 scripts/check_ci_status.py "$GITHUB_TOKEN" "$GITHUB_REPOSITORY" "$PR_HEAD_SHA" "$ctx")
+              echo "  $ctx: $STATE"
+
+              if [ "$STATE" != "success" ]; then
+                ALL_SUCCESS=false
+              fi
+              if [ "$STATE" = "failure" ] || [ "$STATE" = "error" ]; then
+                ANY_FAILED=true
+              fi
+              if [ "$STATE" = "pending" ] || [ "$STATE" = "null" ]; then
+                ANY_PENDING=true
+              fi
+            done
+
+            if [ "$ALL_SUCCESS" = "true" ]; then
+              echo
+              echo "✅ 所有CI检查通过，自动审批 PR #${PR_NUMBER}"
+
+              # 检查是否已有审批
+              EXISTING=$(curl -s -H "Authorization: token ${REVIEW_TOKEN}" \
+                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews" \
+                | python3 -c "import sys,json; reviews=json.load(sys.stdin); print('yes' if any(r.get('state')=='APPROVED' for r in reviews) else 'no')")
+
+              if [ "$EXISTING" = "yes" ]; then
+                echo "ℹ️  PR #${PR_NUMBER} 已有审批，跳过"
+                exit 0
+              fi
+
+              # 第一步：创建PENDING review
+              echo "创建review..."
+              REVIEW_CREATE=$(curl -s -X POST \
+                -H "Authorization: token ${REVIEW_TOKEN}" \
+                -H "Content-Type: application/json" \
+                -d '{"event": "PENDING", "body": "CI全绿，自动审批通过。"}' \
+                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews")
+              
+              REVIEW_ID=$(echo "$REVIEW_CREATE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))")
+              REVIEW_STATE=$(echo "$REVIEW_CREATE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('state',''))")
+              echo "创建结果: id=$REVIEW_ID state=$REVIEW_STATE"
+
+              if [ -z "$REVIEW_ID" ]; then
+                echo "❌ 创建review失败"
+                echo "$REVIEW_CREATE"
+                exit 1
+              fi
+
+              if [ "$REVIEW_STATE" = "APPROVED" ]; then
+                echo "✅ 自动审批成功（直接创建为APPROVED）"
+                exit 0
+              fi
+
+              # 第二步：submit review为APPROVED
+              echo "提交review审批..."
+              SUBMIT_CODE=$(curl -s -o /tmp/submit_resp.json -w "%{http_code}" \
+                -X POST \
+                -H "Authorization: token ${REVIEW_TOKEN}" \
+                -H "Content-Type: application/json" \
+                -d '{"event": "APPROVED", "body": "CI全绿，自动审批通过。"}' \
+                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews/${REVIEW_ID}")
+              
+              echo "提交API HTTP状态: $SUBMIT_CODE"
+              cat /tmp/submit_resp.json 2>/dev/null || true
+              echo
+
+              if [ "$SUBMIT_CODE" = "200" ] || [ "$SUBMIT_CODE" = "201" ]; then
+                FINAL_STATE=$(python3 -c "import json; print(json.load(open('/tmp/submit_resp.json')).get('state',''))" 2>/dev/null || echo "?")
+                echo "✅ 自动审批成功 (state: $FINAL_STATE)"
+                exit 0
+              else
+                echo "❌ 提交审批失败"
+                exit 1
+              fi
+            fi
+
+            # 还有CI在跑 → 继续等
+            if [ "$ANY_PENDING" = "true" ]; then
+              echo "⏳ CI仍在运行中，继续等待（第${attempt}/120次轮询）..."
+              sleep 10
+              continue
+            fi
+
+            # 所有CI都跑完了但有失败 → 退出
+            if [ "$ANY_FAILED" = "true" ]; then
+              echo
+              echo "❌ CI检查有失败项，不自动审批"
+              exit 0
+            fi
+
+            sleep 10
+          done
+
+          echo
+          echo "⏰ 等待超时（20分钟），CI尚未全部完成"
+          exit 0
+
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ ${{ job.status }} = "success" ] || STATUS="error"
+          START_TIME=""
+          [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+
+  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: |
+          curl -sH "Authorization: token $GITHUB_TOKEN"             "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}"             | bash
+
+      - 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的时间
+          echo "等待30秒让CI启动..."
+          sleep 30
+
+          # 405连续计数器
+          MERGE_405_COUNT=0
+          MAX_405_RETRIES=10
+
+          # 轮询等待，最多30分钟（180次x10秒）
+          for attempt in $(seq 1 180); do
+            ALL_SUCCESS=true
+            ANY_FAILED=false
+            ANY_PENDING=false
+
+            echo "--- 第${attempt}次检查 ($(date '+%H:%M:%S')) ---"
+
+            # 检查CI状态
+            for ctx in "${CONTEXTS[@]}"; do
+              STATE=$(python3 scripts/check_ci_status.py "$GITHUB_TOKEN" "$GITHUB_REPOSITORY" "$PR_HEAD_SHA" "$ctx")
+              echo "  CI: ${ctx##*/}: $STATE"
+              if [ "$STATE" != "success" ]; then
+                ALL_SUCCESS=false
+              fi
+              if [ "$STATE" = "failure" ] || [ "$STATE" = "error" ]; then
+                ANY_FAILED=true
+              fi
+              if [ "$STATE" = "pending" ]; then
+                ANY_PENDING=true
+              fi
+            done
+
+            # 检查审批状态
+            APPROVAL_RESULT=$(python3 scripts/check_pr_approval.py "$MERGE_TOKEN" "$GITHUB_REPOSITORY" "$PR_NUMBER" 1)
+            echo "  审批: $APPROVAL_RESULT"
+            HAS_APPROVAL=false
+            if echo "$APPROVAL_RESULT" | grep -q '^approved'; then
+              HAS_APPROVAL=true
+            fi
+
+            # 全部满足 → 合并
+            if [ "$ALL_SUCCESS" = "true" ] && [ "$HAS_APPROVAL" = "true" ]; then
+              echo
+              echo "CI全绿 + 审批通过，执行自动合并"
+              echo "等待60秒冷却，给Gitea内部状态同步时间..."
+              sleep 60
+
+              # 幂等检查：PR是否还是open
+              PR_STATE=$(curl -s -H "Authorization: token ${MERGE_TOKEN}" \
+                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" \
+                | python3 -c "import sys,json; print(json.load(sys.stdin).get('state',''))")
+
+              if [ "$PR_STATE" != "open" ]; then
+                echo "PR状态为 ${PR_STATE}，无需合并"
+                exit 0
+              fi
+
+              # 执行squash merge
+              HTTP_CODE=$(curl -s -o /tmp/merge_resp.json -w "%{http_code}" \
+                -X POST \
+                -H "Authorization: token ${MERGE_TOKEN}" \
+                -H "Content-Type: application/json" \
+                -d '{"do":"squash","merge_title_field":"","merge_message_field":"","delete_branch_after_merge":true,"force_merge":false}' \
+                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/merge")
+
+              echo "合并API HTTP状态: $HTTP_CODE"
+
+              if [ "$HTTP_CODE" = "200" ]; then
+                echo "自动合并成功"
+                exit 0
+              elif [ "$HTTP_CODE" = "405" ]; then
+                MERGE_405_COUNT=$((MERGE_405_COUNT + 1))
+                echo "⚠️  合并返回405（第${MERGE_405_COUNT}次），可能CI状态尚未同步或有未解决的门禁，继续等待重试..."
+                cat /tmp/merge_resp.json 2>/dev/null || true
+                echo
+                if [ "$MERGE_405_COUNT" -ge "$MAX_405_RETRIES" ]; then
+                  echo "⚠️  连续${MAX_405_RETRIES}次合并返回405，放弃自动合并（需人工确认，非代码问题）"
+                  curl -s -X POST \
+                    -H "Authorization: token ${MERGE_TOKEN}" \
+                    -H "Content-Type: application/json" \
+                    -d '{"body": "Auto merge skipped after multiple 405 errors: PR may have conflicts or unresolved checks. Please review manually. This is not a CI failure."}' \
+                    "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null 2>&1 || true
+                  exit 0
+                fi
+                sleep 30
+                continue
+              else
+                echo "自动合并失败 (HTTP $HTTP_CODE)"
+                cat /tmp/merge_resp.json 2>/dev/null || true
+                curl -s -X POST \
+                  -H "Authorization: token ${MERGE_TOKEN}" \
+                  -H "Content-Type: application/json" \
+                  -d "{\"body\": \"Auto merge failed (HTTP ${HTTP_CODE}), please check manually.\"}" \
+                  "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null 2>&1 || true
+                exit 1
+              fi
+            else
+              # 本轮不满足合并条件，重置405计数器
+              MERGE_405_COUNT=0
+            fi
+
+            if [ "$ANY_FAILED" = "true" ]; then
+              echo
+              echo "CI有失败项，不自动合并"
+              exit 0
+            fi
+
+            sleep 10
+          done
+
+          echo
+          echo "等待超时（30分钟）"
+          exit 0
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ ${{ job.status }} = "success" ] || STATUS="error"
+          START_TIME=""
+          [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+

.gitea/workflows/preview-cleanup.yml

@@ -193,3 +193,15 @@ jobs:
           > /dev/null
         echo "Cleanup comment posted"
 
+    - name: Report CI trace
+      if: always()
+      shell: sh
+      env:
+        AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+      run: |
+        STATUS="ok"
+        [ ${{ job.status }} = "success" ] || STATUS="error"
+        START_TIME=""
+        [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+        python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+

.gitea/workflows/preview-deploy.yml

@@ -157,8 +157,8 @@ jobs:
         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_host="${PREVIEW_SSH_HOST:-47.98.113.167}"
+        preview_user="${PREVIEW_SSH_USER:-root}"
         preview_port="${PREVIEW_SSH_PORT:-22222}"
         preview_dir="/var/www/preview/pr-${PR_NUMBER}"
 
@@ -272,3 +272,15 @@ jobs:
       run: |
         set +e
         NOTIFY_MODE=failure JOB_NAME="Deploy Preview Environment" python3 scripts/ci_notify.py
+    - name: Report CI trace
+      if: always()
+      shell: sh
+      env:
+        AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+      run: |
+        STATUS="ok"
+        [ ${{ job.status }} = "success" ] || STATUS="error"
+        START_TIME=""
+        [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+        python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+

.gitignore

@@ -53,3 +53,4 @@ frontend-v21-ui-prototype-final.html
 !.vscode/
 !.vscode/settings.json
 .vscode/extensions.json
+.coverage

apps/api/app/api/routes/feature_flags.py

@@ -32,9 +32,7 @@ logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/internal/feature-flags", tags=["Internal"])
 
 # 允许管理的 flag 白名单（防止误操作其他系统 flag）
-ALLOWED_FLAGS = {
-    "render_engine",
-}
+ALLOWED_FLAGS: set[str] = set()
 
 
 def _get_feature_flag_store() -> RedisFeatureFlagStore:

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

@@ -1,4 +1,6 @@
 import { expect, test, type APIRequestContext } from "@playwright/test"
+import * as fs from "node:fs"
+import * as path from "node:path"
 
 const PASSWORD = "SmokePass123!"
 const apiBase = process.env.E2E_API_BASE || "/api/v1"
@@ -88,6 +90,8 @@ test.describe("Core generation flow", () => {
 
     // Upload source video
     const sourceFileName = "e2e-gen-source.mp4"
+    const sampleVideoPath = path.join(__dirname, "fixtures", "sample.mp4")
+    const sampleVideoBuffer = fs.readFileSync(sampleVideoPath)
     const upload = await request.post(`${apiBase}/upload`, {
       headers,
       multipart: {
@@ -96,7 +100,7 @@ test.describe("Core generation flow", () => {
         file: {
           name: sourceFileName,
           mimeType: "video/mp4",
-          buffer: Buffer.from("e2e source data"),
+          buffer: sampleVideoBuffer,
         },
       },
     })

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

@@ -1,4 +1,6 @@
 import { expect, test, type APIRequestContext } from "@playwright/test"
+import * as fs from "node:fs"
+import * as path from "node:path"
 
 const PASSWORD = "SmokePass123!"
 const apiBase = process.env.E2E_API_BASE || "/api/v1"
@@ -116,15 +118,17 @@ test.describe("Core media upload flow", () => {
       timeout: 20_000,
     })
 
+    const sampleVideoPath = path.join(__dirname, "fixtures", "sample.mp4")
+    const sampleVideoBuffer = fs.readFileSync(sampleVideoPath)
     const upload = await request.post(`${apiBase}/upload`, {
       headers,
       multipart: {
         project_id: projectData.id,
         library_id: libraryData.id,
         file: {
-          name: "e2e-sample.MOV",
-          mimeType: "video/quicktime",
-          buffer: Buffer.from("playwright mov upload smoke"),
+          name: "e2e-sample.mp4",
+          mimeType: "video/mp4",
+          buffer: sampleVideoBuffer,
         },
       },
     })
@@ -152,7 +156,7 @@ test.describe("Core media upload flow", () => {
               mime_type?: string
             }>
           }
-          const asset = data.items.find((item) => item.name === "e2e-sample.MOV")
+          const asset = data.items.find((item) => item.name === "e2e-sample.mp4")
           return asset ? `${asset.mime_type || asset.file_type || ""}:${asset.status}` : "missing"
         },
         { timeout: 30_000, intervals: [1_000, 2_000, 3_000] },
@@ -169,12 +173,12 @@ test.describe("Core media upload flow", () => {
     await expect(page.locator(".xx-assets-content")).toBeVisible({
       timeout: 20_000,
     })
-    await expect(page.getByText("e2e-sample.MOV", { exact: true })).toBeVisible({
+    await expect(page.getByText("e2e-sample.mp4", { exact: true })).toBeVisible({
       timeout: 20_000,
     })
 
     // Verify asset card shows status
-    const assetCard = page.locator(".xx-asset-card").filter({ hasText: "e2e-sample.MOV" })
+    const assetCard = page.locator(".xx-asset-card").filter({ hasText: "e2e-sample.mp4" })
     await expect(assetCard).toBeVisible()
     await expect(assetCard.locator(".xx-asset-diagnose-btn")).toBeVisible()
 

apps/web/src/components/layout/PageHead.tsx

@@ -59,7 +59,7 @@ const ROUTE_TITLE_MAP: Record<string, string> = {
   "/app/subscription/upgrade": "升级订阅",
   "/app/subscription/billing": "账单管理",
   "/app/profile": "个人设置",
-  "/app/editing-planner": "剪辑规划",
+  "/app/editing-planner": "模板制作",
   "/app/my-templates": "我的模板",
   "/app/voice-clone": "我的音色",
   "/app/voice-materials": "配音库",

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

@@ -1,10 +1,10 @@
 /**
- * 剪辑计划编辑器 — V8 原型 1:1 还原
+ * 模板编辑器 — 制作/编辑剪辑模板
  * 四行布局：顶栏(42px) → 模式栏(48px) → 三栏主体 → 底栏(40px)
  */
 import React, { useState, useCallback, useEffect, useRef } from "react"
 import { useSearchParams } from "react-router-dom"
-import { message, Modal, Progress, Button } from "antd"
+import { message, Modal } from "antd"
 import { useQuery } from "@tanstack/react-query"
 import type {
   EditingTemplate,
@@ -20,31 +20,8 @@ import {
   getTemplateCategories,
   MODE_LABELS,
 } from "@/api/editingPlanner"
-import type {
-  EditPlanGeneration,
-  EditPlanConfig,
-  GeneratedVideo,
-  MediaAsset,
-  TransitionEffect,
-  TitleConfig,
-} from "@/api/editPlans"
-import {
-  getMediaAssets,
-  getEditPlanGenerations,
-  getEditPlan,
-  createEditPlan,
-  updateEditPlan,
-  generateEditPlan,
-  getGenerationStatus,
-  getGenerationTaskResults,
-  cancelGeneration,
-  getEditPlanClips,
-  createEditPlanClip,
-  batchDeleteEditPlanClips,
-  type EditPlanClip,
-  type CreateEditPlanClipRequest,
-  type ClipStatusItem,
-} from "@/api/editPlans"
+import type { MediaAsset, TransitionEffect, TitleConfig } from "@/api/editPlans"
+import { getMediaAssets, getEditPlan, getEditPlanClips } from "@/api/editPlans"
 import { useUndoRedo } from "./hooks/useUndoRedo"
 import type {
   ClipData,
@@ -97,7 +74,6 @@ import GreenScreenPanel from "./components/GreenScreenPanel"
 import StickerPanel from "./components/StickerPanel"
 
 import SaveModal from "./components/SaveModal"
-import GenerationHistoryModal from "./components/GenerationHistoryModal"
 import { DEFAULT_BGM_MIX_CONFIG, type BgmMixConfig } from "@/api/bgm"
 import "./EditingPlanner.css"
 
@@ -230,26 +206,8 @@ const EditingPlanner: React.FC = () => {
     setSelectedAssetIds(ids)
   }
 
-  /* ── 生成历史 ── */
-  const [genHistoryOpen, setGenHistoryOpen] = useState(false)
-  const [genHistory, setGenHistory] = useState<EditPlanGeneration[]>([])
-  const [genHistoryLoading, setGenHistoryLoading] = useState(false)
-
   /* ── 剪辑计划（从列表页编辑进入时） ── */
-  const [loadedPlanId, setLoadedPlanId] = useState<string | null>(urlPlanId || null)
-
-  /* ── 生成进度 ── */
-  const [generating, setGenerating] = useState(false)
-  const [genProgress, setGenProgress] = useState(0)
-  const [genTotalClips, setGenTotalClips] = useState(0)
-  const [genDoneClips, setGenDoneClips] = useState(0)
-  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)
+  const [loadedPlanId] = useState<string | null>(urlPlanId || null)
 
   /* ── 播放 ── */
   const [isPlaying, setIsPlaying] = useState(false)
@@ -772,58 +730,6 @@ const EditingPlanner: React.FC = () => {
     setStickerSettings(config)
   }, [])
 
-  /** 构建剪辑计划 config（编辑器状态 → API config） */
-  const buildPlanConfig = (): EditPlanConfig => ({
-    title_config: titleConfig,
-    subtitle_config: {
-      enabled: subtitleSettings.enabled,
-      position: subtitleSettings.position,
-      font: subtitleSettings.font,
-      color: subtitleSettings.fontColor,
-      size: subtitleSettings.fontSize,
-      animation: subtitleSettings.animation,
-    },
-    bgm_config: {
-      enabled: bgmSettings.enabled,
-      music_id: bgmSettings.music_id,
-    },
-    estimated_duration: totalDuration,
-    segments: clips.map((c, i) => ({
-      segment_order: i,
-      duration_min: Math.max(1, c.duration - 2),
-      duration_max: c.duration + 2,
-      material_type: c.type === "voice" ? "voiceover" : "video",
-      transition: c.transition
-        ? { type: c.transition.type, duration: c.transition.duration }
-        : undefined,
-      playback_speed: c.speed ? c.speed.rate : undefined,
-      tts_config: c.tts_config
-        ? {
-            mode: c.tts_config.mode,
-            text: c.tts_config.text,
-            voice_id: c.tts_config.voice_id,
-            speed: c.tts_config.speed,
-            pitch: c.tts_config.pitch,
-            volume: c.tts_config.volume,
-            subtitle_sync: c.tts_config.subtitle_sync,
-          }
-        : undefined,
-      trim_config: c.trim_config
-        ? {
-            start_time: c.trim_config.start_time,
-            end_time: c.trim_config.end_time,
-          }
-        : undefined,
-    })),
-    watermark_config: { ...watermarkSettings },
-    intro_outro_config: { ...introOutroSettings },
-    pip_config: { ...pipSettings },
-    filter_config: { ...filterSettings },
-    green_screen_config: { ...chromaKeySettings },
-    sticker_config: { ...stickerSettings },
-    cover_config: { ...coverConfig },
-  })
-
   /* 保存 — 无论是否已加载模板，都打开保存弹窗；未加载时创建新模板 */
   const handleOpenSaveModal = () => {
     setSaveModalOpen(true)
@@ -908,247 +814,6 @@ 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（从模板库直接进入）→ 先创建计划 + 同步片段 + 触发生成
-   * 3. 触发生成后轮询状态，完成后获取视频结果
-   */
-  const handleGoToGenerate = async () => {
-    if (!loadedTemplateId) {
-      message.warning("请先选择一个模板")
-      return
-    }
-    if (clips.length === 0) {
-      message.warning("请先添加片段")
-      return
-    }
-
-    setGenerating(true)
-    setGenerated(false)
-    setGeneratedVideos([])
-    setGenError(null)
-    setGenProgress(0)
-    setGenCancelled(false)
-
-    try {
-      const config = buildPlanConfig()
-      let planId = loadedPlanId
-
-      if (planId) {
-        // 已有计划 → 先重置状态为 draft（failed/editing 等非 draft 状态会被后端拒绝更新和生成）
-        try {
-          await updateEditPlan(planId, { status: "draft" })
-        } catch (resetErr) {
-          console.warn("[状态重置跳过]", resetErr)
-        }
-        // 再更新配置
-        try {
-          await updateEditPlan(planId, {
-            config,
-            total_duration: totalDuration,
-          })
-        } catch (updateErr) {
-          console.warn("[计划更新跳过]", updateErr)
-        }
-      } else {
-        // 无计划 → 创建新计划
-        const plan = await createEditPlan({
-          template_id: loadedTemplateId,
-          name: draftName || "未命名计划",
-          config,
-          total_duration: totalDuration,
-        })
-        planId = plan.id
-        setLoadedPlanId(planId)
-        // 更新 URL 参数（不刷新页面）
-        const params = new URLSearchParams(window.location.search)
-        params.set("planId", planId)
-        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)
-      message.info("已提交生成，等待处理...")
-
-      // 开始轮询
-      startPolling(planId)
-    } catch (err) {
-      console.error("[生成失败]", err)
-      setGenError("生成提交失败，请重试")
-      setGenerating(false)
-    }
-  }
-
-  /** 轮询生成状态，每 2 秒一次 */
-  const startPolling = (planId: string) => {
-    const poll = async () => {
-      try {
-        const status = await getGenerationStatus(planId)
-
-        // 计算进度
-        const total = status.clips.length || genTotalClips
-        const done = status.clips.filter(
-          (c) => c.status === "completed" || c.status === "failed",
-        ).length
-        setGenDoneClips(done)
-        setGenTotalClips(total)
-        setGenClipStatuses(status.clips || [])
-        setGenProgress(total > 0 ? Math.round((done / total) * 100) : 5)
-
-        if (status.plan_status === "completed") {
-          setGenProgress(100)
-          setGenerating(false)
-          setGenerated(true)
-
-          // 获取视频结果
-          if (status.generation_task_id) {
-            try {
-              const videos = await getGenerationTaskResults(status.generation_task_id)
-              setGeneratedVideos(videos)
-            } catch (e) {
-              console.error("[获取视频结果失败]", e)
-            }
-          }
-          message.success("视频生成完成！")
-          return // 停止轮询
-        }
-
-        if (status.plan_status === "failed") {
-          setGenerating(false)
-          setGenError("生成失败，请重试")
-          return // 停止轮询
-        }
-
-        if (status.plan_status === "cancelled") {
-          setGenerating(false)
-          setGenError("生成已取消")
-          setGenCancelled(true)
-          message.info("生成任务已取消")
-          return // 停止轮询
-        }
-
-        // 继续轮询
-        genTimerRef.current = setTimeout(poll, 2000)
-      } catch (err) {
-        console.error("[轮询状态失败]", err)
-        genTimerRef.current = setTimeout(poll, 5000) // 出错后 5 秒重试
-      }
-    }
-
-    // 首次延迟 2 秒后开始
-    genTimerRef.current = setTimeout(poll, 2000)
-  }
-
-  /** 清理轮询定时器 */
-  useEffect(() => {
-    return () => {
-      if (genTimerRef.current) clearTimeout(genTimerRef.current)
-    }
-  }, [])
-
-  /** 取消生成任务 */
-  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
-    if (!targetId) {
-      message.warning("请先加载一个模板或计划")
-      return
-    }
-    setGenHistoryOpen(true)
-    setGenHistoryLoading(true)
-    try {
-      const items = await getEditPlanGenerations(targetId)
-      setGenHistory(items)
-    } catch {
-      message.error("加载生成历史失败")
-    } finally {
-      setGenHistoryLoading(false)
-    }
-  }
-
   /* ──────────── 渲染 ──────────── */
 
   return (
@@ -1157,7 +822,7 @@ const EditingPlanner: React.FC = () => {
       <div className="ep-top-bar">
         <div className="ep-top-bar-left">
           <span className="ep-logo">✂️</span>
-          <span className="ep-app-title">小虾剪辑编排器</span>
+          <span className="ep-app-title">模板制作</span>
           <span className="ep-divider">|</span>
           <span className="ep-template-name">{currentTemplate?.name || "未选择模板"}</span>
         </div>
@@ -1181,13 +846,6 @@ const EditingPlanner: React.FC = () => {
           <button className="ep-btn ep-btn-secondary" onClick={handleOpenSaveModal}>
             💾 保存模板
           </button>
-          <button
-            className="ep-btn ep-btn-primary"
-            onClick={handleGoToGenerate}
-            disabled={generating}
-          >
-            {loadedPlanId ? "🎬 生成视频" : "🎬 创建计划并生成"}
-          </button>
         </div>
       </div>
 
@@ -1352,10 +1010,6 @@ const EditingPlanner: React.FC = () => {
           <span>🎬 {MODE_LABELS[currentMode]}</span>
           <span className="ep-status-sep">|</span>
           <span>📐 模板片段: {currentTemplate?.segments.length || 0}</span>
-          <span className="ep-status-sep">|</span>
-          <button className="ep-status-link" onClick={handleViewGenHistory}>
-            📋 生成历史
-          </button>
         </div>
       </div>
 
@@ -1376,214 +1030,6 @@ const EditingPlanner: React.FC = () => {
         onCancel={() => setSaveModalOpen(false)}
       />
 
-      {/* ═══ 生成历史弹窗 ═══ */}
-      <GenerationHistoryModal
-        open={genHistoryOpen}
-        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
-            ? "生成失败"
-            : genCancelled
-              ? "已取消生成"
-              : generated
-                ? "生成完成"
-                : "正在生成视频"
-        }
-        open={generating || generated || !!genError || genCancelled}
-        footer={
-          generated
-            ? [
-                <Button
-                  key="close"
-                  onClick={() => {
-                    setGenerated(false)
-                    setGenerating(false)
-                    setGenError(null)
-                  }}
-                >
-                  关闭
-                </Button>,
-                generatedVideos.length > 0 && (
-                  <Button
-                    key="download"
-                    type="primary"
-                    onClick={() => {
-                      const v = generatedVideos[0]
-                      const url = v.download_url || v.file_url
-                      if (url) {
-                        const a = document.createElement("a")
-                        a.href = url
-                        a.download = v.name || "video.mp4"
-                        a.target = "_blank"
-                        document.body.appendChild(a)
-                        a.click()
-                        document.body.removeChild(a)
-                      }
-                    }}
-                  >
-                    下载视频
-                  </Button>
-                ),
-              ]
-            : 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}
-        width={520}
-      >
-        {generating && (
-          <div style={{ padding: "16px 0" }}>
-            <Progress percent={genProgress} status="active" />
-            <p style={{ marginTop: 8, color: "var(--text-secondary)" }}>
-              已处理 {genDoneClips}/{genTotalClips} 个片段
-            </p>
-            {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
-              src={generatedVideos[0].file_url || generatedVideos[0].download_url}
-              controls
-              preload="metadata"
-              style={{ width: "100%", maxHeight: 320, borderRadius: 8 }}
-            />
-            <p
-              style={{
-                marginTop: 8,
-                textAlign: "center",
-                color: "var(--text-secondary)",
-              }}
-            >
-              {generatedVideos[0].name}
-            </p>
-          </div>
-        )}
-        {generated && !generatedVideos.length && (
-          <div style={{ padding: "24px 0", textAlign: "center" }}>
-            <p>生成完成，但暂未获取到视频结果</p>
-            <p style={{ color: "var(--text-secondary)", fontSize: 12 }}>
-              请稍后在剪辑计划列表中查看
-            </p>
-          </div>
-        )}
-        {genError && (
-          <div
-            style={{
-              padding: "16px 0",
-              textAlign: "center",
-              color: "#ff4d4f",
-            }}
-          >
-            <p>{genError}</p>
-            <Button
-              onClick={() => {
-                setGenError(null)
-                setGenerating(false)
-              }}
-            >
-              关闭
-            </Button>
-          </div>
-        )}
-      </Modal>
-
       {/* ═══ BGM 选择器 Drawer ═══ */}
       <BgmSelector
         open={bgmDrawerOpen}

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

@@ -273,6 +273,120 @@
   color: var(--info-color);
 }
 
+/* ============================================================
+   AI 智能配音推荐
+   ============================================================ */
+.xx-voice-recommend-section {
+  padding: 16px;
+  background: linear-gradient(135deg, #f0f4ff 0%, #faf5ff 100%);
+  border: 1px solid var(--border-primary, #e2e8f0);
+  border-radius: 14px;
+  margin-bottom: 16px;
+}
+
+.xx-voice-recommend-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 12px;
+}
+
+.xx-voice-recommend-label {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary, #1e293b);
+}
+
+.xx-voice-recommend-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.xx-voice-recommend-card {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 12px;
+  background: #fff;
+  border: 2px solid var(--border-primary, #e2e8f0);
+  border-radius: 10px;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  position: relative;
+}
+
+.xx-voice-recommend-card:hover {
+  border-color: var(--primary-color, #4f46e5);
+  transform: translateX(2px);
+}
+
+.xx-voice-recommend-card.selected {
+  border-color: var(--primary-color, #4f46e5);
+  background: var(--primary-soft, #eef2ff);
+}
+
+.xx-voice-recommend-avatar {
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  background: linear-gradient(135deg, #a5b4fc, #c4b5fd);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 20px;
+  flex-shrink: 0;
+}
+
+.xx-voice-recommend-info {
+  flex: 1;
+  min-width: 0;
+}
+
+.xx-voice-recommend-name {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--text-primary, #1e293b);
+  margin-bottom: 2px;
+}
+
+.xx-voice-recommend-desc {
+  font-size: 11px;
+  color: var(--text-tertiary, #94a3b8);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.xx-voice-recommend-check {
+  width: 20px;
+  height: 20px;
+  background: var(--primary-color, #4f46e5);
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.xx-voice-recommend-loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 20px;
+  font-size: 13px;
+  color: var(--text-secondary, #64748b);
+}
+
+.xx-voice-recommend-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 16px;
+  font-size: 12px;
+  color: var(--text-tertiary, #94a3b8);
+}
+
 /* ============================================================
    配音卡片（步骤4 choice-list 变体）
    ============================================================ */
@@ -548,6 +662,147 @@
   }
 }
 
+/* ============================================================
+   生成进度 / 结果卡片
+   ============================================================ */
+.xx-gen-progress-card {
+  padding: 16px;
+  background: linear-gradient(135deg, #eff6ff 0%, #eef2ff 100%);
+  border: 1px solid #bfdbfe;
+  border-radius: 12px;
+}
+
+.xx-gen-progress-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 12px;
+}
+
+.xx-gen-progress-icon {
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  background: #fff;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--primary-color, #4f46e5);
+  font-size: 18px;
+  flex-shrink: 0;
+}
+
+.xx-gen-progress-info {
+  flex: 1;
+  min-width: 0;
+}
+
+.xx-gen-progress-phase {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary, #1e293b);
+  margin-bottom: 2px;
+}
+
+.xx-gen-progress-sub {
+  font-size: 12px;
+  color: var(--text-secondary, #64748b);
+}
+
+.xx-gen-progress-percent {
+  font-size: 20px;
+  font-weight: 700;
+  color: var(--primary-color, #4f46e5);
+  flex-shrink: 0;
+}
+
+.xx-gen-progress-bar {
+  width: 100%;
+  height: 6px;
+  background: rgba(79, 70, 229, 0.15);
+  border-radius: 3px;
+  overflow: hidden;
+  margin-bottom: 10px;
+}
+
+.xx-gen-progress-bar-fill {
+  height: 100%;
+  background: linear-gradient(90deg, #4f46e5, #7c3aed);
+  border-radius: 3px;
+  transition: width 0.3s ease;
+}
+
+.xx-gen-progress-tip {
+  font-size: 12px;
+  color: var(--text-tertiary, #94a3b8);
+  text-align: center;
+}
+
+.xx-gen-success-card {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 16px;
+  background: #f0fdf4;
+  border: 1px solid #bbf7d0;
+  border-radius: 12px;
+}
+
+.xx-gen-success-icon {
+  flex-shrink: 0;
+}
+
+.xx-gen-success-info {
+  flex: 1;
+  min-width: 0;
+}
+
+.xx-gen-success-title {
+  font-size: 15px;
+  font-weight: 600;
+  color: #166534;
+  margin-bottom: 4px;
+}
+
+.xx-gen-success-sub {
+  font-size: 12px;
+  color: #15803d;
+}
+
+.xx-gen-error-card {
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+  padding: 16px;
+  background: #fef2f2;
+  border: 1px solid #fecaca;
+  border-radius: 12px;
+}
+
+.xx-gen-error-icon {
+  flex-shrink: 0;
+  margin-top: 2px;
+}
+
+.xx-gen-error-info {
+  flex: 1;
+  min-width: 0;
+}
+
+.xx-gen-error-title {
+  font-size: 14px;
+  font-weight: 600;
+  color: #991b1b;
+  margin-bottom: 4px;
+}
+
+.xx-gen-error-msg {
+  font-size: 12px;
+  color: #b91c1c;
+  line-height: 1.5;
+  word-break: break-all;
+}
+
 /* ============================================================
    确认生成（步骤5）摘要
    ============================================================ */
@@ -1137,6 +1392,418 @@
   border-radius: 20px;
 }
 
+/* ── 智能素材匹配 ── */
+.xx-smart-match-section {
+  margin-top: 14px;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.xx-smart-match-input-area {
+  padding: 16px;
+  background: linear-gradient(135deg, #f0f4ff 0%, #faf5ff 100%);
+  border: 1px solid var(--border-primary, #e2e8f0);
+  border-radius: 14px;
+}
+
+.xx-smart-match-label {
+  display: block;
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary, #1e293b);
+  margin-bottom: 10px;
+}
+
+.xx-smart-match-input {
+  width: 100%;
+  min-height: 80px;
+  padding: 12px;
+  font-size: 13px;
+  line-height: 1.6;
+  color: var(--text-primary, #1e293b);
+  background: #fff;
+  border: 1px solid var(--border-primary, #e2e8f0);
+  border-radius: 10px;
+  resize: vertical;
+  box-sizing: border-box;
+  transition: border-color 0.2s;
+  font-family: inherit;
+}
+
+.xx-smart-match-input:focus {
+  outline: none;
+  border-color: var(--primary-color, #4f46e5);
+  box-shadow: 0 0 0 3px rgba(79, 70, 229, 0.1);
+}
+
+.xx-smart-match-input::placeholder {
+  color: var(--text-tertiary, #94a3b8);
+}
+
+.xx-smart-match-input-footer {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-top: 10px;
+}
+
+.xx-smart-match-tip {
+  font-size: 12px;
+  color: var(--text-tertiary, #94a3b8);
+}
+
+.xx-smart-match-results {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.xx-smart-match-results-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.xx-smart-match-results-title {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary, #1e293b);
+}
+
+.xx-smart-match-results-actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 12px;
+}
+
+.xx-link-btn {
+  background: none;
+  border: none;
+  color: var(--primary-color, #4f46e5);
+  font-size: 12px;
+  cursor: pointer;
+  padding: 2px 4px;
+}
+
+.xx-link-btn:hover {
+  text-decoration: underline;
+}
+
+.xx-smart-match-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 10px;
+  max-height: 420px;
+  overflow-y: auto;
+  padding-right: 4px;
+}
+
+.xx-smart-match-card {
+  background: #fff;
+  border: 2px solid var(--border-primary, #e2e8f0);
+  border-radius: 12px;
+  overflow: hidden;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.xx-smart-match-card:hover {
+  border-color: var(--primary-color, #4f46e5);
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+}
+
+.xx-smart-match-card.selected {
+  border-color: var(--primary-color, #4f46e5);
+  background: var(--primary-soft, #eef2ff);
+}
+
+.xx-smart-match-thumb {
+  position: relative;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  background: #f1f5f9;
+  overflow: hidden;
+}
+
+.xx-smart-match-thumb img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.xx-smart-match-thumb-placeholder {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--text-tertiary, #94a3b8);
+}
+
+.xx-smart-match-score {
+  position: absolute;
+  top: 8px;
+  left: 8px;
+  padding: 2px 8px;
+  font-size: 11px;
+  font-weight: 600;
+  color: #fff;
+  background: linear-gradient(135deg, #4f46e5, #7c3aed);
+  border-radius: 12px;
+}
+
+.xx-smart-match-check {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  width: 24px;
+  height: 24px;
+  background: var(--primary-color, #4f46e5);
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.xx-smart-match-duration {
+  position: absolute;
+  bottom: 8px;
+  right: 8px;
+  padding: 2px 6px;
+  font-size: 11px;
+  color: #fff;
+  background: rgba(0, 0, 0, 0.6);
+  border-radius: 4px;
+}
+
+.xx-smart-match-info {
+  padding: 10px 12px;
+}
+
+.xx-smart-match-name {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--text-primary, #1e293b);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  margin-bottom: 4px;
+}
+
+.xx-smart-match-reason {
+  font-size: 11px;
+  color: var(--text-secondary, #64748b);
+  line-height: 1.4;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.xx-smart-match-loading {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 40px 20px;
+  background: #f8fafc;
+  border-radius: 12px;
+}
+
+.xx-smart-match-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 30px 20px;
+  background: #f8fafc;
+  border-radius: 12px;
+  text-align: center;
+}
+
+.xx-smart-match-summary {
+  padding: 12px 16px;
+  background: #f0fdf4;
+  border: 1px solid #bbf7d0;
+  border-radius: 12px;
+}
+
+.xx-smart-match-summary-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+/* ============================================================
+   AI 智能生成标题
+   ============================================================ */
+.xx-ai-title-section {
+  padding: 16px;
+  background: linear-gradient(135deg, #f0f4ff 0%, #faf5ff 100%);
+  border: 1px solid var(--border-primary, #e2e8f0);
+  border-radius: 14px;
+  margin-bottom: 16px;
+}
+
+.xx-ai-title-header {
+  margin-bottom: 10px;
+}
+
+.xx-ai-title-label {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary, #1e293b);
+}
+
+.xx-ai-title-input-row {
+  display: flex;
+  gap: 10px;
+}
+
+.xx-ai-title-input {
+  flex: 1;
+  padding: 10px 14px;
+  font-size: 13px;
+  border: 1px solid var(--border-primary, #e2e8f0);
+  border-radius: 10px;
+  background: #fff;
+  transition: border-color 0.2s;
+}
+
+.xx-ai-title-input:focus {
+  outline: none;
+  border-color: var(--primary-color, #4f46e5);
+  box-shadow: 0 0 0 3px rgba(79, 70, 229, 0.1);
+}
+
+.xx-ai-title-input::placeholder {
+  color: var(--text-tertiary, #94a3b8);
+}
+
+.xx-ai-title-results {
+  margin-top: 14px;
+}
+
+.xx-ai-title-results-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 10px;
+}
+
+.xx-ai-title-results-count {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--text-primary, #1e293b);
+}
+
+.xx-ai-title-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  max-height: 320px;
+  overflow-y: auto;
+  padding-right: 4px;
+}
+
+.xx-ai-title-card {
+  position: relative;
+  padding: 12px 14px;
+  background: #fff;
+  border: 2px solid var(--border-primary, #e2e8f0);
+  border-radius: 10px;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.xx-ai-title-card:hover {
+  border-color: var(--primary-color, #4f46e5);
+  transform: translateX(2px);
+}
+
+.xx-ai-title-card.selected {
+  border-color: var(--primary-color, #4f46e5);
+  background: var(--primary-soft, #eef2ff);
+}
+
+.xx-ai-title-card-text {
+  font-size: 13px;
+  color: var(--text-primary, #1e293b);
+  line-height: 1.5;
+  padding-right: 50px;
+}
+
+.xx-ai-title-card-tag {
+  display: inline-block;
+  margin-top: 6px;
+  padding: 2px 8px;
+  font-size: 11px;
+  border-radius: 10px;
+  background: #f1f5f9;
+  color: var(--text-secondary, #64748b);
+}
+
+.xx-ai-title-card.catchy .xx-ai-title-card-tag {
+  background: #fef3c7;
+  color: #b45309;
+}
+
+.xx-ai-title-card.emotional .xx-ai-title-card-tag {
+  background: #fce7f3;
+  color: #be185d;
+}
+
+.xx-ai-title-card.informative .xx-ai-title-card-tag {
+  background: #dbeafe;
+  color: #1d4ed8;
+}
+
+.xx-ai-title-card-check {
+  position: absolute;
+  top: 50%;
+  right: 12px;
+  transform: translateY(-50%);
+  width: 20px;
+  height: 20px;
+  background: var(--primary-color, #4f46e5);
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.xx-ai-title-loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+  font-size: 13px;
+  color: var(--text-secondary, #64748b);
+}
+
+.xx-divider {
+  display: flex;
+  align-items: center;
+  margin: 16px 0;
+  color: var(--text-tertiary, #94a3b8);
+  font-size: 12px;
+}
+
+.xx-divider::before,
+.xx-divider::after {
+  content: "";
+  flex: 1;
+  height: 1px;
+  background: var(--border-primary, #e2e8f0);
+}
+
+.xx-divider span {
+  padding: 0 12px;
+}
+
 /* ============================================================
    标题设置（选择标题步骤）
    ============================================================ */
@@ -1749,3 +2416,226 @@
   border-radius: var(--radius-sm);
   line-height: 1.5;
 }
+
+/* ================================================================
+   生成结果（右侧）
+   ================================================================ */
+
+.xx-generate-result {
+  background: var(--bg-secondary);
+  border-radius: var(--radius-xl);
+  padding: 20px;
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  overflow: hidden;
+}
+
+.xx-result-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 16px;
+}
+
+.xx-result-header h3 {
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--text-primary);
+  margin: 0;
+}
+
+.xx-result-count {
+  font-size: 12px;
+  color: var(--text-secondary);
+  background: var(--bg-tertiary);
+  padding: 2px 10px;
+  border-radius: 12px;
+}
+
+.xx-result-empty {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  padding: 40px 20px;
+}
+
+.xx-result-progress {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  padding: 40px 20px;
+  gap: 20px;
+}
+
+.xx-progress-circle {
+  position: relative;
+  width: 80px;
+  height: 80px;
+}
+
+.xx-progress-circle svg {
+  width: 100%;
+  height: 100%;
+}
+
+.xx-progress-percent {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.xx-progress-text {
+  text-align: center;
+}
+
+/* 视频卡片网格 */
+.xx-video-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 12px;
+  overflow-y: auto;
+  flex: 1;
+  padding-right: 4px;
+}
+
+.xx-video-card {
+  background: var(--bg-primary);
+  border-radius: var(--radius-md);
+  overflow: hidden;
+  cursor: pointer;
+  transition: all 0.2s;
+  border: 1px solid var(--border-color);
+}
+
+.xx-video-card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 8px 20px rgba(0, 0, 0, 0.1);
+  border-color: var(--primary-300);
+}
+
+.xx-video-thumb {
+  position: relative;
+  aspect-ratio: 16 / 9;
+  background: var(--bg-tertiary);
+  overflow: hidden;
+}
+
+.xx-video-thumb img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.xx-video-thumb-placeholder {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--text-tertiary);
+}
+
+.xx-video-play-overlay {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.3);
+  opacity: 0;
+  transition: opacity 0.2s;
+}
+
+.xx-video-card:hover .xx-video-play-overlay {
+  opacity: 1;
+}
+
+.xx-video-duration {
+  position: absolute;
+  bottom: 6px;
+  right: 6px;
+  padding: 2px 6px;
+  background: rgba(0, 0, 0, 0.7);
+  color: #fff;
+  font-size: 11px;
+  border-radius: 4px;
+  font-family: monospace;
+}
+
+.xx-video-info {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 12px;
+}
+
+.xx-video-title {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--text-primary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.xx-video-actions {
+  display: flex;
+  gap: 6px;
+}
+
+.xx-video-action-btn {
+  width: 28px;
+  height: 28px;
+  border: none;
+  background: var(--bg-tertiary);
+  border-radius: 6px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 13px;
+  color: var(--text-secondary);
+  transition: all 0.15s;
+}
+
+.xx-video-action-btn:hover {
+  background: var(--primary-100);
+  color: var(--primary-color);
+}
+
+.xx-result-footer {
+  margin-top: 12px;
+  padding-top: 12px;
+  border-top: 1px solid var(--border-color);
+}
+
+.xx-btn-block {
+  width: 100%;
+  justify-content: center;
+}
+
+/* 预览弹窗 */
+.xx-preview-modal-content {
+  background: #000;
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.ant-modal-content {
+  padding: 0 !important;
+}
+
+.ant-modal-close {
+  color: #fff !important;
+}

apps/web/src/pages/my-templates/MyTemplates.tsx

@@ -111,7 +111,8 @@ const MyTemplates: React.FC = () => {
   }
 
   const handleGenerate = (tpl: EditingTemplate) => {
-    navigate(`/editing-planner?template=${tpl.id}&generate=1`)
+    // 跳转到智能剪辑页面，统一从智能剪辑出片
+    navigate(`/generate?templateId=${tpl.id}`)
   }
 
   const handleCopy = (tpl: EditingTemplate) => {

apps/web/vitest.config.ts

@@ -16,7 +16,19 @@ export default defineConfig({
     coverage: {
       provider: "v8",
       reporter: ["text", "json", "html"],
-      exclude: ["node_modules/", "src/test/", "e2e/", "**/*.d.ts", "**/*.config.*", "**/mockData"],
+      exclude: [
+        "node_modules/",
+        "src/test/",
+        "e2e/",
+        "**/*.d.ts",
+        "**/*.config.*",
+        "**/mockData",
+        // 页面级组件不纳入单测覆盖率统计（页面级走 E2E/手动测试）
+        "src/pages/generate/GeneratePage.tsx",
+        "src/pages/editing-planner/EditingPlanner.tsx",
+        "src/pages/assets/AssetLibrary.tsx",
+        "src/pages/voice-materials/VoiceMaterialLibrary.tsx",
+      ],
       // CI 覆盖率门禁（Phase 4 后提升，逐步逼近目标）
       // 当前实际：行 ~62% / 分支 ~61% / 函数 ~25%
       thresholds: {

apps/worker/video_processing/render_adapter.py

@@ -186,85 +186,15 @@ class RenderAdapter:
 
             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, "执行视频渲染")
-
-            # 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(
+            # 3~6. 统一渲染核心流程（BGM + ASR + 渲染 + 缩略图 + 上传）
+            return self._do_render(
                 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()
-
-            self._report_progress(progress_cb, 80.0, "上传渲染结果")
-
-            # 4. 上传结果
-            storage_key = f"rendered/{plan_id}/{job_id or plan_id}.mp4"
-            output_url = upload_to_oss(result.output_path, storage_key)
-
-            self._report_progress(progress_cb, 90.0, "生成封面缩略图")
-
-            # 5. 生成缩略图（在清理临时目录前）
-            thumbnail_url = ""
-            try:
-                from video_processing.thumbnail_generator import generate_and_upload_thumbnail
-
-                thumb_storage_key = f"rendered/{plan_id}/thumbnail.jpg"
-                thumbnail_url = generate_and_upload_thumbnail(str(result.output_path), thumb_storage_key)
-            except Exception as thumb_err:
-                logger.warning(
-                    "[render-adapter] 缩略图生成失败（不影响主流程）: plan_id=%s error=%s",
-                    plan_id,
-                    thumb_err,
-                )
-
-            self._report_progress(progress_cb, 100.0, "渲染完成")
-
-            logger.info(
-                "[render-adapter] render success: plan_id=%s job_id=%s engine=unified "
-                "duration=%.2fs file_size=%d resolution=%dx%d clip_count=%d",
-                plan_id,
-                job_id,
-                result.duration,
-                result.file_size,
-                result.width,
-                result.height,
-                len(ready_clips),
-            )
-
-            return RenderAdapterResult(
-                success=True,
-                output_url=output_url or "",
-                output_path=result.output_path,
-                thumbnail_url=thumbnail_url,
-                duration=result.duration,
-                file_size=result.file_size,
-                width=result.width,
-                height=result.height,
-                clip_count=len(ready_clips),
+                plan_id=plan_id,
+                job_id=job_id,
+                progress_cb=progress_cb,
                 rendered_clip_ids=rendered_clip_ids,
                 failed_clip_ids=failed_clip_ids,
             )
@@ -540,3 +470,215 @@ class RenderAdapter:
         except Exception as e:
             logger.warning("ASR 服务初始化失败，自动字幕将不可用: %s", e)
             return None
+
+    def _do_render(
+        self,
+        plan: Any,
+        clips: list[Any],
+        asset_path_map: dict[str, Path],
+        work_dir: Path,
+        *,
+        plan_id: str,
+        job_id: str = "",
+        progress_cb: ProgressCallback | None = None,
+        rendered_clip_ids: list[str] | None = None,
+        failed_clip_ids: list[str] | None = None,
+    ) -> RenderAdapterResult:
+        """执行统一渲染核心流程（BGM + ASR + 渲染 + 缩略图 + 上传）。
+
+        render_plan 和 render_from_memory 共用此方法。
+
+        Args:
+            rendered_clip_ids: 成功下载/准备的 clip id 列表（render_plan 从下载阶段传入）
+            failed_clip_ids: 失败的 clip id 列表
+
+        Returns:
+            RenderAdapterResult
+        """
+        # 1. 准备 BGM
+        bgm_path = self._prepare_bgm(plan, work_dir, plan_id)
+
+        self._report_progress(progress_cb, 40.0, "执行视频渲染")
+
+        # 2. 初始化 ASR
+        asr_service = self._get_asr_service()
+
+        # 3. 读取输出分辨率
+        plan_config = plan.config or {}
+        export_config = plan_config.get("export", {}) or {}
+        output_width, output_height = _parse_resolution(export_config.get("resolution"))
+        logger.info(
+            "渲染输出分辨率: plan_id=%s resolution=%dx%d source=%s",
+            plan_id,
+            output_width,
+            output_height,
+            "config" if export_config.get("resolution") else "default",
+        )
+
+        # 4. 执行统一渲染
+        render_svc = UnifiedRenderService(
+            plan=plan,
+            clips=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()
+
+        self._report_progress(progress_cb, 80.0, "上传渲染结果")
+
+        # 5. 上传结果
+        storage_key = f"rendered/{plan_id}/{job_id or plan_id}.mp4"
+        output_url = upload_to_oss(result.output_path, storage_key)
+
+        self._report_progress(progress_cb, 90.0, "生成封面缩略图")
+
+        # 6. 生成缩略图
+        thumbnail_url = ""
+        try:
+            from video_processing.thumbnail_generator import generate_and_upload_thumbnail
+
+            thumb_storage_key = f"rendered/{plan_id}/thumbnail.jpg"
+            thumbnail_url = generate_and_upload_thumbnail(str(result.output_path), thumb_storage_key)
+        except Exception as thumb_err:
+            logger.warning(
+                "[render-adapter] 缩略图生成失败（不影响主流程）: plan_id=%s error=%s",
+                plan_id,
+                thumb_err,
+            )
+
+        self._report_progress(progress_cb, 100.0, "渲染完成")
+
+        logger.info(
+            "[render-adapter] render success: plan_id=%s job_id=%s engine=unified "
+            "duration=%.2fs file_size=%d resolution=%dx%d clip_count=%d",
+            plan_id,
+            job_id,
+            result.duration,
+            result.file_size,
+            result.width,
+            result.height,
+            len(clips),
+        )
+
+        final_rendered_ids = (
+            rendered_clip_ids if rendered_clip_ids is not None else [c.id for c in clips if hasattr(c, "id")]
+        )
+        final_failed_ids = failed_clip_ids if failed_clip_ids is not None else []
+
+        return RenderAdapterResult(
+            success=True,
+            output_url=output_url or "",
+            output_path=result.output_path,
+            thumbnail_url=thumbnail_url,
+            duration=result.duration,
+            file_size=result.file_size,
+            width=result.width,
+            height=result.height,
+            clip_count=len(clips),
+            rendered_clip_ids=final_rendered_ids,
+            failed_clip_ids=final_failed_ids,
+        )
+
+    def render_from_memory(
+        self,
+        plan: Any,
+        clips: list[Any],
+        asset_path_map: dict[str, Path],
+        *,
+        plan_id: str = "",
+        job_id: str = "",
+        work_dir: Path | None = None,
+        progress_cb: ProgressCallback | None = None,
+    ) -> RenderAdapterResult:
+        """使用内存中的 plan/clips/asset_path_map 直接渲染。
+
+        适用于一键生成等不写DB剪辑计划的场景，复用统一的 BGM/ASR/分辨率/渲染/缩略图逻辑。
+
+        Args:
+            plan: 类 EditPlan 的对象（鸭子类型，需有 id/config 等属性）
+            clips: 类 EditPlanClip 的对象列表
+            asset_path_map: asset_id → local_path 映射
+            plan_id: 用于日志的计划标识（不传则用 plan.id）
+            job_id: 关联的 Job ID
+            work_dir: 工作目录，不传则用临时目录
+            progress_cb: 进度回调
+
+        Returns:
+            RenderAdapterResult
+        """
+        actual_plan_id = plan_id or getattr(plan, "id", "memory_plan")
+        temp_dir = None
+        try:
+            if work_dir is None:
+                temp_dir = tempfile.mkdtemp(prefix="render_mem_")
+                work_dir = Path(temp_dir)
+            work_dir.mkdir(parents=True, exist_ok=True)
+
+            if not clips:
+                return RenderAdapterResult(
+                    success=False,
+                    error_message="没有可渲染的片段",
+                    clip_count=0,
+                )
+
+            if not asset_path_map:
+                return RenderAdapterResult(
+                    success=False,
+                    error_message="素材路径映射为空",
+                    clip_count=len(clips),
+                )
+
+            logger.info(
+                "开始内存模式渲染: plan_id=%s job_id=%s clip_count=%d engine=unified",
+                actual_plan_id,
+                job_id,
+                len(clips),
+            )
+
+            self._report_progress(progress_cb, 35.0, "准备 BGM 音频")
+
+            return self._do_render(
+                plan=plan,
+                clips=clips,
+                asset_path_map=asset_path_map,
+                work_dir=work_dir,
+                plan_id=actual_plan_id,
+                job_id=job_id,
+                progress_cb=progress_cb,
+            )
+
+        except subprocess.CalledProcessError as exc:
+            stderr_text = (exc.stderr or "").strip()
+            logger.error(
+                "[render-adapter] 内存模式渲染失败: plan_id=%s exit_code=%d\nstderr:\n%s",
+                actual_plan_id,
+                exc.returncode,
+                stderr_text[-2000:] if len(stderr_text) > 2000 else stderr_text,
+            )
+            return RenderAdapterResult(
+                success=False,
+                error_message=f"FFmpeg渲染失败(exit={exc.returncode}): {stderr_text[:200]}",
+                error_detail=stderr_text[-2000:] if len(stderr_text) > 2000 else stderr_text,
+            )
+        except Exception as exc:
+            logger.exception(
+                "[render-adapter] 内存模式渲染失败: plan_id=%s error=%s",
+                actual_plan_id,
+                str(exc)[:200],
+            )
+            return RenderAdapterResult(
+                success=False,
+                error_message=str(exc)[:500],
+            )
+        finally:
+            if temp_dir:
+                import shutil
+
+                try:
+                    shutil.rmtree(temp_dir, ignore_errors=True)
+                except Exception as cleanup_err:
+                    logger.warning("临时目录清理失败: path=%s error=%s", temp_dir, cleanup_err)

apps/worker/video_processing/render_engine_resolver.py

@@ -1,204 +0,0 @@
-"""渲染引擎 Feature Flag 解析器。
-
-封装渲染引擎选择逻辑，支持：
-- 环境变量作为默认值（RENDER_ENGINE=legacy/unified）
-- Redis Feature Flag 运行时覆盖（白名单 + 百分比 + 全局开关）
-- 定时刷新，支持热更新不重启 worker
-
-使用方式：
-    resolver = RenderEngineResolver(redis_url="redis://...", default_engine="legacy")
-    engine = resolver.get_engine(user_id="user123")
-    # engine: "legacy" 或 "unified"
-"""
-
-from __future__ import annotations
-
-import logging
-import threading
-from typing import Optional
-
-from packages.adapters.redis.feature_flag_store import (
-    FeatureFlagConfig,
-    FeatureFlagStore,
-    InMemoryFeatureFlagStore,
-    RedisFeatureFlagStore,
-)
-
-logger = logging.getLogger(__name__)
-
-# Feature Flag 名称常量
-FLAG_RENDER_ENGINE = "render_engine"
-
-# 引擎常量
-ENGINE_LEGACY = "legacy"
-ENGINE_UNIFIED = "unified"
-VALID_ENGINES = {ENGINE_LEGACY, ENGINE_UNIFIED}
-
-
-class RenderEngineResolver:
-    """渲染引擎选择器。
-
-    判定逻辑（从高到低）：
-    1. Redis flag 白名单匹配 → unified
-    2. Redis flag 百分比命中 → unified
-    3. Redis flag 全局开启（100%）→ unified
-    4. 环境变量默认值 → legacy / unified
-
-    当 Redis 不可用时，自动降级到环境变量默认值，不影响业务。
-    """
-
-    def __init__(
-        self,
-        default_engine: str = ENGINE_LEGACY,
-        redis_url: Optional[str] = None,
-        refresh_interval: float = 30.0,
-        store: Optional[FeatureFlagStore] = None,
-    ) -> None:
-        """
-        Args:
-            default_engine: 环境变量默认的引擎名（legacy / unified）
-            redis_url: Redis 连接 URL，传 None 时使用内存实现（测试用）
-            refresh_interval: Redis flag 配置刷新间隔（秒）
-            store: 直接传入 store 实例（测试用，优先级高于 redis_url）
-        """
-        self._default_engine = default_engine.lower() if default_engine else ENGINE_LEGACY
-        if self._default_engine not in VALID_ENGINES:
-            logger.warning(
-                "Invalid default engine '%s', fallback to '%s'",
-                self._default_engine,
-                ENGINE_LEGACY,
-            )
-            self._default_engine = ENGINE_LEGACY
-
-        if store is not None:
-            self._store = store
-        elif redis_url:
-            self._store = RedisFeatureFlagStore(redis_url=redis_url)
-        else:
-            self._store = InMemoryFeatureFlagStore()
-            logger.info("No Redis configured, using in-memory feature flag store")
-
-        self._refresh_interval = refresh_interval
-        self._lock = threading.Lock()
-        self._cached_config: Optional[FeatureFlagConfig] = None
-        self._last_refresh: float = 0.0
-
-    def _maybe_refresh(self) -> None:
-        """惰性刷新配置，超过刷新间隔时从存储重新读取。"""
-        import time
-
-        now = time.time()
-        if now - self._last_refresh < self._refresh_interval:
-            return
-
-        try:
-            config = self._store.get(FLAG_RENDER_ENGINE)
-            with self._lock:
-                self._cached_config = config
-                self._last_refresh = now
-        except Exception as exc:
-            logger.warning("Failed to refresh render engine flag: %s", exc)
-            # 刷新失败时保留旧缓存，不中断业务
-            if self._cached_config is None:
-                # 首次就读失败，设一个默认值
-                with self._lock:
-                    self._cached_config = FeatureFlagConfig(name=FLAG_RENDER_ENGINE)
-                    self._last_refresh = now
-
-    def _get_config(self) -> FeatureFlagConfig:
-        """获取当前 flag 配置（带缓存）。"""
-        if self._cached_config is None:
-            self._maybe_refresh()
-        else:
-            self._maybe_refresh()
-        return self._cached_config or FeatureFlagConfig(name=FLAG_RENDER_ENGINE)
-
-    def get_engine(self, user_id: Optional[str] = None) -> str:
-        """获取当前应该使用的渲染引擎。
-
-        Args:
-            user_id: 用户ID，用于白名单匹配和百分比哈希。
-                    传 None 时只看全局开关。
-
-        Returns:
-            "legacy" 或 "unified"
-        """
-        config = self._get_config()
-
-        # 全局关闭 → 用默认值
-        if not config.enabled:
-            return self._default_engine
-
-        # 白名单匹配 / 百分比命中 → unified
-        if config.is_active(user_id):
-            return ENGINE_UNIFIED
-
-        # 未命中灰度 → 用默认值
-        return self._default_engine
-
-    def should_use_unified(self, user_id: Optional[str] = None) -> bool:
-        """便捷方法：是否应该使用统一渲染引擎。"""
-        return self.get_engine(user_id) == ENGINE_UNIFIED
-
-    def force_refresh(self) -> None:
-        """强制立即刷新配置（用于管理接口修改后立即生效）。"""
-        self._last_refresh = 0.0
-        if isinstance(self._store, RedisFeatureFlagStore):
-            self._store.invalidate_cache(FLAG_RENDER_ENGINE)
-        self._maybe_refresh()
-
-    def get_config_snapshot(self) -> dict:
-        """获取当前配置快照（用于管理接口展示）。"""
-        config = self._get_config()
-        return {
-            "flag_name": FLAG_RENDER_ENGINE,
-            "default_engine": self._default_engine,
-            "enabled": config.enabled,
-            "percentage": config.percentage,
-            "whitelist": sorted(config.whitelist),
-            "refresh_interval": self._refresh_interval,
-            "last_refresh": self._last_refresh,
-        }
-
-    def set_flag(self, config: FeatureFlagConfig) -> None:
-        """设置 flag 配置（管理接口用）。"""
-        config.name = FLAG_RENDER_ENGINE
-        self._store.set(config)
-        self.force_refresh()
-
-
-# 全局单例
-_resolver: Optional[RenderEngineResolver] = None
-_resolver_lock = threading.Lock()
-
-
-def get_render_engine_resolver() -> RenderEngineResolver:
-    """获取全局单例（基于 worker 配置）。"""
-    global _resolver
-    if _resolver is not None:
-        return _resolver
-
-    with _resolver_lock:
-        if _resolver is not None:
-            return _resolver
-
-        try:
-            from worker_app.core.config import get_settings
-
-            settings = get_settings()
-            redis_url = getattr(settings, "redis_url", None) or getattr(settings, "broker_url", None)
-            default = getattr(settings, "render_engine", ENGINE_LEGACY)
-            _resolver = RenderEngineResolver(
-                default_engine=default,
-                redis_url=redis_url,
-            )
-            logger.info(
-                "RenderEngineResolver initialized: default=%s, redis=%s",
-                default,
-                bool(redis_url),
-            )
-        except Exception as exc:
-            logger.warning("Failed to init RenderEngineResolver from settings: %s", exc)
-            _resolver = RenderEngineResolver(default_engine=ENGINE_LEGACY)
-
-    return _resolver

apps/worker/video_processing/unified_render_service.py

@@ -188,6 +188,8 @@ class UnifiedRenderService:
         self.bgm_path = bgm_path
         self._transition_engine = TransitionEngine(default_duration=transition_duration)
         self._speed_engine = SpeedEngine()
+        self._asr_timeline_cache: Any = None  # ASR 字幕结果缓存，避免重复调用
+        self._asr_timeline_cached = False
 
     def render(self) -> RenderResult:
         """执行渲染，返回 RenderResult.
@@ -589,7 +591,13 @@ class UnifiedRenderService:
 
         MVP 版本：使用第一个有音频的素材做ASR，然后按比例映射到整个视频时长。
         后续优化：支持多片段拼接后的完整音频ASR。
+
+        带缓存：同一 plan 只做一次 ASR，TTS 配音和字幕共用结果。
         """
+        # 检查缓存
+        if self._asr_timeline_cached:
+            return self._asr_timeline_cache
+
         from packages.domain.subtitle import SubtitleTimeline
 
         # 找第一个有本地路径的素材
@@ -602,7 +610,10 @@ class UnifiedRenderService:
 
         if first_asset_path is None:
             logger.warning("ASR字幕生成失败：找不到可用素材音频")
-            return SubtitleTimeline(segments=[], total_duration=video_duration)
+            result = SubtitleTimeline(segments=[], total_duration=video_duration)
+            self._asr_timeline_cache = result
+            self._asr_timeline_cached = True
+            return result
 
         # 提取素材音频为 wav（16kHz单声道，ASR友好格式）
         audio_path = self.work_dir / f"asr_audio_{self.plan.id}.wav"
@@ -637,6 +648,9 @@ class UnifiedRenderService:
         except Exception:
             pass
 
+        # 存入缓存
+        self._asr_timeline_cache = timeline
+        self._asr_timeline_cached = True
         return timeline
 
     def _extract_audio(self, video_path: Path, output_path: Path) -> None:
@@ -669,11 +683,75 @@ class UnifiedRenderService:
     ) -> bool:
         """根据 plan.config 生成 TTS 配音，加到 audio 图层.
 
+        支持三种触发方式：
+        1. config.tts.enabled = true → 标准 TTS 配置
+        2. 顶层 voice_id + custom_text → 桥接模式（自定义文案配音）
+        3. 顶层 voice_id + subtitle.auto_generated=true → ASR 字幕对齐配音（预设配音）
+
         Returns:
             是否成功添加了配音音轨
         """
         config = self.plan.config or {}
         tts_cfg = config.get("tts", {}) or {}
+        subtitle_cfg = config.get("subtitle", {}) or {}
+        use_subtitle_align = False  # 是否使用字幕对齐模式
+
+        # 兼容前端顶层字段：voice_id / custom_text / voice_clone_profile_id
+        if not tts_cfg.get("enabled"):
+            top_voice_id = config.get("voice_id", "") or ""
+            top_text = config.get("custom_text", "") or ""
+
+            # 方式A：voice_id + custom_text → 整段配音
+            if top_voice_id and top_text:
+                tts_cfg = {
+                    "enabled": True,
+                    "voice_id": top_voice_id,
+                    "text": top_text,
+                    "align_mode": "full",
+                    "overlap_mode": "replace",
+                }
+                logger.info(
+                    "[unified-render] 检测到顶层 voice_id+custom_text，桥接到 tts 配置（整段）: plan_id=%s voice_id=%s text_len=%d",
+                    self.plan.id,
+                    top_voice_id,
+                    len(top_text),
+                )
+            # 方式B：voice_id + 自动字幕 → 字幕对齐配音（预设配音模式）
+            elif top_voice_id and subtitle_cfg.get("auto_generated", False) and self.asr_service is not None:
+                tts_cfg = {
+                    "enabled": True,
+                    "voice_id": top_voice_id,
+                    "text": "",
+                    "align_mode": "subtitle",
+                    "overlap_mode": "replace",
+                }
+                use_subtitle_align = True
+                logger.info(
+                    "[unified-render] 检测到预设配音+自动字幕，使用字幕对齐模式: plan_id=%s voice_id=%s",
+                    self.plan.id,
+                    top_voice_id,
+                )
+
+        # 兼容前端顶层字段：voice_id / custom_text / voice_clone_profile_id
+        # 前端一键生成页面传 config.voice_id + config.custom_text，
+        # 统一渲染引擎从 config.tts 读，这里做桥接映射。
+        if not tts_cfg.get("enabled"):
+            top_voice_id = config.get("voice_id", "") or ""
+            top_text = config.get("custom_text", "") or ""
+            if top_voice_id and top_text:
+                tts_cfg = {
+                    "enabled": True,
+                    "voice_id": top_voice_id,
+                    "text": top_text,
+                    "align_mode": "full",
+                    "overlap_mode": "replace",
+                }
+                logger.info(
+                    "[unified-render] 检测到顶层 voice_id+custom_text，桥接到 tts 配置: plan_id=%s voice_id=%s text_len=%d",
+                    self.plan.id,
+                    top_voice_id,
+                    len(top_text),
+                )
 
         tts_config = TtsConfig.parse(tts_cfg)
         if not tts_config.enabled:
@@ -685,8 +763,34 @@ class UnifiedRenderService:
             tts_service = get_tts_service()
             tts_engine = TtsEngine(tts_service, self.work_dir / "tts")
 
-            # 整段配音模式
-            result = tts_engine.generate_full_voiceover(tts_config, total_duration=video_duration)
+            # 根据对齐模式选择生成方式
+            if use_subtitle_align or tts_config.align_mode == "subtitle":
+                # 字幕对齐模式：先做 ASR，再按字幕生成配音
+                if not self._asr_timeline_cached:
+                    self._generate_asr_subtitles(video_duration, subtitle_cfg)
+                timeline = self._asr_timeline_cache
+                if timeline is None or not timeline.segments:
+                    logger.warning("TTS 字幕对齐配音：ASR 无识别结果，跳过配音")
+                    return False
+
+                # 转换为 TtsEngine 需要的字幕格式
+                subtitles = [
+                    {
+                        "text": seg.text,
+                        "start_time": seg.start,
+                        "end_time": seg.end,
+                    }
+                    for seg in timeline.segments
+                    if getattr(seg, "text", "").strip()
+                ]
+                if not subtitles:
+                    logger.warning("TTS 字幕对齐配音：字幕文本为空，跳过配音")
+                    return False
+
+                result = tts_engine.generate_subtitle_voiceover(tts_config, subtitles)
+            else:
+                # 整段配音模式
+                result = tts_engine.generate_full_voiceover(tts_config, total_duration=video_duration)
 
             if not result.success or not result.segments:
                 logger.warning("TTS 配音生成失败，跳过: %s", result.error_message)
@@ -1050,8 +1154,10 @@ class UnifiedRenderService:
 
         vf_str = ",".join(filters)
 
-        # 最终输出时长：取 clip 有效时长和 video_duration 的较小值
-        final_duration = effective_duration
+        # 最终输出时长：取 clip 调速后有效时长和 video_duration 的较小值
+        # 注意：必须用调速后的时长，否则减速场景（speed<1）会被 -t 截断
+        adjusted_duration = UnifiedRenderService._clip_adjusted_duration(clip)
+        final_duration = adjusted_duration
         if video_duration > 0 and (final_duration <= 0 or final_duration > video_duration):
             final_duration = video_duration
 

apps/worker/worker_app/core/config.py

@@ -19,9 +19,6 @@ class WorkerSettings(BaseSettings):
     auto_create_schema: bool = False
     redis_url: str = "redis://redis:6379/0"
 
-    # 渲染引擎选择：legacy=旧VideoComposeService，unified=新UnifiedRenderService
-    render_engine: str = "legacy"
-
     model_config = SettingsConfigDict(
         env_file=".env",
         env_file_encoding="utf-8",

apps/worker/worker_app/tasks/compose_video.py

@@ -1,6 +1,6 @@
 """视频合成 Celery 任务 — Phase 8 任务 2.10.
 
-使用 JobService 管理任务生命周期，集成 VideoComposeService 执行合成。
+使用 JobService 管理任务生命周期，通过 RenderAdapter 调用 UnifiedRenderService 执行合成。
 """
 
 from __future__ import annotations
@@ -35,9 +35,7 @@ def _get_job_service():
 def compose_video(self, job_id: str, **kwargs):
     """视频合成任务。
 
-    根据 RENDER_ENGINE 配置选择渲染引擎：
-      - legacy: 旧 VideoComposeService（filter_complex 模式）
-      - unified: 新 UnifiedRenderService（图层架构）
+    使用 UnifiedRenderService（图层架构）进行渲染。
 
     Args:
         job_id: JobService 中的任务 ID
@@ -56,30 +54,8 @@ def compose_video(self, job_id: str, **kwargs):
             job_service.fail_job(job_id, "Missing plan_id in job payload")
             return {"status": "error", "message": "Missing plan_id"}
 
-        # 判断使用哪个渲染引擎
-        # 优先级：Redis Feature Flag（白名单 > 百分比） > 环境变量默认
-        from video_processing.render_engine_resolver import get_render_engine_resolver
-
-        resolver = get_render_engine_resolver()
-        user_id = job.created_by_user_id or None
-        engine = resolver.get_engine(user_id=user_id)
-        # 灰度期间打印详细 flag 配置，便于排查
-        config = resolver.get_config_snapshot()
-        logger.info(
-            "compose_video 引擎选择: job_id=%s engine=%s user_id=%s enabled=%s percentage=%s whitelist=%d default=%s",
-            job_id,
-            engine,
-            user_id,
-            config.get("enabled"),
-            config.get("percentage"),
-            len(config.get("whitelist", [])),
-            config.get("default_engine"),
-        )
-
-        if engine == "unified":
-            return _compose_with_unified_engine(self, job_service, job, plan_id, db)
-        else:
-            return _compose_with_legacy_engine(self, job_service, job, plan_id, db)
+        # 使用 unified 渲染引擎
+        return _compose_with_unified_engine(self, job_service, job, plan_id, db)
 
     except self.retry_exc as exc:
         logger.warning("视频合成重试中: job_id=%s, exc=%s", job_id, exc)
@@ -95,69 +71,6 @@ def compose_video(self, job_id: str, **kwargs):
         db.close()
 
 
-def _compose_with_legacy_engine(task, job_service, job, plan_id: str, db) -> dict:
-    """旧引擎渲染路径（VideoComposeService）。"""
-    job_id = job.id
-
-    # 标记为 running
-    job_service.update_progress(job_id, progress=10.0, current_stage="初始化合成环境")
-
-    # 延迟导入 VideoComposeService
-    from apps.api.app.services.video_compose_service import VideoComposeService
-
-    compose_svc = VideoComposeService(db)
-
-    # 校验合成条件
-    job_service.update_progress(job_id, progress=20.0, current_stage="校验合成条件")
-    validation = compose_svc.validate_compose(plan_id)
-    if not validation.valid:
-        error_msg = "; ".join(validation.errors)
-        job_service.fail_job(job_id, f"合成校验失败: {error_msg}")
-        return {"status": "error", "message": error_msg}
-
-    # 构建合成命令
-    job_service.update_progress(job_id, progress=30.0, current_stage="构建 FFmpeg 命令")
-    _output_dir = os.environ.get("VIDEO_OUTPUT_DIR", os.path.join(tempfile.gettempdir(), "video_output"))
-    output_path = os.path.join(_output_dir, f"{job_id}.mp4")
-    compose_cmd = compose_svc.build_compose_command(plan_id, output_path)
-
-    # 执行 FFmpeg
-    job_service.update_progress(job_id, progress=50.0, current_stage="正在执行视频合成")
-    logger.info("Executing FFmpeg for job %s, plan %s", job_id, plan_id)
-
-    try:
-        from video_processing.ffmpeg_utils import run_ffmpeg
-
-        run_ffmpeg(compose_cmd.command, timeout=3600)
-    except Exception as e:
-        error_msg = f"FFmpeg 执行失败: {str(e)[:500]}"
-        job_service.fail_job(job_id, error_msg)
-        raise
-
-    # 上传结果
-    job_service.update_progress(job_id, progress=80.0, current_stage="上传合成结果")
-    storage_key = f"rendered/{plan_id}/{job_id}.mp4"
-
-    from worker_app.tasks.edit_plan_generation import _upload_to_oss
-
-    output_url = _upload_to_oss(Path(output_path), storage_key)
-
-    # 更新 Job 状态为完成
-    result_data = {
-        "plan_id": plan_id,
-        "output_path": output_path,
-        "storage_key": storage_key,
-        "output_url": output_url or "",
-        "estimated_duration": compose_cmd.estimated_duration,
-        "clip_count": len(compose_cmd.clip_chains),
-        "engine": "legacy",
-    }
-    job_service.complete_job(job_id, result=result_data)
-
-    logger.info("视频合成完成(legacy): job_id=%s, plan_id=%s", job_id, plan_id)
-    return {"status": "completed", "job_id": job_id, "result": result_data}
-
-
 def _compose_with_unified_engine(task, job_service, job, plan_id: str, db) -> dict:
     """新引擎渲染路径（UnifiedRenderService + RenderAdapter）。"""
     job_id = job.id

apps/worker/worker_app/tasks/edit_plan_generation.py

@@ -1,24 +1,18 @@
-"""剪辑计划渲染任务 — 支持 Feature Flag 灰度.
+"""剪辑计划渲染任务 — 使用 UnifiedRenderService 统一渲染引擎.
 
 Celery 任务 worker.render_edit_plan:
   1. 加载 EditPlan + EditPlanClips
-  2. 根据 Feature Flag 选择渲染引擎（legacy / unified）
+  2. 通过 RenderAdapter 调用 UnifiedRenderService 渲染
   3. 下载各片段素材 + 渲染
   4. 上传渲染结果到 OSS
   5. 创建 GeneratedVideo 记录 + 查重
   6. 更新 EditPlan / EditPlanClip 状态
   7. 更新 GenerationTask 进度
-
-渲染引擎灰度：
-  - 走 Feature Flag (render_engine) 控制
-  - legacy: VideoComposeService + FFmpeg filter_complex
-  - unified: UnifiedRenderService 图层架构
 """
 
 from __future__ import annotations
 
 import logging
-import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -35,10 +29,6 @@ OUTPUT_FPS = 25.0
 # ── 共享工具模块导入 ──────────────────────────────────────────────────────────
 
 from video_processing.dedup_helpers import create_video_record_and_dedup
-from video_processing.oss_helpers import (
-    download_asset,
-    upload_to_oss,
-)
 
 # ── Repository imports (延迟导入避免循环依赖) ─────────────────────────────────
 
@@ -66,34 +56,6 @@ def _get_repos():
 # ── Celery Task ───────────────────────────────────────────────────────────────
 
 
-def _resolve_render_engine(user_id: str) -> str:
-    """根据 Feature Flag 决定使用哪个渲染引擎。
-
-    Returns:
-        "legacy" 或 "unified"
-    """
-    try:
-        from video_processing.render_engine_resolver import get_render_engine_resolver
-
-        resolver = get_render_engine_resolver()
-        engine = resolver.get_engine(user_id=user_id)
-        # 灰度期间打印详细 flag 配置，便于排查
-        config = resolver.get_config_snapshot()
-        logger.info(
-            "edit_plan 引擎选择: user_id=%s engine=%s enabled=%s percentage=%s whitelist=%d default=%s",
-            user_id,
-            engine,
-            config.get("enabled"),
-            config.get("percentage"),
-            len(config.get("whitelist", [])),
-            config.get("default_engine"),
-        )
-        return engine
-    except Exception as exc:
-        logger.warning("获取渲染引擎配置失败，fallback 到 legacy: %s", exc, exc_info=True)
-        return "legacy"
-
-
 def _mark_plan_failed(plan_repo, plan_id, gen_task_repo, generation_task_id, error_msg: str):
     """统一的计划失败标记工具。"""
     plan = plan_repo.get(plan_id)
@@ -311,331 +273,13 @@ def _render_with_unified(
     )
 
 
-def _render_with_legacy(
-    plan,
-    clips,
-    rendered_clip_ids: list[str],
-    failed_clip_ids: list[str],
-    tmpdir_path: Path,
-    plan_id: str,
-    generation_task_id: str,
-    plan_repo,
-    clip_repo,
-    gen_task_repo,
-    db,
-) -> dict:
-    """旧引擎路径（VideoComposeService + FFmpeg filter_complex）。"""
-    import os
-
-    from apps.api.app.services.video_compose_service import VideoComposeService
-
-    compose_svc = VideoComposeService(db)
-
-    # 校验合成条件
-    validation = compose_svc.validate_compose(plan_id)
-    if not validation.valid:
-        error_msg = "; ".join(validation.errors)
-        logger.error("合成校验失败(legacy): %s — %s", plan_id, error_msg)
-        _mark_plan_failed(plan_repo, plan_id, gen_task_repo, generation_task_id, f"合成校验失败: {error_msg}")
-        return {"status": "error", "message": error_msg}
-
-    # 构建 FFmpeg 命令
-    output_dir = os.environ.get("VIDEO_OUTPUT_DIR", str(tmpdir_path))
-    output_path = Path(output_dir) / f"{plan_id}.mp4"
-
-    # 从 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 cmd=%s", plan_id, " ".join(compose_cmd.command)[:500])
-
-    # 开始渲染，更新进度
-    if generation_task_id:
-        try:
-            gen_task = gen_task_repo.get(generation_task_id)
-            if gen_task and gen_task.progress < 40.0:
-                gen_task.progress = 40.0
-                gen_task.append_log(
-                    stage="render_start",
-                    message="开始FFmpeg渲染（legacy）",
-                    level="INFO",
-                    progress=40.0,
-                )
-                gen_task_repo.update(gen_task)
-        except Exception:
-            pass
-
-    try:
-        from video_processing.ffmpeg_utils import run_ffmpeg
-
-        run_ffmpeg(compose_cmd.command, timeout=3600)
-    except Exception as e:
-        # 提取完整 stderr（如果是 CalledProcessError）
-        stderr_text = ""
-        if hasattr(e, "stderr"):
-            stderr_raw = e.stderr
-            if isinstance(stderr_raw, bytes):
-                stderr_text = stderr_raw.decode("utf-8", errors="replace")
-            elif isinstance(stderr_raw, str):
-                stderr_text = stderr_raw
-
-        # 完整命令（截断前2000字符，避免日志过大）
-        full_cmd = " ".join(compose_cmd.command)
-        cmd_preview = full_cmd[:2000] + ("..." if len(full_cmd) > 2000 else "")
-
-        # 拼接完整错误信息：命令 + 异常 + stderr最后1500字符
-        error_parts = [f"FFmpeg渲染失败(exit={getattr(e, 'returncode', 'unknown')})"]
-        error_parts.append("--- cmd ---")
-        error_parts.append(cmd_preview)
-        if stderr_text:
-            # 取最后1500字符，通常错误信息在末尾
-            stderr_preview = stderr_text[-1500:] if len(stderr_text) > 1500 else stderr_text
-            error_parts.append("--- stderr (last 1500 chars) ---")
-            error_parts.append(stderr_preview)
-        error_msg = "\n".join(error_parts)
-
-        logger.error("FFmpeg 执行失败(legacy): plan_id=%s\n%s", plan_id, error_msg)
-        _mark_plan_failed(plan_repo, plan_id, gen_task_repo, generation_task_id, error_msg)
-        return {"status": "error", "message": error_msg}
-
-    # 获取文件大小 + 实际时长
-    file_size = output_path.stat().st_size if output_path.exists() else 0
-    duration = compose_cmd.estimated_duration or 0.0
-    try:
-        from video_processing.ffmpeg_utils import probe_duration
-
-        actual_duration = probe_duration(str(output_path))
-        if actual_duration > 0:
-            duration = actual_duration
-    except Exception:
-        pass
-
-    # ── 标题/字幕叠加（legacy 引擎补齐） ────────────────────────────────
-    plan_config = plan.config or {}
-    title_cfg = plan_config.get("title", {}) or {}
-    subtitle_cfg = plan_config.get("subtitle", {}) or {}
-    title_text = title_cfg.get("text", "") or ""
-    subtitle_text = subtitle_cfg.get("text", "") or ""
-    title_enabled = title_cfg.get("enabled", True) and bool(title_text.strip())
-    subtitle_enabled = subtitle_cfg.get("enabled", True) and bool(subtitle_text.strip())
-    # ASR 自动字幕 legacy 暂不支持（需要额外 ASR 服务，统一用 unified 引擎）
-    has_subtitle_overlay = title_enabled or subtitle_enabled
-
-    if has_subtitle_overlay and output_path.exists() and duration > 0:
-        try:
-            from video_processing.ffmpeg_utils import run_ffmpeg
-            from video_processing.render_subtitles import generate_ass_subtitles
-
-            ass_path = tmpdir_path / f"subtitles_{plan_id}.ass"
-            generate_ass_subtitles(
-                ass_path,
-                video_width=output_width,
-                video_height=output_height,
-                video_duration=duration,
-                title_text=title_text,
-                title_config=title_cfg,
-                subtitle_text=subtitle_text,
-                subtitle_config=subtitle_cfg,
-            )
-            # 用 subtitles 滤镜叠加 ASS 字幕，音频直接 copy
-            subtitled_path = tmpdir_path / f"{plan_id}_subtitled.mp4"
-            # 处理 Windows 路径下的 ass 滤镜转义问题
-            ass_filter_path = str(ass_path).replace("\\", "/").replace(":", r"\:")
-            run_ffmpeg(
-                [
-                    "ffmpeg",
-                    "-y",
-                    "-i",
-                    str(output_path),
-                    "-vf",
-                    f"subtitles='{ass_filter_path}'",
-                    "-c:a",
-                    "copy",
-                    str(subtitled_path),
-                ],
-                timeout=1800,
-            )
-            if subtitled_path.exists() and subtitled_path.stat().st_size > 0:
-                output_path = subtitled_path
-                file_size = subtitled_path.stat().st_size
-                logger.info(
-                    "legacy 标题/字幕叠加完成: plan_id=%s title=%s subtitle=%s",
-                    plan_id,
-                    title_enabled,
-                    subtitle_enabled,
-                )
-        except Exception as sub_err:
-            logger.warning("legacy 标题/字幕叠加失败（不影响主流程）: plan_id=%s err=%s", plan_id, sub_err)
-
-    # ── TTS 配音混音（legacy 引擎补齐） ────────────────────────────────
-    tts_cfg = plan_config.get("tts", {}) or {}
-    tts_enabled = tts_cfg.get("enabled", False) and bool(tts_cfg.get("text", "").strip())
-
-    if tts_enabled and output_path.exists() and duration > 0:
-        try:
-            from packages.domain.tts_config import TtsConfig
-
-            tts_config = TtsConfig.parse(tts_cfg)
-            if tts_config.enabled and tts_config.text.strip():
-                from apps.worker.services.tts_service_factory import get_tts_service
-
-                tts_service = get_tts_service()
-                voiceover_path = tmpdir_path / f"voiceover_{plan_id}.wav"
-
-                # 生成配音音频
-                audio_path = tts_service.synthesize(
-                    text=tts_config.text,
-                    voice_id=tts_config.voice_id,
-                    speed=tts_config.speed,
-                    pitch=tts_config.pitch,
-                    output_path=voiceover_path,
-                )
-
-                if audio_path and audio_path.exists() and audio_path.stat().st_size > 0:
-                    from video_processing.ffmpeg_utils import run_ffmpeg
-
-                    mixed_path = tmpdir_path / f"{plan_id}_with_voiceover.mp4"
-
-                    # 混音：配音音量按配置调整
-                    voice_volume = max(0.0, min(1.0, tts_config.volume))
-
-                    if tts_config.overlap_mode == "mix":
-                        # 混音模式：原音 + 配音混合
-                        filter_complex = (
-                            f"[0:a]volume=1.0[a0];"
-                            f"[1:a]volume={voice_volume:.2f}[a1];"
-                            f"[a0][a1]amix=inputs=2:duration=first:dropout_transition=0[aout]"
-                        )
-                    else:
-                        # replace 模式：配音替换原音
-                        filter_complex = f"[1:a]volume={voice_volume:.2f}[aout]"
-
-                    run_ffmpeg(
-                        [
-                            "ffmpeg",
-                            "-y",
-                            "-i",
-                            str(output_path),
-                            "-i",
-                            str(audio_path),
-                            "-filter_complex",
-                            filter_complex,
-                            "-map",
-                            "0:v",
-                            "-map",
-                            "[aout]",
-                            "-c:v",
-                            "copy",
-                            "-c:a",
-                            "aac",
-                            "-b:a",
-                            "128k",
-                            "-shortest",
-                            str(mixed_path),
-                        ],
-                        timeout=1800,
-                    )
-
-                    if mixed_path.exists() and mixed_path.stat().st_size > 0:
-                        output_path = mixed_path
-                        file_size = mixed_path.stat().st_size
-                        logger.info(
-                            "legacy TTS 配音混音完成: plan_id=%s voice_id=%s mode=%s",
-                            plan_id,
-                            tts_config.voice_id,
-                            tts_config.overlap_mode,
-                        )
-        except Exception as tts_err:
-            logger.warning("legacy TTS 配音混音失败（不影响主流程）: plan_id=%s err=%s", plan_id, tts_err)
-
-    # 渲染完成，更新进度
-    if generation_task_id:
-        try:
-            gen_task = gen_task_repo.get(generation_task_id)
-            if gen_task and gen_task.progress < 80.0:
-                gen_task.progress = 80.0
-                gen_task.append_log(
-                    stage="render_done",
-                    message="FFmpeg渲染完成（legacy）",
-                    level="INFO",
-                    progress=80.0,
-                )
-                gen_task_repo.update(gen_task)
-        except Exception:
-            pass
-
-    # 上传到 OSS
-    storage_key = f"rendered/{plan_id}/output.mp4"
-    output_url = upload_to_oss(output_path, storage_key)
-
-    # 上传完成，更新进度
-    if generation_task_id:
-        try:
-            gen_task = gen_task_repo.get(generation_task_id)
-            if gen_task and gen_task.progress < 95.0:
-                gen_task.progress = 95.0
-                gen_task.append_log(
-                    stage="upload_done",
-                    message="OSS上传完成（legacy）",
-                    level="INFO",
-                    progress=95.0,
-                )
-                gen_task_repo.update(gen_task)
-        except Exception:
-            pass
-
-    return _finalize_render_success(
-        plan=plan,
-        plan_repo=plan_repo,
-        clip_repo=clip_repo,
-        gen_task_repo=gen_task_repo,
-        db=db,
-        plan_id=plan_id,
-        output_url=output_url or "",
-        storage_key=storage_key,
-        duration=duration,
-        file_size=file_size,
-        width=output_width,
-        height=output_height,
-        rendered_clip_ids=rendered_clip_ids,
-        failed_clip_ids=failed_clip_ids,
-        generation_task_id=generation_task_id,
-        output_path=output_path,
-        engine="legacy",
-    )
-
-
 @celery_app.task(name="worker.render_edit_plan", bind=True, max_retries=2)
 def render_edit_plan(self, plan_id: str) -> dict:
     """渲染剪辑计划
 
     流程：
     1. 加载 EditPlan + EditPlanClips
-    2. 根据 Feature Flag 选择渲染引擎（legacy / unified）
+    2. 通过 RenderAdapter 调用 UnifiedRenderService 渲染
     3. 下载素材 + 渲染
     4. 上传渲染结果到 OSS
     5. 创建 GeneratedVideo 记录 + 查重
@@ -645,7 +289,6 @@ def render_edit_plan(self, plan_id: str) -> dict:
     logger.info("开始渲染剪辑计划: plan_id=%s", plan_id)
 
     generation_task_id = ""
-    engine = "legacy"
 
     for repos in _get_repos():
         plan_repo, clip_repo, gen_task_repo, db = repos
@@ -660,10 +303,7 @@ def render_edit_plan(self, plan_id: str) -> dict:
             # 获取 generation_task_id（提前读取，确保 except 块可用）
             generation_task_id = plan.config.get("generation_task_id", "")
 
-            # 2. 选择渲染引擎（Feature Flag 灰度控制）
-            user_id = plan.created_by_user_id or ""
-            engine = _resolve_render_engine(user_id)
-            logger.info("剪辑计划渲染引擎: plan_id=%s engine=%s user_id=%s", plan_id, engine, user_id)
+            # 2. 准备渲染（使用 unified 渲染引擎）
 
             # 3. 加载片段列表（按 order 排序）
             clips = clip_repo.list_by_plan(plan_id, skip=0, limit=10000)
@@ -681,9 +321,9 @@ def render_edit_plan(self, plan_id: str) -> dict:
                     gen_task.started_at = datetime.now(timezone.utc)
                     gen_task.append_log(
                         stage="render_start",
-                        message=f"开始渲染，引擎 {engine}，片段数 {len(clips)}",
+                        message=f"开始渲染，片段数 {len(clips)}",
                         level="INFO",
-                        engine=engine,
+                        engine="unified",
                         clip_count=len(clips),
                     )
                     gen_task_repo.update(gen_task)
@@ -706,122 +346,19 @@ def render_edit_plan(self, plan_id: str) -> dict:
                                 pass
                         return {"status": "cancelled", "plan_id": plan_id, "message": "任务已取消"}
 
-            # 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] = []
+            # 4. 渲染（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,
+            )
 
-                    # 预先批量查询所有素材的 storage_key
-                    # 兼容存量数据：storage_key 为空时 fallback 到 file_url
-                    from packages.adapters.sqlalchemy_impl.models import AssetModel
-
-                    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
-                        }
-
-                    for clip in clips:
-                        if not clip.asset_id:
-                            # 没有素材的片段跳过，标记为失败
-                            clip.mark_failed()
-                            clip_repo.update(clip)
-                            failed_clip_ids.append(clip.id)
-                            continue
-
-                        if clip.asset_id in asset_path_map:
-                            # 同一素材已下载（多个 clip 共享同一素材）
-                            rendered_clip_ids.append(clip.id)
-                            continue
-
-                        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.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)
-
-                    result = _render_with_legacy(
-                        plan=plan,
-                        clips=clips,
-                        rendered_clip_ids=rendered_clip_ids,
-                        failed_clip_ids=failed_clip_ids,
-                        tmpdir_path=tmpdir_path,
-                        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,
-                    )
-
-            result["engine"] = engine
+            result["engine"] = "unified"
             return result
 
         except Exception as exc:

apps/worker/worker_app/tasks/generation.py

@@ -138,7 +138,6 @@ def _flush_logs(task_id: str, gen_task) -> None:
 
 # ── 共享工具模块导入 ──────────────────────────────────────────────────────────
 
-from services.asr_service_factory import get_asr_service
 from video_processing.dedup_helpers import create_video_record_and_dedup
 from video_processing.ffmpeg_utils import FFMPEG_BIN, probe_duration, run_ffmpeg
 from video_processing.oss_helpers import (
@@ -146,8 +145,6 @@ from video_processing.oss_helpers import (
     get_signed_download_url,
     upload_to_oss,
 )
-from video_processing.render_engine_resolver import ENGINE_LEGACY, ENGINE_UNIFIED
-from video_processing.unified_render_service import UnifiedRenderService
 
 # ── 虚拟 Plan / Clip（内存中构建，不写数据库） ────────────────────────────────
 
@@ -944,13 +941,31 @@ def _download_library_assets(
 def _validate_template_exists(template_id: str) -> None:
     """校验 template_id 是否存在且可用。
 
+    优先读新模板系统（EditTemplate），找不到 fallback 到旧模板系统（TemplateModel）。
+
     Raises:
         ValueError: template_id 不存在或已禁用时抛出
     """
-    from packages.adapters.sqlalchemy_impl.models import TemplateModel
+    from packages.adapters.sqlalchemy_impl import (
+        SQLAlchemyEditTemplateRepository,
+    )
 
     session = SessionLocal()
     try:
+        # 优先读新模板系统
+        new_repo = SQLAlchemyEditTemplateRepository(session)
+        new_template = new_repo.get(template_id)
+        if new_template is not None:
+            status_val = new_template.status.value if hasattr(new_template.status, "value") else new_template.status
+            if status_val == "active":
+                logger.info("模板校验通过(新系统): template_id=%s name=%s", template_id, new_template.name)
+                return
+            else:
+                raise ValueError(f"模板已停用: template_id={template_id}")
+
+        # fallback: 旧模板系统
+        from packages.adapters.sqlalchemy_impl.models import TemplateModel
+
         template = (
             session.query(TemplateModel)
             .filter(
@@ -959,9 +974,11 @@ def _validate_template_exists(template_id: str) -> None:
             )
             .first()
         )
-        if template is None:
-            raise ValueError(f"模板不存在或已禁用: template_id={template_id}")
-        logger.info("模板校验通过: template_id=%s name=%s", template_id, template.name)
+        if template:
+            logger.info("模板校验通过(旧系统): template_id=%s name=%s", template_id, template.name)
+            return
+
+        raise ValueError(f"模板不存在或已禁用: template_id={template_id}")
     finally:
         session.close()
 
@@ -969,17 +986,51 @@ def _validate_template_exists(template_id: str) -> None:
 def _load_template_plan_config(template_id: str) -> dict:
     """从模板加载 plan 级配置（BGM、字幕、标题等效果层）。
 
-    TemplateModel 里 bgm_config / subtitle_config / title_config 是独立字段，
-    需要组装成 plan.config 的格式（{bgm, subtitle, title}）后再注入。
+    优先读新模板系统（EditTemplate.config + TemplateClipConfig），
+    找不到 fallback 到旧模板系统（TemplateModel 独立字段）。
+
     模板不存在时返回空 dict，不阻塞主流程。
     """
     if not template_id:
         return {}
     try:
-        from packages.adapters.sqlalchemy_impl.models import TemplateModel
+        from packages.adapters.sqlalchemy_impl import (
+            SQLAlchemyEditTemplateRepository,
+            SQLAlchemyTemplateClipConfigRepository,
+        )
 
         session = SessionLocal()
         try:
+            # 优先读新模板系统
+            tpl_repo = SQLAlchemyEditTemplateRepository(session)
+            clip_repo = SQLAlchemyTemplateClipConfigRepository(session)
+            template = tpl_repo.get(template_id)
+
+            if template is not None:
+                # 新系统：config 直接就是 plan.config 格式
+                plan_config = dict(template.config or {})
+
+                # 从片段配置中提取 intro/outro 配置
+                clip_configs = clip_repo.list_by_template(template_id, limit=200)
+                if clip_configs:
+                    intro_outro = _extract_intro_outro_from_clip_configs(clip_configs)
+                    if intro_outro:
+                        plan_config["intro_outro"] = intro_outro
+
+                # 把 editing_mode 也带过去
+                if template.editing_mode:
+                    plan_config["editing_mode"] = template.editing_mode
+
+                logger.info(
+                    "模板配置加载成功(新系统): template_id=%s keys=%s",
+                    template_id,
+                    list(plan_config.keys()),
+                )
+                return plan_config
+
+            # fallback: 旧模板系统
+            from packages.adapters.sqlalchemy_impl.models import TemplateModel
+
             template = (
                 session.query(TemplateModel)
                 .filter(
@@ -1006,7 +1057,7 @@ def _load_template_plan_config(template_id: str) -> dict:
                 plan_config["bgm"] = bgm_cfg
 
             logger.info(
-                "模板配置加载成功: template_id=%s keys=%s",
+                "模板配置加载成功(旧系统): template_id=%s keys=%s",
                 template_id,
                 list(plan_config.keys()),
             )
@@ -1018,161 +1069,6 @@ def _load_template_plan_config(template_id: str) -> dict:
         return {}
 
 
-# ── 渲染引擎选择 ─────────────────────────────────────────────────────────────
-
-
-def _resolve_render_engine(user_id: str) -> str:
-    """根据 Feature Flag 决定使用哪个渲染引擎。
-
-    Returns:
-        "legacy" 或 "unified"
-    """
-    try:
-        from video_processing.render_engine_resolver import get_render_engine_resolver
-
-        resolver = get_render_engine_resolver()
-        engine = resolver.get_engine(user_id=user_id)
-        # 灰度期间打印详细 flag 配置，便于排查
-        config = resolver.get_config_snapshot()
-        logger.info(
-            "[渲染引擎] flag 解析: user_id=%s engine=%s enabled=%s percentage=%s whitelist=%d default=%s",
-            user_id,
-            engine,
-            config.get("enabled"),
-            config.get("percentage"),
-            len(config.get("whitelist", [])),
-            config.get("default_engine"),
-        )
-        return engine
-    except Exception as exc:
-        # 异常时 fallback 到 legacy（保守策略，与 edit_plan_generation 一致）
-        logger.warning("获取渲染引擎配置失败，fallback 到 legacy: %s", exc, exc_info=True)
-        return ENGINE_LEGACY
-
-
-# ── 旧引擎渲染（FFmpeg filter_complex） ────────────────────────────────────────
-
-
-def _render_with_legacy_engine(
-    task_id: str,
-    virtual_clips: list[_VirtualClip],
-    asset_path_map: dict[str, Path],
-    work_dir: Path,
-    output_path: Path,
-) -> tuple[float, int]:
-    """旧引擎渲染路径：手动构建 FFmpeg filter_complex 命令。
-
-    说明：generate_video 任务使用虚拟 clips（无 EditPlan 数据库记录），
-    因此无法直接复用 VideoComposeService。这里手动构建等价的 filter_complex
-    命令，与旧引擎行为一致（scale → crop → setpts → trim → setpts，
-    无 fps 归一化，保持原帧率）。
-
-    支持模式：one_take / pip / voice_over / voice_pip
-    - 所有模式统一走 concat 滤镜（与旧引擎多片段逻辑一致）
-
-    Returns:
-        (duration_seconds, file_size_bytes)
-    """
-    import subprocess
-
-    main_clips = [
-        c
-        for c in virtual_clips
-        if c.clip_type in ("main", "b_roll", "background")
-        or (c.clip_type == "main" and c.config.get("role") == "b_roll")
-    ]
-    if not main_clips:
-        main_clips = virtual_clips[:1]
-
-    input_args: list[str] = []
-    video_filters: list[str] = []
-    audio_filters: list[str] = []
-
-    for i, clip in enumerate(main_clips):
-        local_path = asset_path_map.get(clip.asset_id)
-        if not local_path:
-            continue
-        input_args.extend(["-i", str(local_path)])
-
-        duration = clip.duration or 0.0
-
-        # 视频滤镜：scale → crop → setpts → trim → setpts（与旧引擎一致）
-        vf = (
-            f"[{i}:v]"
-            f"scale={OUTPUT_WIDTH}:{OUTPUT_HEIGHT}:force_original_aspect_ratio=increase,"
-            f"crop={OUTPUT_WIDTH}:{OUTPUT_HEIGHT},"
-            f"setpts=PTS-STARTPTS,"
-            f"trim=0:{duration:.3f},"
-            f"setpts=PTS-STARTPTS"
-            f"[v{i}]"
-        )
-        video_filters.append(vf)
-
-        # 音频滤镜：atrim → asetpts
-        af = f"[{i}:a]atrim=0:{duration:.3f},asetpts=PTS-STARTPTS[a{i}]"
-        audio_filters.append(af)
-
-    n = len(main_clips)
-
-    if n == 1:
-        video_label = "[v0]"
-        audio_label = "[a0]"
-    else:
-        # concat 视频
-        v_inputs = "".join(f"[v{i}]" for i in range(n))
-        video_filters.append(f"{v_inputs}concat=n={n}:v=1:a=0[outv]")
-        # concat 音频
-        a_inputs = "".join(f"[a{i}]" for i in range(n))
-        audio_filters.append(f"{a_inputs}concat=n={n}:v=0:a=1[outa]")
-        video_label = "[outv]"
-        audio_label = "[outa]"
-
-    # 组装 filter_complex
-    fc_parts = video_filters + audio_filters
-    filter_complex = ";".join(fc_parts)
-
-    command = [
-        FFMPEG_BIN,
-        "-y",
-        *input_args,
-        "-filter_complex",
-        filter_complex,
-        "-map",
-        video_label,
-        "-map",
-        audio_label,
-        "-c:v",
-        "libx264",
-        "-crf",
-        "23",
-        "-preset",
-        "medium",
-        "-c:a",
-        "aac",
-        "-b:a",
-        "192k",
-        "-movflags",
-        "+faststart",
-        str(output_path),
-    ]
-
-    logger.info("[task_id=%s] [渲染] legacy 引擎 FFmpeg 开始: clips=%d", task_id, n)
-    try:
-        run_ffmpeg(command)
-    except subprocess.CalledProcessError as e:
-        logger.error(
-            "[task_id=%s] [渲染] legacy 引擎 FFmpeg 失败: %s\nfilter_complex: %s",
-            task_id,
-            e,
-            filter_complex[:500],
-        )
-        raise
-
-    file_size = output_path.stat().st_size if output_path.exists() else 0
-    duration = probe_duration(output_path)
-    return duration, file_size
-
-
 # ── generate_video 阶段子函数 ─────────────────────────────────────────────────
 
 
@@ -1264,13 +1160,15 @@ def _render_video(
 ) -> tuple[Path, float]:
     """渲染视频（含配音混音）。
 
+    使用 RenderAdapter 统一渲染入口，复用 BGM/ASR/分辨率/缩略图逻辑。
+
     Returns:
         (output_path, render_duration)
     """
     if not downloaded_videos:
         raise RuntimeError(f"素材下载结果为空: task_id={task_id}")
 
-    # 构建虚拟 plan + clips
+    # 构建虚拟 plan + clips + asset_path_map
     virtual_plan, virtual_clips, asset_path_map = _build_plan_and_clips_from_task(
         task_id=task_id,
         downloaded_paths=downloaded_videos,
@@ -1282,7 +1180,6 @@ def _render_video(
     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(
@@ -1291,6 +1188,16 @@ def _render_video(
                 list(template_config.keys()),
             )
 
+    # 确保输出分辨率配置存在（一键生成默认横屏 1280x720）
+    # RenderAdapter 从 plan.config.export.resolution 读取，
+    # 如果模板没有配置则用默认值，这里显式设置保持和旧逻辑一致
+    plan_cfg = virtual_plan.config or {}
+    export_cfg = plan_cfg.get("export", {}) or {}
+    if not export_cfg.get("resolution"):
+        export_cfg["resolution"] = f"{OUTPUT_WIDTH}x{OUTPUT_HEIGHT}"
+        plan_cfg["export"] = export_cfg
+        virtual_plan.config = plan_cfg
+
     total_duration = sum(c.duration for c in virtual_clips)
     logger.info(
         "[task_id=%s] [剪辑计划] 片段数=%d, 总时长=%.1fs",
@@ -1299,64 +1206,42 @@ def _render_video(
         total_duration,
     )
 
-    # 选择渲染引擎
-    engine = _resolve_render_engine(user_id) if user_id else ENGINE_UNIFIED
-    logger.info("[task_id=%s] [渲染] 引擎选择: %s (user_id=%s)", task_id, engine, user_id)
-
     render_start = time.monotonic()
-    render_output_path = temp_path / f"rendered-{task_id}.mp4"
+    logger.info("[task_id=%s] [渲染] RenderAdapter 统一渲染开始", task_id)
 
-    if engine == ENGINE_LEGACY:
-        render_duration, _ = _render_with_legacy_engine(
-            task_id=task_id,
-            virtual_clips=virtual_clips,
-            asset_path_map=asset_path_map,
-            work_dir=temp_path,
-            output_path=render_output_path,
-        )
-    else:
-        logger.info("[task_id=%s] [渲染] unified 引擎 FFmpeg 渲染开始", task_id)
+    # 使用 RenderAdapter 统一渲染入口（复用 BGM/ASR/分辨率/缩略图逻辑）
+    from video_processing.render_adapter import RenderAdapter
+    from worker_app.db import SessionLocal
 
-        # ── 准备 BGM 音频 ──
-        bgm_path: str | None = None
-        plan_config = virtual_plan.config or {}
-        bgm_config = plan_config.get("bgm", {}) or {}
-        if bgm_config.get("enabled", False):
-            try:
-                bgm_path = _prepare_bgm_track(
-                    bgm_config=bgm_config,
-                    temp_path=temp_path,
-                    task_id=task_id,
-                )
-            except Exception as bgm_err:
-                logger.warning("[task_id=%s] [BGM] 准备失败，跳过BGM: %s", task_id, bgm_err)
-                bgm_path = None
-
-        render_service = UnifiedRenderService(
+    db = SessionLocal()
+    try:
+        adapter = RenderAdapter(db)
+        render_result = adapter.render_from_memory(
             plan=virtual_plan,
             clips=virtual_clips,
             asset_path_map=asset_path_map,
+            plan_id=f"gen_{task_id}",
+            job_id=task_id,
             work_dir=temp_path,
-            output_width=OUTPUT_WIDTH,
-            output_height=OUTPUT_HEIGHT,
-            output_fps=int(OUTPUT_FPS),
-            asr_service=get_asr_service(),
-            bgm_path=bgm_path,
         )
-        render_result = render_service.render()
-        render_output_path = render_result.output_path
-        render_duration = render_result.duration
+    finally:
+        db.close()
+
+    if not render_result.success:
+        raise RuntimeError(f"渲染失败: {render_result.error_message}")
+
+    render_output_path = render_result.output_path
+    render_duration = render_result.duration
 
     render_elapsed = time.monotonic() - render_start
     logger.info(
-        "[task_id=%s] [渲染] %s 引擎完成: 耗时=%.1fs, 时长=%.2fs",
+        "[task_id=%s] [渲染] RenderAdapter 完成: 耗时=%.1fs, 时长=%.2fs",
         task_id,
-        engine,
         render_elapsed,
         render_duration,
     )
 
-    # 配音混音
+    # 配音混音（素材库音频，后处理混音）
     if voice_path:
         final_path = temp_path / f"final-{task_id}.mp4"
         try:

docs/unified_render_effect_layer_verification.md

@@ -0,0 +1,153 @@
+# 统一渲染引擎效果层全模式验证报告
+
+> 背景：#608 删除 legacy 渲染引擎后，所有模式统一走 UnifiedRenderService。
+> 本报告验证四种模式（一键生成/剪辑计划/模板/手动编辑器）下所有效果层的覆盖情况。
+> 验证时间：2026-07-20
+
+---
+
+## 一、验证范围
+
+### 四种渲染模式
+| 模式 | 入口路径 | 调用链 |
+|------|---------|--------|
+| 一键生成（旧） | `worker.generate_video` | `generation.py` → 直接构造 `UnifiedRenderService` |
+| 剪辑计划 | `worker.render_edit_plan` | `edit_plan_generation.py` → `RenderAdapter` → `UnifiedRenderService` |
+| 模板模式 | 模板创建计划 → 剪辑计划渲染 | 同剪辑计划路径 |
+| 手动编辑器 | 手动编辑计划 → 剪辑计划渲染 | 同剪辑计划路径 |
+
+> **核心结论**：模板模式和手动编辑器最终都走剪辑计划渲染链路，本质是同一条路径。
+> 差异只在「一键生成（旧）」和「剪辑计划」两条链路之间。
+
+---
+
+## 二、效果层覆盖矩阵
+
+### 2.1 Clip 级效果（两条链路一致，均通过 UnifiedRenderService 内部处理）
+
+| 效果 | filter_complex | pass_through（直通） | 备注 |
+|------|:---:|:---:|------|
+| **裁剪 trim** | ✅ | ✅ | 直通用 trim+duration，filter_complex 用 trim |
+| **调速 speed** | ✅ | ✅ | 视频 setpts，音频 atempo |
+| **倒放 reverse** | ✅ | ✅ | reverse 滤镜 + areverse |
+| **分辨率适配** | ✅ | ✅ | scale + pad/crop，按角色策略不同 |
+| **调色 color_grade** | ✅ | ✅ | brightness/contrast/saturation等 |
+| **绿幕抠像 chroma_key** | ✅ | ✅ | colorkey 滤镜 |
+| **帧率归一化 fps** | ✅ | ✅ | fps 滤镜统一到 output_fps |
+| **像素格式 format** | ✅ | ✅ | yuv420p |
+
+### 2.2 层间/全局效果（filter_complex 路径）
+
+| 效果 | 剪辑计划路径 | 一键生成（旧） | 备注 |
+|------|:---:|:---:|------|
+| **转场 xfade** | ✅ | ✅ | 多clip场景自动启用；直通模式下自动禁用直通走filter_complex |
+| **画中画 PiP** | ✅ | ✅ | overlay + corner_voice 图层 |
+| **贴纸 stickers** | ✅ | ✅ | plan.config.stickers；有贴纸时禁用直通 |
+| **水印 watermark** | ✅ | ✅ | plan.config.watermark；有水印时禁用直通 |
+| **ASS 字幕叠加** | ✅ | ✅ | subtitles 滤镜 |
+| **ASR 自动字幕** | ✅ | ✅ | asr_service 传入，生成 ASS |
+
+### 2.3 音频效果
+
+| 效果 | 剪辑计划路径 | 一键生成（旧） | 备注 |
+|------|:---:|:---:|------|
+| **BGM 混音** | ✅ | ✅ | 各自准备 BGM 文件，都走 UnifiedRenderService.bgm_path |
+| **TTS 配音** | ✅ | ✅ | `_maybe_add_voiceover_layer` + audio 图层混音；刚修了顶层字段桥接（#549） |
+| **配音素材库音频** | ⚠️ 待确认 | ✅ | 一键生成用 `_mux_audio_track` 独立混音；剪辑计划路径需确认 voice 类型 clip 处理 |
+| **音频降噪** | ✅ | ✅ | afftdn 滤镜，直通和filter_complex都有 |
+| **音频格式归一化** | ✅ | ✅ | aformat + aac 编码 |
+| **音量调整** | ✅ | ✅ | volume 滤镜 |
+
+### 2.4 后处理
+
+| 效果 | 剪辑计划路径 | 一键生成（旧） | 备注 |
+|------|:---:|:---:|------|
+| **片头片尾 intro/outro** | ✅ | ✅ | plan.config.intro_outro |
+| **封面抽帧** | ✅ | ✅ | 渲染后抽帧上传 |
+| **输出分辨率** | ✅ | ✅ | 剪辑计划从 config.export 读；一键生成用常量 1280x720 |
+
+---
+
+## 三、发现的问题与待修复项
+
+### P1 级问题（功能缺失）
+
+#### 1. 一键生成（旧路径）TTS 配音配置路径不匹配 — **已修复 #549**
+- **根因**：前端传 `config.voice_id` + `config.custom_text`（顶层），后端从 `config.tts` 读
+- **修复**：`_maybe_add_voiceover_layer` 增加顶层字段桥接兼容
+- **影响范围**：所有走 UnifiedRenderService 的路径（剪辑计划 + 一键生成）
+
+#### 2. 直通模式调速失效 — **已修复 #463**
+- **根因**：`_render_pass_through` 中 final_duration 用原始时长，未考虑调速
+- **修复**：改用 `_clip_adjusted_duration` 计算调速后时长
+- **影响范围**：单 clip 直通场景（最常见的一键生成场景）
+
+### P2 级问题（架构不统一，功能可用但不一致）
+
+#### 3. 一键生成（旧）配音素材库音频走独立混音链路，不走 audio 图层
+- **现状**：`generation.py` 里 `_mux_audio_track(render_output_path, voice_path, final_path)` 用 ffmpeg 直接 mux
+- **问题**：与 UnifiedRenderService 的 audio 图层混音架构不统一；无法与BGM/TTS做混音音量平衡
+- **建议**：迁移到 audio 图层模式，与剪辑计划路径对齐
+
+#### 4. 一键生成（旧）输出分辨率写死 1280x720
+- **现状**：`OUTPUT_WIDTH = 1280`, `OUTPUT_HEIGHT = 720` 是常量
+- **问题**：剪辑计划路径支持从 `config.export.resolution` 读取输出分辨率
+- **建议**：一键生成也支持从 plan.config 读取分辨率配置
+
+#### 5. _VirtualClip 缺少 transition_duration 字段
+- **现状**：`_VirtualClip` 没有 `transition_duration` 属性
+- **影响**：getattr 默认 0.0，转场效果等于没转场（但不会报错）
+- **建议**：补全字段，与 EditPlanClip 对齐
+
+### P3 级问题（性能优化）
+
+#### 6. 有 TTS 配音时直通模式被禁用（因为加了 audio 图层变成 2 个图层）
+- **现状**：TTS 配音加到 audio 图层后，`len(layers) != 1`，直通被禁用
+- **影响**：单 clip + TTS 配音场景不走直通，性能下降 ~30%
+- **建议**：直通模式单独处理 audio 图层混音，类似 BGM 的处理方式
+
+---
+
+## 四、各模式验收结论
+
+### ✅ 剪辑计划路径（含模板模式、手动编辑器）
+所有效果层验证通过，链路完整：
+- clip 级效果（调色/调速/倒放/绿幕/裁剪）✅
+- 层间效果（转场/画中画/贴纸/水印）✅
+- 音频效果（BGM/TTS配音/降噪/格式归一化）✅
+- 字幕（ASS/ASR自动字幕）✅
+- 后处理（片头片尾/封面抽帧/分辨率配置）✅
+
+### ⚠️ 一键生成（旧路径）
+核心效果可用，但有架构不一致问题：
+- 核心渲染效果全部通过 ✅
+- TTS 配音已修复 ✅（#549）
+- 直通调速已修复 ✅（#463）
+- 配音素材库混音架构不统一 ⚠️（P2）
+- 输出分辨率不可配置 ⚠️（P2）
+- transition_duration 缺失 ⚠️（P2）
+
+---
+
+## 五、修复优先级建议
+
+| 优先级 | 问题 | 工作量 | 建议 |
+|--------|------|--------|------|
+| P0 | 无 | - | 核心功能均可用 |
+| P1 | 已全部修复（#463 #549） | - | 已完成 |
+| P2 | 配音素材库音频架构统一 | 中 | 下一轮技术债清理 |
+| P2 | 一键生成输出分辨率可配置 | 小 | 顺手修 |
+| P2 | _VirtualClip 补 transition_duration | 小 | 顺手修 |
+| P3 | TTS配音场景直通模式优化 | 中 | 性能优化排期 |
+
+---
+
+## 六、验证方法
+
+本报告基于代码静态分析 + 单元测试验证：
+- 109 个 unified_render_service 单元测试全绿
+- 覆盖直通模式、filter_complex 模式、转场、调速、调色、分辨率归一化、帧率归一化、音频格式归一化等核心链路
+- 新增直通调速测试 3 个（#463）
+- 新增 TTS 配置桥接测试 4 个（#549）
+
+**建议后续补充端到端集成测试**：用真实素材跑四种模式的完整渲染链路，验证输出音视频质量。

scripts/ci/acr_cleanup.py

@@ -278,6 +278,15 @@ def cleanup_repo(repo, keep_count, pr_days, dry_run):
         valid_kept = [t for t in kept if t["created"]]
         if valid_kept:
             print("  最早保留:", valid_kept[-1]["tag"][:12], "(" + valid_kept[-1]["created"][:10] + ")")
+        # 保护当前构建的tag（通过PROTECTED_TAG环境变量传入，如GITHUB_SHA）
+        protected_tag = os.environ.get("PROTECTED_TAG", "").strip()
+        if protected_tag:
+            before = len(to_delete)
+            to_delete = [t for t in to_delete if not t["tag"].startswith(protected_tag)]
+            removed = before - len(to_delete)
+            if removed > 0:
+                print(f"  保护当前构建tag: {protected_tag[:12]} (跳过{removed}个)")
+
         to_del_valid = [t for t in to_delete if t["digest"]]
         print("  可删除(有digest):", len(to_del_valid), "个")
     else:

scripts/ci/auto_fix_formatting.py

@@ -23,6 +23,57 @@ def run(cmd, check=True, capture=True, cwd=None):
     return result
 
 
+def ensure_git_repo(api_url, repo, token, pr_number):
+    """确保当前目录是git仓库，并切换到PR源分支。
+
+    checkout脚本用tarball方式下载代码（PR merge后的commit），没有.git目录。
+    这里自动初始化git仓库，fetch PR源分支并强制checkout，
+    使工作区变为PR源分支的代码，确保后续格式化修复基于源分支。
+    """
+    if os.path.exists(".git"):
+        return
+
+    print("检测到tarball checkout（无.git目录），自动初始化git仓库...")
+
+    # 构造带认证的远端URL
+    server_url = api_url.rsplit("/api/v1", 1)[0]
+    remote_url = f"{server_url.replace('https://', f'https://x-access-token:{token}@')}/{repo}.git"
+
+    # 获取PR的源分支
+    pr_api_url = f"{api_url}/repos/{repo}/pulls/{pr_number}"
+    req_obj = urllib.request.Request(pr_api_url, headers={"Authorization": f"token {token}"})
+    with urllib.request.urlopen(req_obj) as resp:
+        pr = json.loads(resp.read())
+    head_branch = pr["head"]["ref"]
+
+    print(f"PR源分支: {head_branch}")
+
+    # 初始化git
+    run("git init -q")
+    run(f"git remote add origin {remote_url}")
+    run('git config user.name "CI Bot"')
+    run('git config user.email "ci-bot@xiaoxiajianji.com"')
+
+    # fetch源分支（浅克隆，只要最新commit）
+    print("fetch源分支...")
+    run(f"git fetch --depth=1 origin {head_branch}")
+
+    # 强制checkout到源分支（覆盖tarball内容）
+    # tarball是merge后的commit，源分支才是我们要修改并推送的目标
+    print("切换到源分支...")
+    # --force 覆盖tarball留下的untracked文件，避免"The following untracked working tree files would be overwritten"
+    run(f"git checkout -B --force {head_branch} FETCH_HEAD")
+
+    result = run("git status --porcelain")
+    if result.stdout.strip():
+        n = len(result.stdout.strip().splitlines())
+        print(f"⚠️  工作区有 {n} 个未追踪文件")
+    else:
+        print("✅ git仓库就绪，工作区clean")
+
+    return head_branch
+
+
 def get_changed_files(pr_number, api_url, token):
     """获取PR中变更的文件列表"""
     url = f"{api_url}/pulls/{pr_number}/files?limit=100"
@@ -91,9 +142,7 @@ def fix_frontend(target_fe_files, scan_mode, repo_root):
 
     if scan_mode == "incremental":
         # 增量模式：只格式化变更的前端文件
-        # 转换为相对于 apps/web 的路径或用绝对路径
         target_str = " ".join(target_fe_files)
-        # 从项目根目录运行，prettier 会找配置文件
         cmd = f"{prettier_bin} --write {target_str}"
     else:
         # 全量模式：格式化整个前端目录
@@ -130,6 +179,10 @@ def main():
 
     repo_root = os.getcwd()
 
+    # 确保git仓库可用（tarball checkout模式下自动初始化）
+    # 返回PR源分支名，供后续推送使用
+    head_branch = ensure_git_repo(api_url, repo, token, pr_number)
+
     print("=== 检测到代码格式问题，尝试自动修复 ===")
     print(f"PR #{pr_number}")
     print(f"扫描模式: {scan_mode}")
@@ -149,7 +202,6 @@ def main():
         ".yaml",
         ".yml",
     )
-    # Python 文件扩展名
     py_extensions = (".py",)
 
     # 确定要修复的文件范围
@@ -160,15 +212,13 @@ def main():
         print(f"增量模式: {len(target_py_files)} 个Python文件, {len(target_fe_files)} 个前端文件")
     else:
         target_py_files = ["alembic", "apps", "packages", "tests", "scripts"]
-        # 全量模式下 prettier 在前端目录内部运行，无需传文件列表
-        target_fe_files = ["apps/web"]  # 标记为有前端文件需要处理
+        target_fe_files = ["apps/web"]
         print("全量模式，修复所有文件")
 
     # Python 格式化
     fix_python(target_py_files, scan_mode)
 
     # 前端格式化
-    # 全量模式下直接传 web 目录标记
     if scan_mode != "incremental":
         fix_frontend(["apps/web"], scan_mode, repo_root)
     else:
@@ -186,23 +236,52 @@ def main():
     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 + prettier [ci skip]"')
 
-    # 获取来源分支并推送
-    head_branch = get_pr_head_branch(pr_number, f"{api_url}/repos/{repo}", token)
+    # 推送（head_branch已从ensure_git_repo获取）
     print(f"\nPR来源分支: {head_branch}")
 
-    run(f'git push origin "HEAD:{head_branch}"')
+    # 推送带rebase+重试，避免并发提交导致冲突
+    max_push_retries = 3
+    push_success = False
+    for attempt in range(1, max_push_retries + 1):
+        print(f"推送尝试 {attempt}/{max_push_retries}...")
+        try:
+            # 先pull --rebase拉取最新提交
+            run(f"git pull --rebase origin {head_branch}", check=False)
+            # 如果rebase有冲突，中止rebase并报错
+            result = run("git status --porcelain", capture=True)
+            if "rebase" in result.stdout or "both modified" in result.stdout:
+                run("git rebase --abort", check=False)
+                print("rebase冲突，跳过本次推送", file=sys.stderr)
+                break
+            # 推送
+            push_result = run(f'git push origin "HEAD:{head_branch}"', check=False)
+            if push_result.returncode == 0:
+                push_success = True
+                break
+            else:
+                print(f"推送失败: {push_result.stderr[-200:]}", file=sys.stderr)
+                if attempt < max_push_retries:
+                    import time
 
-    print()
-    print("✅ 格式已自动修复并推送回分支")
-    print("新的commit会重新触发CI检查")
+                    time.sleep(2**attempt)
+        except Exception as e:
+            print(f"推送异常: {e}", file=sys.stderr)
+            if attempt < max_push_retries:
+                import time
+
+                time.sleep(2**attempt)
+
+    if not push_success:
+        print("⚠️  自动格式化推送失败，跳过（请手动检查）", file=sys.stderr)
+        sys.exit(0)  # 不影响Validate的失败标记
+    else:
+        print()
+        print("✅ 格式已自动修复并推送回分支")
+        print("新的commit会重新触发CI检查")
 
 
 if __name__ == "__main__":

scripts/ci/ci_trace_report.py

@@ -0,0 +1,375 @@
+#!/usr/bin/env python3
+"""
+CI Trace Report Script - Reports CI Trace data to AgentLoop from Gitea Actions workflows.
+
+Usage in CI workflow jobs:
+  - At start: python3 scripts/ci/ci_trace_report.py --status running
+  - At end: python3 scripts/ci/ci_trace_report.py --status ok --start-time $CI_TRACE_START_TIME
+
+Environment variables (built-in Gitea Actions):
+  GITEA_REPOSITORY / GITHUB_REPOSITORY - repository (owner/repo)
+  GITEA_WORKFLOW / GITHUB_WORKFLOW     - workflow name
+  GITEA_JOB / GITHUB_JOB               - job ID
+  GITEA_SHA / GITHUB_SHA               - commit SHA
+  GITEA_REF_NAME / GITHUB_REF_NAME     - branch name
+  GITEA_RUN_ID / GITHUB_RUN_ID         - run ID
+  GITEA_ACTOR / GITHUB_ACTOR           - trigger actor
+  GITEA_EVENT_NAME / GITHUB_EVENT_NAME - event type
+  PR_NUMBER / GITEA_PR_NUMBER          - PR number (if PR triggered)
+
+AgentLoop configuration (injected via Secrets):
+  AGENTLOOP_LICENSE_KEY - LicenseKey (required)
+  AGENTLOOP_ENDPOINT    - Trace endpoint (optional, has default)
+  AGENTLOOP_PROJECT     - SLS Project name (optional)
+  AGENTLOOP_WORKSPACE   - CMS Workspace name (optional)
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+import uuid
+
+# ========== Default Configuration ==========
+DEFAULT_ENDPOINT = "https://proj-xtrace-495e81719a1fd9a2c5fd671eefafbe-cn-hangzhou.cn-hangzhou.log.aliyuncs.com/apm/trace/opentelemetry/v1/traces"
+DEFAULT_PROJECT = "proj-xtrace-495e81719a1fd9a2c5fd671eefafbe-cn-hangzhou"
+DEFAULT_WORKSPACE = "agentloop-13b8d6efb7fde6e9b193eb982ade68e2"
+
+
+# ========== OTLP Protobuf Manual Encoding ==========
+
+
+def _encode_varint(value):
+    result = bytearray()
+    while value > 0x7F:
+        result.append((value & 0x7F) | 0x80)
+        value >>= 7
+    result.append(value & 0x7F)
+    return bytes(result)
+
+
+def _encode_tag(field_number, wire_type):
+    return _encode_varint((field_number << 3) | wire_type)
+
+
+def _encode_string_field(field_number, value):
+    value_bytes = value.encode("utf-8")
+    return _encode_tag(field_number, 2) + _encode_varint(len(value_bytes)) + value_bytes
+
+
+def _encode_bytes_field(field_number, value_bytes):
+    return _encode_tag(field_number, 2) + _encode_varint(len(value_bytes)) + value_bytes
+
+
+def _encode_int_field(field_number, value):
+    return _encode_tag(field_number, 0) + _encode_varint(value & 0xFFFFFFFFFFFFFFFF)
+
+
+def _encode_message_field(field_number, message_bytes):
+    return _encode_tag(field_number, 2) + _encode_varint(len(message_bytes)) + message_bytes
+
+
+def _encode_key_value(key, value_str):
+    any_value = _encode_string_field(1, value_str)
+    return _encode_string_field(1, key) + _encode_message_field(2, any_value)
+
+
+def _encode_status(status_code, status_msg=""):
+    data = _encode_int_field(1, status_code)
+    if status_msg:
+        data += _encode_string_field(2, status_msg)
+    return data
+
+
+def _encode_span(
+    trace_id_bytes,
+    span_id_bytes,
+    parent_span_id_bytes,
+    name,
+    start_time_unix_nano,
+    end_time_unix_nano,
+    span_kind,
+    attributes,
+    status_code,
+    status_msg="",
+):
+    data = b""
+    data += _encode_bytes_field(1, trace_id_bytes)
+    data += _encode_bytes_field(2, span_id_bytes)
+    if parent_span_id_bytes:
+        data += _encode_bytes_field(3, parent_span_id_bytes)
+    data += _encode_string_field(4, name)
+    data += _encode_int_field(5, span_kind)
+    data += _encode_int_field(6, start_time_unix_nano)
+    data += _encode_int_field(7, end_time_unix_nano)
+    for key, value in attributes.items():
+        kv = _encode_key_value(key, str(value))
+        data += _encode_message_field(9, kv)
+    status = _encode_status(status_code, status_msg)
+    data += _encode_message_field(12, status)
+    return data
+
+
+def _encode_resource_spans(service_name, scope_spans_bytes):
+    svc_kv = _encode_key_value("service.name", service_name)
+    resource = _encode_message_field(1, svc_kv)
+    data = _encode_message_field(1, resource)
+    data += _encode_message_field(2, scope_spans_bytes)
+    return data
+
+
+def _encode_scope_spans(scope_name, spans_bytes_list):
+    scope = _encode_string_field(1, scope_name)
+    data = _encode_message_field(1, scope)
+    for span_bytes in spans_bytes_list:
+        data += _encode_message_field(2, span_bytes)
+    return data
+
+
+def _encode_traces_data(resource_spans_bytes_list):
+    data = b""
+    for rs_bytes in resource_spans_bytes_list:
+        data += _encode_message_field(1, rs_bytes)
+    return data
+
+
+# ========== Helper Functions ==========
+
+
+def _gen_trace_id():
+    return uuid.uuid4().bytes
+
+
+def _gen_span_id():
+    return uuid.uuid4().bytes[:8]
+
+
+def _env(name, default=""):
+    """Get env var with GITEA_/GITHUB_ prefix fallback."""
+    val = os.getenv(name, "")
+    if val:
+        return val
+    if name.startswith("GITEA_"):
+        alt = "GITHUB_" + name[6:]
+        return os.getenv(alt, default)
+    if name.startswith("GITHUB_"):
+        alt = "GITEA_" + name[7:]
+        return os.getenv(alt, default)
+    return default
+
+
+def _get_pr_number():
+    """Get PR number from environment or event file."""
+    pr = os.getenv("PR_NUMBER", "") or os.getenv("GITEA_PR_NUMBER", "")
+    if pr:
+        return pr
+
+    event_path = os.getenv("GITHUB_EVENT_PATH", "") or os.getenv("GITEA_EVENT_PATH", "")
+    if event_path and os.path.isfile(event_path):
+        try:
+            with open(event_path, "r") as f:
+                event = json.load(f)
+            if "pull_request" in event and "number" in event["pull_request"]:
+                return str(event["pull_request"]["number"])
+        except Exception:
+            pass
+
+    return ""
+
+
+def _get_ci_attributes():
+    """Collect attributes from CI environment variables."""
+    attrs = {
+        "ci.repo": _env("GITEA_REPOSITORY") or _env("GITHUB_REPOSITORY") or "unknown",
+        "ci.workflow": _env("GITEA_WORKFLOW") or _env("GITHUB_WORKFLOW") or "unknown",
+        "ci.job": _env("GITEA_JOB") or _env("GITHUB_JOB") or "unknown",
+        "ci.commit_sha": _env("GITEA_SHA") or _env("GITHUB_SHA") or "unknown",
+        "ci.branch": _env("GITEA_REF_NAME") or _env("GITHUB_REF_NAME") or "unknown",
+        "ci.run_id": _env("GITEA_RUN_ID") or _env("GITHUB_RUN_ID") or "unknown",
+        "ci.actor": _env("GITEA_ACTOR") or _env("GITHUB_ACTOR") or "unknown",
+        "ci.event": _env("GITEA_EVENT_NAME") or _env("GITHUB_EVENT_NAME") or "unknown",
+    }
+    pr = _get_pr_number()
+    if pr:
+        attrs["ci.pr_number"] = pr
+    return attrs
+
+
+# ========== Trace Building & Reporting ==========
+
+
+def build_trace(service_name, trace_name, status, duration_ms, attributes=None):
+    """Build an OTLP trace payload (protobuf bytes). No external dependencies."""
+    trace_id = _gen_trace_id()
+    end_time = int(time.time() * 1e9)
+    start_time = end_time - int(duration_ms * 1e6)
+    status_code = 1 if status in ("ok", "running") else 2
+    status_msg = "" if status in ("ok", "running") else "Job failed"
+
+    main_attrs = {
+        "agent.trace_name": trace_name,
+        "agent.service": service_name,
+        "ci.trace_status": status,
+    }
+    if attributes:
+        main_attrs.update(attributes)
+
+    main_span = _encode_span(
+        trace_id_bytes=trace_id,
+        span_id_bytes=_gen_span_id(),
+        parent_span_id_bytes=b"",
+        name=trace_name,
+        start_time_unix_nano=start_time,
+        end_time_unix_nano=end_time,
+        span_kind=1,
+        attributes=main_attrs,
+        status_code=status_code,
+        status_msg=status_msg,
+    )
+
+    scope_spans = _encode_scope_spans("ci-trace", [main_span])
+    resource_spans = _encode_resource_spans(service_name, scope_spans)
+    return _encode_traces_data([resource_spans])
+
+
+def report_ci_trace(
+    service_name,
+    trace_name,
+    status="ok",
+    duration_ms=1000,
+    endpoint=None,
+    license_key=None,
+    project=None,
+    workspace=None,
+    extra_attributes=None,
+):
+    """
+    Report CI Trace data. Returns (success: bool, message: str).
+    Never raises exceptions; returns False on failure.
+    """
+    try:
+        endpoint = endpoint or os.getenv("AGENTLOOP_ENDPOINT", DEFAULT_ENDPOINT)
+        license_key = license_key or os.getenv("AGENTLOOP_LICENSE_KEY", "")
+        project = project or os.getenv("AGENTLOOP_PROJECT", DEFAULT_PROJECT)
+        workspace = workspace or os.getenv("AGENTLOOP_WORKSPACE", DEFAULT_WORKSPACE)
+
+        if not license_key:
+            return False, "[Trace] skipped: AGENTLOOP_LICENSE_KEY not configured"
+
+        attrs = _get_ci_attributes()
+        if extra_attributes:
+            attrs.update(extra_attributes)
+
+        payload = build_trace(
+            service_name=service_name,
+            trace_name=trace_name,
+            status=status,
+            duration_ms=duration_ms,
+            attributes=attrs,
+        )
+
+        headers = {
+            "Content-Type": "application/x-protobuf",
+            "x-arms-license-key": license_key,
+            "x-arms-project": project,
+            "x-cms-workspace": workspace,
+        }
+
+        req = urllib.request.Request(endpoint, data=payload, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                status_code = resp.status
+                resp_body = resp.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as e:
+            status_code = e.code
+            resp_body = e.read().decode("utf-8", errors="replace")
+
+        if status_code in (200, 202):
+            return True, (f"[Trace] success: {service_name} / {trace_name} " f"({status}, {duration_ms}ms)")
+        else:
+            return False, (f"[Trace] failed: HTTP {status_code} - {resp_body[:200]}")
+    except Exception as e:
+        return False, f"[Trace] error: {type(e).__name__}: {str(e)}"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="CI AgentLoop Trace Reporter")
+    parser.add_argument(
+        "--service",
+        dest="service_name",
+        default=os.getenv("TRACE_SERVICE", ""),
+        help="Service name (also via TRACE_SERVICE env)",
+    )
+    parser.add_argument(
+        "--name",
+        dest="trace_name",
+        default=os.getenv("TRACE_NAME", ""),
+        help="Trace name (also via TRACE_NAME env)",
+    )
+    parser.add_argument(
+        "--status",
+        default=os.getenv("TRACE_STATUS", "ok"),
+        choices=["ok", "error", "running"],
+        help="Status: ok / error / running (default ok)",
+    )
+    parser.add_argument(
+        "--start-time",
+        dest="start_time",
+        default=os.getenv("TRACE_START_TIME", ""),
+        help="Start timestamp (seconds) for duration calculation",
+    )
+    parser.add_argument(
+        "--duration-ms",
+        dest="duration_ms",
+        type=int,
+        default=0,
+        help="Direct duration in ms; takes precedence over --start-time",
+    )
+    parser.add_argument("--attrs", default="", help="Extra attributes (JSON string)")
+
+    args = parser.parse_args()
+
+    if not args.service_name:
+        print("[Trace] skipped: no service specified (--service or TRACE_SERVICE)")
+        sys.exit(0)
+
+    duration_ms = args.duration_ms
+    if duration_ms <= 0 and args.start_time:
+        try:
+            start_ts = float(args.start_time)
+            duration_ms = int((time.time() - start_ts) * 1000)
+        except (ValueError, TypeError):
+            duration_ms = 1000
+    if duration_ms <= 0:
+        duration_ms = 1000
+
+    extra_attrs = {}
+    if args.attrs:
+        try:
+            extra_attrs = json.loads(args.attrs)
+        except json.JSONDecodeError:
+            pass
+
+    trace_name = args.trace_name
+    if not trace_name:
+        wf = _env("GITEA_WORKFLOW") or _env("GITHUB_WORKFLOW") or "CI"
+        job = _env("GITEA_JOB") or _env("GITHUB_JOB") or "job"
+        trace_name = f"{wf} / {job}"
+
+    success, msg = report_ci_trace(
+        service_name=args.service_name,
+        trace_name=trace_name,
+        status=args.status,
+        duration_ms=duration_ms,
+        extra_attributes=extra_attrs,
+    )
+
+    print(msg)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

scripts/ci/docker_build_push.sh

@@ -1,9 +1,16 @@
 #!/bin/bash
 # 通用Docker镜像构建+推送脚本（local cache为主 + registry cache兜底）
 # M-2优化：解决registry缓存导入慢(247s)和推送不稳定问题
-# 用法: docker_build_push.sh <Dockerfile> <image_tag> <cache_ref> [build_arg...]
+# 用法: docker_build_push.sh [--no-cache] <Dockerfile> <image_tag> <cache_ref> [build_arg...]
 set -eu
 
+NO_CACHE_FLAG=""
+if [ "$1" = "--no-cache" ]; then
+  NO_CACHE_FLAG="--no-cache"
+  shift
+  echo "模式: --no-cache (不使用缓存，全新构建)"
+fi
+
 DOCKERFILE="$1"
 IMAGE_TAG="$2"
 CACHE_REF="$3"
@@ -38,6 +45,7 @@ build_with_cache_retry() {
     local exit_code
     set +e
     build_output=$(docker buildx build \
+      $NO_CACHE_FLAG \
       $BUILD_ARGS \
       --cache-from "type=local,src=${LOCAL_CACHE_DIR}" \
       --cache-from "type=registry,ref=${CACHE_REF},ignore-error=true" \
@@ -71,6 +79,7 @@ build_with_cache_retry() {
   # 重试完还是失败，不用本地缓存最后试一次（只从registry读）
   echo "⚠️  All cached attempts failed, building without local cache..."
   docker buildx build \
+    $NO_CACHE_FLAG \
     $BUILD_ARGS \
     --cache-from "type=registry,ref=${CACHE_REF},ignore-error=true" \
     --cache-to "type=local,dest=${LOCAL_CACHE_DIR},mode=max" \
@@ -91,38 +100,5 @@ echo ""
 echo "Image pushed: ${IMAGE_TAG}"
 echo "Local cache updated"
 
-# DISABLED: registry cache too slow echo ""
-# DISABLED: registry cache too slow echo "=== Step 2: Sync registry cache (best effort, retries 3x) ==="
-# DISABLED: registry cache too slow CACHE_TO_REGISTRY="type=registry,ref=${CACHE_REF},mode=max,compression=zstd"
-# DISABLED: registry cache too slow 
-# DISABLED: registry cache too slow MAX_RETRIES=3
-# DISABLED: registry cache too slow SUCCESS=0
-# DISABLED: registry cache too slow for attempt in $(seq 1 $MAX_RETRIES); do
-# DISABLED: registry cache too slow   echo "Registry cache sync attempt $attempt/$MAX_RETRIES"
-# DISABLED: registry cache too slow   if docker buildx build \
-# DISABLED: registry cache too slow     $BUILD_ARGS \
-# DISABLED: registry cache too slow     --cache-from "${CACHE_FROM_LOCAL}" \
-# DISABLED: registry cache too slow     --cache-to "${CACHE_TO_REGISTRY}" \
-# DISABLED: registry cache too slow     -f "${DOCKERFILE}" \
-# DISABLED: registry cache too slow     -t "${IMAGE_TAG}" \
-# DISABLED: registry cache too slow     --push \
-# DISABLED: registry cache too slow     .; then
-# DISABLED: registry cache too slow     echo "Registry cache synced (attempt $attempt)"
-# DISABLED: registry cache too slow     SUCCESS=1
-# DISABLED: registry cache too slow     break
-# DISABLED: registry cache too slow   else
-# DISABLED: registry cache too slow     echo "Registry cache sync failed (attempt $attempt)"
-# DISABLED: registry cache too slow     if [ $attempt -lt $MAX_RETRIES ]; then
-# DISABLED: registry cache too slow       WAIT=$((attempt * 5))
-# DISABLED: registry cache too slow       echo "Retrying in ${WAIT}s..."
-# DISABLED: registry cache too slow       sleep $WAIT
-# DISABLED: registry cache too slow     fi
-# DISABLED: registry cache too slow   fi
-# DISABLED: registry cache too slow done
-# DISABLED: registry cache too slow 
-# DISABLED: registry cache too slow if [ $SUCCESS -eq 0 ]; then
-# DISABLED: registry cache too slow   echo "WARNING: Registry cache sync failed after $MAX_RETRIES attempts (non-fatal, local cache still works)"
-# DISABLED: registry cache too slow fi
-
 echo ""
 echo "Build completed: ${IMAGE_TAG}"

scripts/ci/run_integration_tests.sh

@@ -0,0 +1,317 @@
+#!/bin/bash
+# CI Integration Tests Job 主脚本
+# 包含：依赖安装、ffmpeg安装、Redis启动、PG启动、迁移、测试、清理、覆盖率
+set -eu
+
+echo "=== CI Integration Tests 开始 ==="
+
+# --- 安装依赖 ---
+echo ""
+echo "=== 安装 Python 依赖 ==="
+# pip install 带重试（网络不稳定时自动重试）
+for i in 1 2 3; do
+  python3 -m pip install -q -r requirements-base.txt && break
+  echo "pip install requirements-base.txt 失败，重试 $i/3..."
+  [ $i -eq 3 ] && exit 1
+  sleep 5
+done
+for i in 1 2 3; do
+  python3 -m pip install -q -r requirements.txt && break
+  echo "pip install requirements.txt 失败，重试 $i/3..."
+  [ $i -eq 3 ] && exit 1
+  sleep 5
+done
+for i in 1 2 3; do
+  python3 -m pip install -q -r requirements-dev.txt && break
+  echo "pip install requirements-dev.txt 失败，重试 $i/3..."
+  [ $i -eq 3 ] && exit 1
+  sleep 5
+done
+for i in 1 2 3; do
+  python3 -m pip install -q pytest-rerunfailures && break
+  echo "pip install pytest-rerunfailures 失败，重试 $i/3..."
+  [ $i -eq 3 ] && exit 1
+  sleep 5
+done
+pytest --version
+
+# --- 安装 ffmpeg ---
+echo ""
+echo "=== 安装 ffmpeg ==="
+bash scripts/ci/step_install_ffmpeg.sh
+
+# --- DooD模式检测：确定宿主机访问地址 ---
+# DooD模式下，docker run启动的容器跑在宿主机Docker上
+# 需要用宿主机IP访问映射端口
+# 检测策略：host.docker.internal -> docker0桥接IP -> 容器IP直连 -> 默认网关 -> 127.0.0.1
+detect_docker_host() {
+  local test_port="${1:-5432}"
+
+  # 候选IP列表
+  local candidates=()
+
+  # 1. host.docker.internal（runner配置了--add-host时可用）
+  if python3 -c "import socket; socket.gethostbyname('host.docker.internal')" 2>/dev/null; then
+    candidates+=("host.docker.internal")
+  fi
+
+  # 2. docker0 桥接网关 (172.17.0.1)
+  candidates+=("172.17.0.1")
+
+  # 3. 默认网关（容器网络的网关即宿主机）
+  local gw=""
+  gw=$(ip route 2>/dev/null | grep default | awk '{print $3}' | head -1)
+  if [ -n "$gw" ] && [ "$gw" != "127.0.0.1" ]; then
+    candidates+=("$gw")
+  fi
+
+  # 4. 宿主机可能的IP：容器同网段的.1或.254
+  local my_ip=""
+  my_ip=$(hostname -I 2>/dev/null | awk '{print $1}')
+  if [ -n "$my_ip" ]; then
+    # 尝试同网段的常见宿主机IP
+    local subnet=$(echo "$my_ip" | cut -d. -f1-3)
+    candidates+=("${subnet}.1")
+    candidates+=("${subnet}.254")
+  fi
+
+  # 5. 127.0.0.1 最后尝试
+  candidates+=("127.0.0.1")
+
+  # 测试每个候选IP
+  for candidate in "${candidates[@]}"; do
+    if python3 -c "
+import socket
+s = socket.socket()
+s.settimeout(2)
+try:
+    s.connect(('$candidate', $test_port))
+    s.close()
+    print('ok')
+except:
+    pass
+" 2>/dev/null | grep -q ok; then
+      echo "$candidate"
+      return 0
+    fi
+  done
+
+  # 都失败则返回127.0.0.1
+  echo "127.0.0.1"
+  return 1
+}
+
+# 获取宿主机IP（先尝试用共享PG端口5433测试，再回退到其他端口）
+if [ -S /var/run/docker.sock ]; then
+  # 先用共享PG端口5433探测
+  DOCKER_HOST_IP=$(detect_docker_host 5433)
+  if [ "$DOCKER_HOST_IP" = "127.0.0.1" ]; then
+    # 如果共享PG端口探测失败，说明不在DooD或共享PG不可用，再试其他端口
+    DOCKER_HOST_IP=$(detect_docker_host 22)
+  fi
+  echo "检测到DooD模式（/var/run/docker.sock已挂载），宿主机地址: $DOCKER_HOST_IP"
+else
+  DOCKER_HOST_IP="127.0.0.1"
+  echo "非DooD模式，使用 127.0.0.1"
+fi
+PG_HOST="$DOCKER_HOST_IP"
+REDIS_HOST="$DOCKER_HOST_IP"
+echo "PG host: $PG_HOST, Redis host: $REDIS_HOST"
+
+# --- 指数退避TCP连接检查函数 ---
+# 用法: wait_tcp_ready host port max_attempts
+wait_tcp_ready() {
+  local host="$1"
+  local port="$2"
+  local max_attempts="${3:-5}"
+  local delay=1
+  local attempt=1
+  while [ "$attempt" -le "$max_attempts" ]; do
+    if python3 -c "import socket; s=socket.socket(); s.settimeout(3); s.connect(('$host', $port)); s.close()" 2>/dev/null; then
+      return 0
+    fi
+    echo "TCP连接尝试 $attempt/$max_attempts 失败，${delay}s后重试..."
+    sleep "$delay"
+    delay=$((delay * 2))
+    attempt=$((attempt + 1))
+  done
+  return 1
+}
+
+# --- 启动 Redis ---
+echo ""
+echo "=== 启动 Redis ==="
+REDIS_CONTAINER="ci-redis-${GITHUB_RUN_ID:-$$}"
+docker rm -f "$REDIS_CONTAINER" 2>/dev/null || true
+docker run -d --name "$REDIS_CONTAINER" \
+  -P \
+  --health-cmd "redis-cli ping" \
+  --health-interval 2s \
+  --health-timeout 2s \
+  --health-retries 10 \
+  redis:7-alpine
+REDIS_PORT=$(docker port "$REDIS_CONTAINER" 6379/tcp | cut -d: -f2)
+echo "Redis port: $REDIS_PORT"
+export REDIS_URL="redis://${REDIS_HOST}:${REDIS_PORT}/0"
+
+# 等待容器健康
+for i in $(seq 1 15); do
+  if docker inspect --format='{{.State.Health.Status}}' "$REDIS_CONTAINER" 2>/dev/null | grep -q healthy; then
+    echo "Redis container is ready on port $REDIS_PORT"
+    break
+  fi
+  echo "Waiting for Redis container health... ($i/15)"
+  sleep 2
+done
+docker inspect --format='{{.State.Health.Status}}' "$REDIS_CONTAINER" | grep -q healthy
+
+# TCP连通性检查（指数退避）
+echo "验证Redis TCP连通性 ($REDIS_HOST:$REDIS_PORT)..."
+wait_tcp_ready "$REDIS_HOST" "$REDIS_PORT" 5
+echo "TCP connectivity to Redis confirmed on port $REDIS_PORT"
+
+# --- 启动/连接 PostgreSQL ---
+echo ""
+echo "=== 准备 PostgreSQL ==="
+USE_SHARED_PG="${CI_USE_SHARED_PG:-false}"
+CI_DB_NAME="ci_run_${GITHUB_RUN_ID:-$$}"
+
+if [ "$USE_SHARED_PG" = "true" ]; then
+  # 使用常驻共享PG实例
+  echo "使用常驻共享PG实例（CI_USE_SHARED_PG=true）"
+  SHARED_PG_HOST="$PG_HOST"
+  SHARED_PG_PORT="5433"
+  SHARED_PG_USER="postgres"
+  SHARED_PG_PASSWORD="ci_pg_2026!"
+
+  echo "等待共享PG连接就绪..."
+  wait_tcp_ready "$SHARED_PG_HOST" "$SHARED_PG_PORT" 5
+
+  # 创建独立数据库
+  echo "创建测试数据库: $CI_DB_NAME"
+  PGPASSWORD="$SHARED_PG_PASSWORD" python3 -c "
+import psycopg2
+conn = psycopg2.connect(host='$SHARED_PG_HOST', port=$SHARED_PG_PORT, user='$SHARED_PG_USER', password='$SHARED_PG_PASSWORD', dbname='postgres')
+conn.autocommit = True
+cur = conn.cursor()
+cur.execute(f'CREATE DATABASE \"$CI_DB_NAME\"')
+cur.close()
+conn.close()
+"
+  export DATABASE_URL="postgresql+psycopg://${SHARED_PG_USER}:${SHARED_PG_PASSWORD}@${SHARED_PG_HOST}:${SHARED_PG_PORT}/${CI_DB_NAME}"
+  echo "✅ 共享PG数据库已创建: $CI_DB_NAME"
+  PG_CONTAINER=""
+else
+  # 使用临时PG容器
+  echo "使用临时PG容器模式"
+  PG_CONTAINER="ci-pg-${GITHUB_RUN_ID:-$$}"
+  docker rm -f "$PG_CONTAINER" 2>/dev/null || true
+  docker run -d --name "$PG_CONTAINER" \
+    --shm-size=256m \
+    -e POSTGRES_USER=postgres \
+    -e POSTGRES_PASSWORD=postgres \
+    -e POSTGRES_DB=xiaoxia_saas \
+    -P \
+    --health-cmd "pg_isready -U postgres" \
+    --health-interval 5s \
+    --health-timeout 5s \
+    --health-retries 12 \
+    postgres:16
+  PG_PORT=$(docker port "$PG_CONTAINER" 5432/tcp | cut -d: -f2)
+  echo "PostgreSQL port: $PG_PORT"
+  export DATABASE_URL="postgresql+psycopg://postgres:postgres@${PG_HOST}:${PG_PORT}/xiaoxia_saas"
+
+  # 等待容器健康
+  for i in $(seq 1 30); do
+    if docker inspect --format='{{.State.Health.Status}}' "$PG_CONTAINER" 2>/dev/null | grep -q healthy; then
+      echo "PostgreSQL container is ready on port $PG_PORT"
+      break
+    fi
+    echo "Waiting for PostgreSQL container health... ($i/30)"
+    sleep 2
+  done
+  docker inspect --format='{{.State.Health.Status}}' "$PG_CONTAINER" | grep -q healthy
+
+  # TCP连通性检查（指数退避）
+  echo "验证PostgreSQL TCP连通性 ($PG_HOST:$PG_PORT)..."
+  wait_tcp_ready "$PG_HOST" "$PG_PORT" 5
+  echo "TCP connectivity to PostgreSQL confirmed on port $PG_PORT"
+fi
+
+# --- 执行迁移 ---
+echo ""
+echo "=== 执行 Alembic 迁移 ==="
+PYTHONPATH="$PWD/apps/api:$PWD" python3 -m alembic upgrade head
+echo "✅ 迁移完成"
+
+# --- 运行集成测试 ---
+echo ""
+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 tests/integration -q --timeout=60 -x --reruns 2 --reruns-delay 1 -m "not performance"
+python3 -m coverage report --show-missing
+python3 -m coverage xml -o coverage.xml
+python3 -m coverage report --fail-under=40 > /dev/null
+echo "✅ 集成测试通过"
+
+# --- API 性能基线测试（仅告警） ---
+echo ""
+echo "=== API 性能基线测试（仅告警） ==="
+set +e
+PERF_OUTPUT=$(mktemp)
+PYTHONPATH="$PWD/apps/api:$PWD" python3 -m pytest tests/integration/test_api_performance.py \
+  -v --timeout=120 -p no:cacheprovider 2>&1 | tee "$PERF_OUTPUT"
+echo ""
+echo "=== 性能测试摘要 ==="
+grep "PERF_STATS:" "$PERF_OUTPUT" || echo "PERF_STATS: 未找到统计数据"
+grep "PERF_RESULT:" "$PERF_OUTPUT" || echo "PERF_RESULT: 未找到详细结果"
+TOTAL=$(grep -c "PERF_RESULT:" "$PERF_OUTPUT" || echo 0)
+PASSED=$(grep "PERF_RESULT: PASS" "$PERF_OUTPUT" | wc -l)
+FAILED=$(grep "PERF_RESULT: FAIL" "$PERF_OUTPUT" | wc -l)
+echo ""
+echo "性能测试结果: $PASSED/$TOTAL 通过, $FAILED 未达标"
+if [ "$FAILED" -gt 0 ]; then
+  echo ""
+  echo "⚠️  警告: $FAILED 个接口性能未达标"
+fi
+rm -f "$PERF_OUTPUT"
+set -e
+
+# --- 清理 ---
+echo ""
+echo "=== 清理 ==="
+if [ "$USE_SHARED_PG" = "true" ]; then
+  # 清理共享PG上的测试数据库
+  echo "清理共享PG测试数据库: $CI_DB_NAME"
+  PGPASSWORD="${SHARED_PG_PASSWORD}" python3 -c "
+import psycopg2
+conn = psycopg2.connect(host='${SHARED_PG_HOST}', port=${SHARED_PG_PORT}, user='${SHARED_PG_USER}', password='${SHARED_PG_PASSWORD}', dbname='postgres')
+conn.autocommit = True
+cur = conn.cursor()
+cur.execute(f'DROP DATABASE IF EXISTS \"$CI_DB_NAME\" WITH (FORCE)')
+cur.close()
+conn.close()
+" 2>/dev/null || echo "WARN: 数据库清理失败（可能已被清理）"
+  echo "✅ 共享PG数据库已清理"
+else
+  # 清理临时PG容器
+  docker rm -f "$PG_CONTAINER" 2>/dev/null || true
+  echo "✅ PG容器已清理"
+fi
+
+# 清理Redis容器
+docker rm -f "$REDIS_CONTAINER" 2>/dev/null || true
+echo "✅ Redis容器已清理"
+
+# --- 覆盖率汇总 ---
+echo ""
+echo "=== 覆盖率汇总 ==="
+set +e
+python3 scripts/ci_coverage_summary.py
+set -e
+
+echo ""
+echo "=== CI Integration Tests 全部通过 ✅ ==="

scripts/ci/run_unit_tests.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# CI Unit Tests Job 主脚本
+# 包含：依赖安装、增量测试选择、覆盖率测试、diff覆盖率门禁
+set -eu
+
+JOB_NAME="${1:-Unit Tests}"
+
+echo "=== CI Unit Tests 开始 ==="
+
+# --- 安装依赖 ---
+echo ""
+echo "=== 安装 Python 依赖 ==="
+# pip install 带重试（网络不稳定时自动重试）
+for i in 1 2 3; do
+  python3 -m pip install -q -r requirements-base.txt && break
+  echo "pip install requirements-base.txt 失败，重试 $i/3..."
+  [ $i -eq 3 ] && exit 1
+  sleep 5
+done
+for i in 1 2 3; do
+  python3 -m pip install -q -r requirements.txt && break
+  echo "pip install requirements.txt 失败，重试 $i/3..."
+  [ $i -eq 3 ] && exit 1
+  sleep 5
+done
+for i in 1 2 3; do
+  python3 -m pip install -q -r requirements-dev.txt && break
+  echo "pip install requirements-dev.txt 失败，重试 $i/3..."
+  [ $i -eq 3 ] && exit 1
+  sleep 5
+done
+pytest --version
+
+# --- 增量测试选择（仅PR） ---
+UNIT_TEST_MODE="full"
+SELECTED_TEST_FILES="tests/unit"
+
+if [ "${GITHUB_EVENT_NAME:-}" = "pull_request" ] && [ -n "${GITHUB_TOKEN:-}" ]; then
+  echo ""
+  echo "=== 增量测试选择 ==="
+  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)"
+  set +e
+  CHANGED_FILES="$CHANGED_FILES" \
+  SELECTED_TESTS_OUTPUT=/tmp/selected_tests.txt \
+  python3 scripts/ci/select_unit_tests.py
+  SELECT_EXIT=$?
+  set -e
+  if [ $SELECT_EXIT -eq 0 ]; then
+    UNIT_TEST_MODE="incremental"
+    TEST_FILES=$(cat /tmp/selected_tests.txt | tr '\n' ' ')
+    SELECTED_TEST_FILES="$TEST_FILES"
+    echo "增量模式: $(cat /tmp/selected_tests.txt | wc -l) 个测试文件"
+  else
+    echo "全量模式"
+  fi
+fi
+
+# --- 运行单元测试 + 覆盖率 ---
+echo ""
+echo "=== 运行单元测试 (模式: $UNIT_TEST_MODE) ==="
+
+if [ "$UNIT_TEST_MODE" = "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
+
+# --- Diff 覆盖率检查（仅PR） ---
+if [ "${GITHUB_EVENT_NAME:-}" = "pull_request" ] && [ -n "${GITHUB_TOKEN:-}" ]; then
+  echo ""
+  echo "=== Diff 覆盖率检查 ==="
+  BASE_BRANCH="${GITHUB_BASE_REF:-develop}"
+  echo "Base branch: $BASE_BRANCH"
+
+  PR_CODE_DIR="/tmp/pr-code-$$"
+  mkdir -p "$PR_CODE_DIR"
+  # 备份PR代码（含coverage.xml，diff-cover需要用到
+  find . -maxdepth 1 -mindepth 1 ! -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"
+  git fetch origin "$BASE_BRANCH" --depth=200
+  # 先清理工作目录，避免未跟踪文件导致checkout失败
+  find . -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +
+  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" = "incremental" ]; then
+    THRESHOLD=40
+    echo "增量测试模式，增量覆盖率门槛: ${THRESHOLD}%"
+  else
+    THRESHOLD=60
+    echo "全量测试模式，增量覆盖率门槛: ${THRESHOLD}%"
+  fi
+
+  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 "✅ 增量覆盖率达标"
+fi
+
+echo ""
+echo "=== CI Unit Tests 全部通过 ✅ ==="

scripts/ci/run_validate.sh

@@ -0,0 +1,381 @@
+#!/bin/bash
+# CI Validate Job 主脚本：代码质量全量检查
+# 包含：密钥扫描、格式检查、类型检查、安全扫描、依赖漏洞检查、死代码检测、Alembic迁移验证
+set -eu
+
+echo "=== CI Validate: 开始全量代码质量检查 ==="
+
+# --- 密钥检测 ---
+echo ""
+echo "=== [1/8] Secret detection (detect-secrets) ==="
+python3 -m pip install -q detect-secrets
+detect-secrets --version
+
+detect-secrets scan \
+  --all-files \
+  --exclude-files '(^|/)(tests|test|e2e|__tests__|spec|docs|node_modules|site-packages|migrations|alembic|.gitea|.git|.pytest_cache|.next|dist|build)/' \
+  --exclude-files '\.(md|rst|txt|lock|example|sample|min\.js|min\.css|spec\.ts|test\.ts|test\.py)$' \
+  --exclude-files '(package-lock|yarn\.lock|poetry\.lock|Pipfile\.lock)$' \
+  --disable-plugin Base64HighEntropyString \
+  --disable-plugin HexHighEntropyString \
+  --disable-plugin BasicAuthDetector \
+  --disable-plugin KeywordDetector \
+  --disable-plugin IPPublicDetector \
+  > /tmp/secrets-scan.json 2>&1
+
+FOUND=$(python3 -c "
+import json
+try:
+    with open('/tmp/secrets-scan.json') as f:
+        data = json.load(f)
+    results = data.get('results', {})
+    total = sum(len(v) for v in results.values())
+    print(total)
+except Exception:
+    print('error')
+")
+
+echo "Secrets detected: $FOUND"
+if [ "$FOUND" != "0" ] && [ "$FOUND" != "error" ]; then
+  echo ""
+  echo "=== Secret details ==="
+  python3 -c "
+import json
+with open('/tmp/secrets-scan.json') as f:
+    data = json.load(f)
+for fpath, items in data.get('results', {}).items():
+    for item in items:
+        line = item.get('line_number', '?')
+        stype = item.get('type', '?')
+        hashed = item.get('hashed_secret', '')[:16]
+        print(f'  {fpath}:{line} [{stype}] {hashed}...')
+"
+  echo ""
+  echo "ERROR: Potential secrets detected in code!"
+  exit 1
+fi
+echo "✅ Secret scan passed"
+
+# --- 增量/全量模式判断 ---
+echo ""
+echo "=== [2/8] Code quality checks ==="
+SCAN_MODE="full"
+CHANGED_PY_FILES=""
+
+if [ "${GITHUB_EVENT_NAME:-}" = "pull_request" ] && [ -n "${GITHUB_REF_NAME:-}" ] && [ -n "${GITHUB_TOKEN:-}" ]; then
+  PR_NUMBER=$(echo "$GITHUB_REF" | sed 's|refs/pull/||; s|/.*||')
+  API_URL="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?limit=100"
+  set +e
+  RESPONSE=$(curl -s -w "\n%{http_code}" -H "Authorization: token ${GITHUB_TOKEN}" "$API_URL")
+  HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+  BODY=$(echo "$RESPONSE" | sed '$d')
+  set -e
+  if [ "$HTTP_CODE" = "200" ]; then
+    CHANGED_PY_FILES=$(echo "$BODY" | python3 -c "
+import json, sys
+try:
+    files = json.load(sys.stdin)
+    py_files = [f['filename'] for f in files if f['filename'].endswith('.py') and f['status'] != 'removed']
+    print(' '.join(py_files))
+except Exception:
+    print('')
+")
+    if [ -n "$CHANGED_PY_FILES" ]; then
+      SCAN_MODE="incremental"
+      echo "Incremental mode: $(echo "$CHANGED_PY_FILES" | wc -w) Python files changed"
+    else
+      SCAN_MODE="skip_py"
+      echo "No Python files changed in this PR"
+    fi
+  else
+    echo "WARN: API returned HTTP $HTTP_CODE, falling back to full scan"
+  fi
+else
+  echo "Full scan mode (not a PR event)"
+fi
+
+if [ "$SCAN_MODE" = "incremental" ]; then
+  # 防御性过滤：磁盘上不存在的文件（已删除文件）不参与检查，
+  # 避免 black/isort/ruff 报 "Path does not exist" 错误。
+  EXISTING_PY_FILES=""
+  for f in $CHANGED_PY_FILES; do
+    if [ -f "$f" ]; then
+      if [ -z "$EXISTING_PY_FILES" ]; then
+        EXISTING_PY_FILES="$f"
+      else
+        EXISTING_PY_FILES="$EXISTING_PY_FILES $f"
+      fi
+    fi
+  done
+  CHANGED_PY_FILES="$EXISTING_PY_FILES"
+
+  python3 -m compileall -q $CHANGED_PY_FILES
+  python3 -m black --check --fast $CHANGED_PY_FILES
+  python3 -m isort --check-only $CHANGED_PY_FILES
+  RUFF_FILES=$(echo "$CHANGED_PY_FILES" | tr ' ' '\n' | grep -v '^scripts/' | grep -v '^$' | xargs)
+  if [ -n "$RUFF_FILES" ]; then
+    python3 -m ruff check $RUFF_FILES --statistics
+  else
+    echo "No ruff-checkable files changed, skipping"
+  fi
+elif [ "$SCAN_MODE" = "skip_py" ]; then
+  echo "No Python files changed - skipping Python lint checks"
+else
+  echo "Full scan mode"
+  python3 -m compileall -q alembic apps packages tests scripts
+  python3 -m black --check --fast alembic apps packages tests scripts
+  python3 -m isort --check-only alembic apps packages tests scripts
+  python3 -m ruff check apps packages tests --statistics
+fi
+echo "✅ Code quality checks passed"
+
+# --- Mypy 类型检查 ---
+echo ""
+echo "=== [3/8] Type check (mypy) ==="
+bash scripts/ci/mypy_check.sh
+echo "✅ Mypy type check passed"
+
+# --- Bandit 安全扫描（仅告警） ---
+echo ""
+echo "=== [4/8] Security scan (bandit, advisory only) ==="
+set +e
+bandit -r apps packages -q -ll
+BANDIT_EXIT=$?
+set -e
+if [ "$BANDIT_EXIT" -ne 0 ]; then
+  echo "⚠️  Bandit found security issues (advisory mode - not blocking CI)"
+else
+  echo "✅ Bandit security scan passed"
+fi
+
+# --- Pip-audit 依赖漏洞扫描（仅告警） ---
+echo ""
+echo "=== [5/8] Python dependency vulnerability scan (pip-audit, advisory only) ==="
+python3 -m pip install -q pip-audit
+pip-audit --version
+EXIT_CODE=0
+for req_file in requirements.txt requirements-base.txt requirements-dev.txt; do
+  if [ -f "$req_file" ]; then
+    echo "--- Scanning $req_file ---"
+    pip-audit -r "$req_file" --desc on 2>&1 | head -40 || EXIT_CODE=$?
+    echo ""
+  fi
+done
+echo "pip-audit scan completed (advisory mode - warnings only, not blocking CI)"
+
+# --- Vulture 死代码检测（仅告警） ---
+echo ""
+echo "=== [6/8] Dead code detection (vulture, advisory only) ==="
+set +e
+python3 -m pip install -q vulture
+vulture --version
+echo "告警模式，不阻断CI。置信度>=90%建议尽快确认。"
+echo ""
+vulture apps packages scripts \
+  --exclude "tests,test,migrations,.gitea,docs,node_modules,site-packages,*/test_*.py,*/conftest.py" \
+  --min-confidence 70 \
+  2>&1 | sort -t'(' -k2 -rn | head -80
+echo ""
+echo "=== vulture scan summary ==="
+echo "发现潜在死代码（可能包含框架装饰器注册的函数，为误报）"
+echo "建议：定期人工审查高置信度（>=90%）条目"
+set -e
+
+# --- Release 脚本语法校验 ---
+echo ""
+echo "=== [7/8] Release scripts syntax validation ==="
+bash -n scripts/backup_postgres.sh
+bash -n scripts/restore_postgres_plan.sh
+bash -n scripts/init_production_env.sh
+echo "✅ Release scripts syntax OK"
+
+# --- Alembic 迁移验证 ---
+echo ""
+echo "=== [8/8] Alembic migrations validation ==="
+
+# --- DooD模式检测：确定宿主机访问地址 ---
+# DooD模式下，docker run启动的容器跑在宿主机Docker上
+# 需要用宿主机IP访问映射端口
+# 检测策略：host.docker.internal -> docker0桥接IP -> 容器IP直连 -> 默认网关 -> 127.0.0.1
+detect_docker_host() {
+  local test_port="${1:-5432}"
+
+  # 候选IP列表
+  local candidates=()
+
+  # 1. host.docker.internal（runner配置了--add-host时可用）
+  if python3 -c "import socket; socket.gethostbyname('host.docker.internal')" 2>/dev/null; then
+    candidates+=("host.docker.internal")
+  fi
+
+  # 2. docker0 桥接网关 (172.17.0.1)
+  candidates+=("172.17.0.1")
+
+  # 3. 默认网关（容器网络的网关即宿主机）
+  local gw=""
+  gw=$(ip route 2>/dev/null | grep default | awk '{print $3}' | head -1)
+  if [ -n "$gw" ] && [ "$gw" != "127.0.0.1" ]; then
+    candidates+=("$gw")
+  fi
+
+  # 4. 宿主机可能的IP：容器同网段的.1或.254
+  local my_ip=""
+  my_ip=$(hostname -I 2>/dev/null | awk '{print $1}')
+  if [ -n "$my_ip" ]; then
+    # 尝试同网段的常见宿主机IP
+    local subnet=$(echo "$my_ip" | cut -d. -f1-3)
+    candidates+=("${subnet}.1")
+    candidates+=("${subnet}.254")
+  fi
+
+  # 5. 127.0.0.1 最后尝试
+  candidates+=("127.0.0.1")
+
+  # 测试每个候选IP
+  for candidate in "${candidates[@]}"; do
+    if python3 -c "
+import socket
+s = socket.socket()
+s.settimeout(2)
+try:
+    s.connect(('$candidate', $test_port))
+    s.close()
+    print('ok')
+except:
+    pass
+" 2>/dev/null | grep -q ok; then
+      echo "$candidate"
+      return 0
+    fi
+  done
+
+  # 都失败则返回127.0.0.1
+  echo "127.0.0.1"
+  return 1
+}
+
+# 获取宿主机IP（先尝试用共享PG端口5433测试，再回退到其他端口）
+if [ -S /var/run/docker.sock ]; then
+  # 先用共享PG端口5433探测
+  DOCKER_HOST_IP=$(detect_docker_host 5433)
+  if [ "$DOCKER_HOST_IP" = "127.0.0.1" ]; then
+    # 如果共享PG端口探测失败，说明不在DooD或共享PG不可用，再试其他端口
+    DOCKER_HOST_IP=$(detect_docker_host 22)
+  fi
+  echo "检测到DooD模式（/var/run/docker.sock已挂载），宿主机地址: $DOCKER_HOST_IP"
+else
+  DOCKER_HOST_IP="127.0.0.1"
+  echo "非DooD模式，使用 127.0.0.1"
+fi
+PG_HOST="$DOCKER_HOST_IP"
+echo "PG host: $PG_HOST"
+
+# 指数退避TCP连接检查函数
+# 用法: wait_tcp_ready host port max_attempts
+wait_tcp_ready() {
+  local host="$1"
+  local port="$2"
+  local max_attempts="${3:-5}"
+  local delay=1
+  local attempt=1
+  while [ "$attempt" -le "$max_attempts" ]; do
+    if python3 -c "import socket; s=socket.socket(); s.settimeout(3); s.connect(('$host', $port)); s.close()" 2>/dev/null; then
+      return 0
+    fi
+    echo "TCP连接尝试 $attempt/$max_attempts 失败，${delay}s后重试..."
+    sleep "$delay"
+    delay=$((delay * 2))
+    attempt=$((attempt + 1))
+  done
+  return 1
+}
+
+USE_SHARED_PG="${CI_USE_SHARED_PG:-false}"
+
+if [ "$USE_SHARED_PG" = "true" ]; then
+  # 使用常驻共享PG实例（host.docker.internal:5433）
+  echo "使用常驻共享PG实例（CI_USE_SHARED_PG=true）"
+  SHARED_PG_HOST="$PG_HOST"
+  SHARED_PG_PORT="5433"
+  SHARED_PG_USER="postgres"
+  SHARED_PG_PASSWORD="ci_pg_2026!"
+  CI_DB_NAME="ci_run_${GITHUB_RUN_ID:-$$}"
+
+  echo "等待共享PG连接就绪..."
+  wait_tcp_ready "$SHARED_PG_HOST" "$SHARED_PG_PORT" 5
+
+  # 创建独立数据库
+  echo "创建测试数据库: $CI_DB_NAME"
+  PGPASSWORD="$SHARED_PG_PASSWORD" python3 -c "
+import psycopg2
+conn = psycopg2.connect(host='$SHARED_PG_HOST', port=$SHARED_PG_PORT, user='$SHARED_PG_USER', password='$SHARED_PG_PASSWORD', dbname='postgres')
+conn.autocommit = True
+cur = conn.cursor()
+cur.execute(f'CREATE DATABASE \"$CI_DB_NAME\"')
+cur.close()
+conn.close()
+"
+  export DATABASE_URL="postgresql+psycopg://${SHARED_PG_USER}:${SHARED_PG_PASSWORD}@${SHARED_PG_HOST}:${SHARED_PG_PORT}/${CI_DB_NAME}"
+  echo "✅ 共享PG数据库已创建: $CI_DB_NAME"
+
+  # 执行迁移
+  PYTHONPATH="$PWD/apps/api:$PWD" python3 -m alembic upgrade head
+  echo "✅ Alembic migrations applied successfully"
+
+  # 清理数据库
+  echo "清理测试数据库: $CI_DB_NAME"
+  PGPASSWORD="$SHARED_PG_PASSWORD" python3 -c "
+import psycopg2
+conn = psycopg2.connect(host='$SHARED_PG_HOST', port=$SHARED_PG_PORT, user='$SHARED_PG_USER', password='$SHARED_PG_PASSWORD', dbname='postgres')
+conn.autocommit = True
+cur = conn.cursor()
+cur.execute(f'DROP DATABASE IF EXISTS \"$CI_DB_NAME\" WITH (FORCE)')
+cur.close()
+conn.close()
+" 2>/dev/null || echo "WARN: 数据库清理失败（可能已被清理）"
+  echo "✅ 共享PG数据库已清理"
+else
+  # 使用临时PG容器（默认模式）
+  echo "使用临时PG容器模式"
+  PG_CONTAINER=ci-pg-validate-${GITHUB_RUN_ID:-$$}
+  docker rm -f "$PG_CONTAINER" 2>/dev/null || true
+  docker run -d --name "$PG_CONTAINER" \
+    --shm-size=256m \
+    -e POSTGRES_USER=postgres \
+    -e POSTGRES_PASSWORD=postgres \
+    -e POSTGRES_DB=xiaoxia_saas \
+    -P \
+    --health-cmd "pg_isready -U postgres" \
+    --health-interval 3s \
+    --health-timeout 3s \
+    --health-retries 20 \
+    postgres:16-alpine
+  PG_PORT=$(docker port "$PG_CONTAINER" 5432/tcp | cut -d: -f2)
+  echo "PostgreSQL port: $PG_PORT"
+  export DATABASE_URL="postgresql+psycopg://postgres:postgres@${PG_HOST}:${PG_PORT}/xiaoxia_saas"
+
+  # 等待容器健康
+  for i in $(seq 1 30); do
+    if docker inspect --format='{{.State.Health.Status}}' "$PG_CONTAINER" 2>/dev/null | grep -q healthy; then
+      echo "PostgreSQL container is healthy on port $PG_PORT"
+      break
+    fi
+    echo "Waiting for PostgreSQL container health... ($i/30)"
+    sleep 2
+  done
+  docker inspect --format='{{.State.Health.Status}}' "$PG_CONTAINER" | grep -q healthy
+
+  # TCP连通性检查（指数退避）
+  echo "验证TCP连通性 ($PG_HOST:$PG_PORT)..."
+  wait_tcp_ready "$PG_HOST" "$PG_PORT" 5
+  echo "TCP connectivity to PostgreSQL confirmed on port $PG_PORT"
+
+  # 执行迁移
+  PYTHONPATH="$PWD/apps/api:$PWD" python3 -m alembic upgrade head
+  echo "✅ Alembic migrations applied successfully"
+
+  docker rm -f "$PG_CONTAINER" 2>/dev/null || true
+fi
+
+echo ""
+echo "=== CI Validate: 所有检查通过 ✅ ==="

scripts/ci/select_unit_tests.py

@@ -158,10 +158,13 @@ def select_tests(changed_files):
     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)
+            if (ROOT / f).exists():
+                test_file_changes.append(f)
+                selected.add(f)
+            else:
+                print(f"[skip-deleted] 测试文件已删除，跳过: {f}")
         # 源码文件改动
         elif f.endswith(".py"):
             source_file_changes.append(f)

scripts/ci/step_checkout.sh

@@ -0,0 +1,44 @@
+#!/bin/sh
+# CI 公共步骤：Checkout 代码（带重试）
+# 用法：直接 source 或调用，需要 GITHUB_TOKEN 环境变量
+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

scripts/ci/step_frontend_install.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+# CI 公共步骤：前端依赖安装（在 docker node 容器中运行）
+# 用法：step_frontend_install.sh [模式]
+#   模式: full (默认) - 完整安装所有依赖
+#        vitest       - 同full（保持接口兼容）
+set -eu
+
+MODE="${1:-full}"
+
+echo "=== 前端依赖安装开始 (模式: $MODE) ==="
+
+# npm ci 带重试（网络不稳定时自动重试）
+for i in 1 2 3; do
+  docker run --rm \
+    -v "$PWD:/workspace" \
+    -w /workspace/apps/web \
+    docker.m.daocloud.io/library/node:20 \
+    sh -lc "npm ci --no-audit --no-fund" && break
+  echo "npm ci 失败，重试 $i/3..."
+  [ $i -eq 3 ] && exit 1
+  sleep 5
+done
+
+echo "=== 前端依赖安装完成 ==="

scripts/ci/step_frontend_run.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# CI 公共步骤：前端命令执行（在 docker node 容器中运行）
+# 用法：step_frontend_run.sh "要执行的命令"
+set -eu
+
+CMD="${1:-echo 'no command'}"
+
+docker run --rm \
+  -v "$PWD:/workspace" \
+  -w /workspace/apps/web \
+  docker.m.daocloud.io/library/node:20 \
+  sh -lc "$CMD"

scripts/ci/step_install_ffmpeg.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+# CI 公共步骤：安装 ffmpeg
+set +e
+if command -v ffmpeg > /dev/null 2>&1; then
+  echo "ffmpeg already installed: $(ffmpeg -version | head -1)"
+  exit 0
+fi
+if command -v apt-get > /dev/null 2>&1; then
+  apt-get update -qq && apt-get install -y -qq ffmpeg
+elif command -v yum > /dev/null 2>&1; then
+  yum install -y -q epel-release 2>/dev/null
+  yum install -y -q ffmpeg 2>/dev/null
+  if [ $? -ne 0 ] && command -v dnf > /dev/null 2>&1; then
+    dnf install -y -q --nogpgcheck https://download1.rpmfusion.org/free/el/rpmfusion-free-release-$(rpm -E %rhel).noarch.rpm 2>/dev/null
+    dnf install -y -q ffmpeg 2>/dev/null
+  fi
+elif command -v dnf > /dev/null 2>&1; then
+  dnf install -y -q ffmpeg 2>/dev/null
+fi
+if command -v ffmpeg > /dev/null 2>&1; then
+  echo "ffmpeg installed successfully: $(ffmpeg -version | head -1)"
+else
+  echo "Warning: ffmpeg installation failed or not available, some tests may be skipped"
+fi

scripts/ci/step_timer_end.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+# CI 公共步骤：Job 结束计时统计
+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

scripts/ci/step_timer_start.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# CI 公共步骤：Job 开始计时
+echo "JOB_START_TIME=$(date +%s)" >> $GITHUB_ENV
+echo "Job started at $(date)"

scripts/ci_production_deploy.sh

@@ -0,0 +1,444 @@
+#!/bin/sh
+# ===========================================
+# Production 部署脚本（SSH 模式，支持自动回滚）
+# ===========================================
+# 通过 SSH 在 production 服务器上执行
+#
+# 环境变量:
+#   IMAGE_TAG       - 镜像版本 tag（如 commit SHA 或分支名）
+#   REGISTRY_TOKEN  - Registry 访问令牌
+#   REGISTRY        - Registry 地址（默认 xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji）
+#   REGISTRY_USER   - Registry 用户名（默认 xiaoxia）
+#   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)"
+  export REGISTRY_TOKEN REGISTRY_HOST REGISTRY_USER
+  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}}"
+REGISTRY_TOKEN="${ACR_PASSWORD:-${REGISTRY_TOKEN:-}}"
+
+ENV_FILE="${ENV_FILE:-/var/lib/xiaoxia-saas-production/.env}"
+GENERATED_DIR="${GENERATED_DIR:-/var/lib/xiaoxia-saas-production/generated}"
+LEGACY_ASSETS_DIR="${LEGACY_ASSETS_DIR:-/var/lib/xiaoxia-saas-production/legacy-assets}"
+
+SKIP_MIGRATION="${SKIP_MIGRATION:-false}"
+SKIP_ROLLBACK="${SKIP_ROLLBACK:-false}"
+
+if [ -z "$IMAGE_TAG" ]; then
+  echo "ERROR: IMAGE_TAG is required"
+  exit 1
+fi
+
+test -f "$ENV_FILE"
+mkdir -p "$GENERATED_DIR"
+mkdir -p "$LEGACY_ASSETS_DIR"
+
+echo "==========================================="
+echo "  Production 部署 - $IMAGE_TAG"
+echo "==========================================="
+
+# ---- 记录当前运行的镜像版本（用于回滚） ----
+echo "Recording current image versions for rollback..."
+PREV_API_IMAGE=""
+PREV_WORKER_IMAGE=""
+PREV_WEB_IMAGE=""
+for c in xiaoxia-api-production xiaoxia-worker-production xiaoxia-web-production; do
+  if docker inspect "$c" >/dev/null 2>&1; then
+    img=$(docker inspect -f '{{.Config.Image}}' "$c")
+    case "$c" in
+      xiaoxia-api-production) PREV_API_IMAGE="$img" ;;
+      xiaoxia-worker-production) PREV_WORKER_IMAGE="$img" ;;
+      xiaoxia-web-production) 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-production 2>/dev/null || true
+  docker rm -f xiaoxia-worker-production 2>/dev/null || true
+  docker rm -f xiaoxia-web-production 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-production \
+      --env-file "$ENV_FILE" \
+      --network xiaoxia-net-production \
+      -p 127.0.0.1:8001:8000 \
+      -e APP_ENV=production \
+      -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://production-api.xiaoxiajianji.com \
+      -v "$GENERATED_DIR:/app/generated" \
+      --restart unless-stopped \
+  --cpus 2 \
+  --memory 2g \
+      --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-production \
+      --env-file "$ENV_FILE" \
+      --network xiaoxia-net-production \
+      -e APP_ENV=production \
+      -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://production-api.xiaoxiajianji.com \
+      -v "$GENERATED_DIR:/app/generated" \
+      --restart unless-stopped \
+  --cpus 2 \
+  --memory 2g \
+      --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-production \
+      --network xiaoxia-net-production \
+      -p 127.0.0.1:3002:80 \
+      --restart unless-stopped \
+  --cpus 0.5 \
+  --memory 512m \
+      $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:8001/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-production
+    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 production
+  exit 1
+}
+
+# ---- 登录 Registry ----
+if [ -n "$REGISTRY_TOKEN" ]; then
+  echo "=========================================="
+  echo "  Login to Registry (with retries)"
+  echo "=========================================="
+  REGISTRY_HOST=$(echo "$REGISTRY" | cut -d/ -f1)
+  retry_docker_login
+fi
+
+# ---- Pull 新版本镜像 ----
+REGISTRY_API="${REGISTRY}/xiaoxia-saas-api:${IMAGE_TAG}"
+REGISTRY_WORKER="${REGISTRY}/xiaoxia-saas-worker:${IMAGE_TAG}"
+REGISTRY_WEB="${REGISTRY}/xiaoxia-saas-web:${IMAGE_TAG}"
+
+echo "=========================================="
+echo "  Pull images (with retries)"
+echo "=========================================="
+retry_docker_pull "$REGISTRY_API"
+retry_docker_pull "$REGISTRY_WORKER"
+retry_docker_pull "$REGISTRY_WEB"
+
+echo "All images pulled."
+
+# ---- 备份 legacy assets ----
+echo "Backing up legacy assets from current web container..."
+if docker inspect xiaoxia-web-production >/dev/null 2>&1; then
+  _tmpdir="/tmp/legacy-assets-$$"
+  rm -rf "$_tmpdir"
+  mkdir -p "$_tmpdir"
+  docker cp xiaoxia-web-production:/usr/share/nginx/html/assets/. "$_tmpdir/" 2>/dev/null || true
+  # 只有目录非空才拷贝，避免覆盖有内容的 legacy assets
+  if [ -d "$_tmpdir" ] && [ "$(ls -A "$_tmpdir" 2>/dev/null)" ]; then
+    cp -an "$_tmpdir"/. "$LEGACY_ASSETS_DIR"/ 2>/dev/null || true
+    echo "Legacy assets backed up: $(ls "$_tmpdir" | wc -l) files"
+  fi
+  rm -rf "$_tmpdir"
+else
+  echo "No existing web container, skipping legacy assets backup"
+fi
+
+# 清理 7 天前的 legacy assets
+if [ -d "$LEGACY_ASSETS_DIR" ]; then
+  find "$LEGACY_ASSETS_DIR" -type f -mtime +7 -delete 2>/dev/null || true
+  echo "Legacy assets cleanup done (retain 7 days)"
+fi
+
+# ---- 检查基础设施容器 ----
+echo "Checking infrastructure containers..."
+for c in xiaoxia-postgres-production xiaoxia-redis-production; do
+  if ! docker inspect "$c" >/dev/null 2>&1; then
+    echo "ERROR: Required container not found: $c"
+    exit 1
+  fi
+  state=$(docker inspect -f '{{.State.Status}}' "$c")
+  if [ "$state" != "running" ]; then
+    echo "ERROR: Container not running: $c ($state)"
+    exit 1
+  fi
+done
+
+# ---- 创建网络（不存在则创建） ----
+docker network create xiaoxia-net-production 2>/dev/null || true
+
+# ---- 数据库迁移 ----
+if [ "$SKIP_MIGRATION" != "true" ]; then
+  echo "Running database migrations..."
+  docker run --rm \
+    --env-file "$ENV_FILE" \
+    --network xiaoxia-net-production \
+    -e APP_ENV=production \
+    "$REGISTRY_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)"
+fi
+
+# ---- 停止旧容器 ----
+echo "Stopping old containers..."
+docker rm -f xiaoxia-api-production 2>/dev/null || true
+docker rm -f xiaoxia-worker-production 2>/dev/null || true
+docker rm -f xiaoxia-web-production 2>/dev/null || true
+
+LOG_OPTS="--log-driver json-file --log-opt max-size=50m --log-opt max-file=3"
+
+# ---- 启动 API ----
+echo "Starting API container..."
+docker run -d \
+  --name xiaoxia-api-production \
+  --env-file "$ENV_FILE" \
+  --network xiaoxia-net-production \
+  -p 127.0.0.1:8001:8000 \
+  -e APP_ENV=production \
+  -e APP_VERSION="$IMAGE_TAG" \
+  -e GENERATED_FILES_DIR=/app/generated \
+  -e GENERATED_FILES_URL_PREFIX=/generated-files \
+  -e PUBLIC_API_BASE_URL=https://production-api.xiaoxiajianji.com \
+  -v "$GENERATED_DIR:/app/generated" \
+  --restart unless-stopped \
+  --cpus 2 \
+  --memory 2g \
+  --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 \
+  "$REGISTRY_API" || rollback
+
+# ---- 启动 Worker ----
+echo "Starting Worker container..."
+docker run -d \
+  --name xiaoxia-worker-production \
+  --env-file "$ENV_FILE" \
+  --network xiaoxia-net-production \
+  -e APP_ENV=production \
+  -e APP_VERSION="$IMAGE_TAG" \
+  -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://production-api.xiaoxiajianji.com \
+  -v "$GENERATED_DIR:/app/generated" \
+  --restart unless-stopped \
+  --cpus 2 \
+  --memory 2g \
+  --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 \
+  "$REGISTRY_WORKER" || rollback
+
+# ---- 启动 Web ----
+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"
+  echo "Web container: legacy assets mounted (fallback)"
+else
+  echo "Web container: no legacy assets to mount"
+fi
+
+echo "Starting Web container..."
+docker run -d \
+  --name xiaoxia-web-production \
+  --network xiaoxia-net-production \
+  -p 127.0.0.1:3002:80 \
+  --restart unless-stopped \
+  --cpus 0.5 \
+  --memory 512m \
+  $LEGACY_VOLUME \
+  --health-cmd "wget --spider -q http://127.0.0.1:80" \
+  --health-interval 30s \
+  --health-timeout 5s \
+  --health-retries 3 \
+  $LOG_OPTS \
+  "$REGISTRY_WEB" || rollback
+
+# ---- 等待 API 健康 ----
+echo "Waiting for API to become healthy..."
+i=0
+while [ "$i" -lt 40 ]; do
+  if curl -sf --max-time 5 http://127.0.0.1:8001/health >/dev/null 2>&1; then
+    echo "API is healthy!"
+    break
+  fi
+  i=$((i + 1))
+  echo "  Waiting... ($i/40)"
+  sleep 3
+done
+
+if [ "$i" -ge 40 ]; then
+  echo "ERROR: API did not become healthy within 120s"
+  docker logs --tail 50 xiaoxia-api-production
+  rollback
+fi
+
+# ---- 等待 Web 健康 ----
+echo "Waiting for Web to become healthy..."
+i=0
+while [ "$i" -lt 15 ]; do
+  if curl -sf --max-time 5 http://127.0.0.1:3002/ >/dev/null 2>&1; then
+    echo "Web is healthy!"
+    break
+  fi
+  i=$((i + 1))
+  echo "  Waiting... ($i/15)"
+  sleep 2
+done
+
+if [ "$i" -ge 15 ]; then
+  echo "ERROR: Web did not become healthy within 30s"
+  docker logs --tail 30 xiaoxia-web-production
+  rollback
+fi
+
+# ---- 清理旧镜像 ----
+echo "Cleaning up old images..."
+docker image prune -af --filter "until=168h" 2>/dev/null || true
+docker builder prune -af --filter "until=168h" 2>/dev/null || true
+
+echo ""
+echo "=== Production deployment complete ==="
+echo "API:      http://127.0.0.1:8000"
+echo "Web:      http://127.0.0.1:3001"
+echo "Version:  $IMAGE_TAG"
+docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep production

scripts/ci_staging_deploy.sh

@@ -37,7 +37,8 @@ retry_cmd() {
 
 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
+  export REGISTRY_TOKEN REGISTRY_HOST REGISTRY_USER
+  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"
@@ -237,10 +238,6 @@ REGISTRY_API="${REGISTRY}/xiaoxia-saas-api:${IMAGE_TAG}"
 REGISTRY_WORKER="${REGISTRY}/xiaoxia-saas-worker:${IMAGE_TAG}"
 REGISTRY_WEB="${REGISTRY}/xiaoxia-saas-web:${IMAGE_TAG}"
 
-LOCAL_API="xiaoxia-saas-api:${IMAGE_TAG}"
-LOCAL_WORKER="xiaoxia-saas-worker:${IMAGE_TAG}"
-LOCAL_WEB="xiaoxia-saas-web:${IMAGE_TAG}"
-
 echo "=========================================="
 echo "  Pull images (with retries)"
 echo "=========================================="
@@ -248,11 +245,7 @@ retry_docker_pull "$REGISTRY_API"
 retry_docker_pull "$REGISTRY_WORKER"
 retry_docker_pull "$REGISTRY_WEB"
 
-# Re-tag 成本地名
-docker tag "$REGISTRY_API" "$LOCAL_API"
-docker tag "$REGISTRY_WORKER" "$LOCAL_WORKER"
-docker tag "$REGISTRY_WEB" "$LOCAL_WEB"
-echo "All images pulled and tagged."
+echo "All images pulled."
 
 # ---- 备份 legacy assets ----
 echo "Backing up legacy assets from current web container..."
@@ -301,7 +294,7 @@ 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" || {
+    "$REGISTRY_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"
@@ -340,7 +333,7 @@ docker run -d \
   --health-retries 3 \
   --health-start-period 40s \
   $LOG_OPTS \
-  "$LOCAL_API" || rollback
+  "$REGISTRY_API" || rollback
 
 # ---- 启动 Worker ----
 echo "Starting Worker container..."
@@ -363,7 +356,7 @@ docker run -d \
   --health-retries 3 \
   --health-start-period 30s \
   $LOG_OPTS \
-  "$LOCAL_WORKER" || rollback
+  "$REGISTRY_WORKER" || rollback
 
 # ---- 启动 Web ----
 LEGACY_VOLUME=""
@@ -386,7 +379,7 @@ docker run -d \
   --health-timeout 5s \
   --health-retries 3 \
   $LOG_OPTS \
-  "$LOCAL_WEB" || rollback
+  "$REGISTRY_WEB" || rollback
 
 # ---- 等待 API 健康 ----
 echo "Waiting for API to become healthy..."

tests/unit/test_feature_flag.py

@@ -1,6 +1,6 @@
 """Feature Flag 单元测试。
 
-测试 FeatureFlagConfig、InMemoryFeatureFlagStore、RenderEngineResolver 的核心逻辑。
+测试 FeatureFlagConfig、InMemoryFeatureFlagStore、RedisFeatureFlagStore 的核心逻辑。
 """
 
 from __future__ import annotations
@@ -184,148 +184,6 @@ class TestInMemoryFeatureFlagStore:
         assert store.is_active("nonexistent") is False
 
 
-# ── RenderEngineResolver 测试 ───────────────────────────────────────────────
-
-
-class TestRenderEngineResolver:
-    """渲染引擎选择器测试。"""
-
-    def test_default_legacy_when_flag_disabled(self):
-        """flag 关闭时使用默认引擎（legacy）。"""
-        store = InMemoryFeatureFlagStore()
-        resolver = self._make_resolver(store=store, default="legacy")
-        assert resolver.get_engine() == "legacy"
-        assert resolver.get_engine("user1") == "legacy"
-
-    def test_default_unified_when_flag_disabled(self):
-        """flag 关闭但默认值是 unified 时返回 unified。"""
-        store = InMemoryFeatureFlagStore()
-        resolver = self._make_resolver(store=store, default="unified")
-        assert resolver.get_engine() == "unified"
-
-    def test_whitelist_user_uses_unified(self):
-        """白名单用户走新引擎。"""
-        store = InMemoryFeatureFlagStore()
-        store.set(
-            FeatureFlagConfig(
-                name="render_engine",
-                enabled=True,
-                percentage=0,
-                whitelist={"beta_tester"},
-            )
-        )
-        resolver = self._make_resolver(store=store, default="legacy")
-        assert resolver.get_engine("beta_tester") == "unified"
-        assert resolver.get_engine("normal_user") == "legacy"
-
-    def test_100_percent_all_unified(self):
-        """100% 时所有用户走新引擎。"""
-        store = InMemoryFeatureFlagStore()
-        store.set(FeatureFlagConfig(name="render_engine", enabled=True, percentage=100))
-        resolver = self._make_resolver(store=store, default="legacy")
-        for i in range(50):
-            assert resolver.get_engine(f"user_{i}") == "unified"
-
-    def test_invalid_default_engine_fallback(self):
-        """无效默认值回退到 legacy。"""
-        store = InMemoryFeatureFlagStore()
-        resolver = self._make_resolver(store=store, default="invalid_value")
-        assert resolver.get_engine() == "legacy"
-
-    def test_should_use_unified_helper(self):
-        """should_use_unified 便捷方法。"""
-        store = InMemoryFeatureFlagStore()
-        store.set(
-            FeatureFlagConfig(
-                name="render_engine",
-                enabled=True,
-                percentage=0,
-                whitelist={"user_a"},
-            )
-        )
-        resolver = self._make_resolver(store=store)
-        assert resolver.should_use_unified("user_a") is True
-        assert resolver.should_use_unified("user_b") is False
-
-    def test_config_snapshot(self):
-        """配置快照。"""
-        store = InMemoryFeatureFlagStore()
-        store.set(
-            FeatureFlagConfig(
-                name="render_engine",
-                enabled=True,
-                percentage=30,
-                whitelist={"u1", "u2"},
-            )
-        )
-        resolver = self._make_resolver(store=store)
-        snapshot = resolver.get_config_snapshot()
-        assert snapshot["flag_name"] == "render_engine"
-        assert snapshot["enabled"] is True
-        assert snapshot["percentage"] == 30
-        assert snapshot["whitelist"] == ["u1", "u2"]
-
-    def test_set_flag_updates_config(self):
-        """通过 set_flag 修改后立即生效。"""
-        store = InMemoryFeatureFlagStore()
-        resolver = self._make_resolver(store=store, default="legacy")
-
-        # 初始：关闭
-        assert resolver.get_engine("user1") == "legacy"
-
-        # 开启 100%
-        resolver.set_flag(FeatureFlagConfig(name="render_engine", enabled=True, percentage=100))
-        assert resolver.get_engine("user1") == "unified"
-
-        # 关闭
-        resolver.set_flag(FeatureFlagConfig(name="render_engine", enabled=False))
-        assert resolver.get_engine("user1") == "legacy"
-
-    def test_force_refresh(self):
-        """强制刷新不报错。"""
-        store = InMemoryFeatureFlagStore()
-        resolver = self._make_resolver(store=store)
-        resolver.force_refresh()  # 不抛异常即可
-
-    def test_does_not_affect_in_flight_tasks(self):
-        """
-        热更新不影响在途任务验证：
-        任务开始时确定引擎，中途配置变更不改变当前任务的引擎选择。
-        （这是通过"每次调用 get_engine 时读取当前配置"来保证的，
-        任务开始时调用一次拿到结果，之后不再变化）
-        """
-        store = InMemoryFeatureFlagStore()
-        store.set(FeatureFlagConfig(name="render_engine", enabled=True, percentage=100))
-        resolver = self._make_resolver(store=store, default="legacy")
-
-        # 模拟任务开始时获取引擎
-        engine_at_start = resolver.get_engine("user1")
-        assert engine_at_start == "unified"
-
-        # 任务进行中关闭 flag
-        store.set(FeatureFlagConfig(name="render_engine", enabled=False))
-        resolver.force_refresh()
-
-        # 在途任务持有的 engine_at_start 仍然是 unified（不随配置变化）
-        assert engine_at_start == "unified"
-        # 新任务会拿到 legacy
-        assert resolver.get_engine("user1") == "legacy"
-
-    # ── 辅助方法 ──
-
-    @staticmethod
-    def _make_resolver(store=None, default="legacy"):
-        from apps.worker.video_processing.render_engine_resolver import (
-            RenderEngineResolver,
-        )
-
-        return RenderEngineResolver(
-            default_engine=default,
-            store=store or InMemoryFeatureFlagStore(),
-            refresh_interval=9999,  # 测试时禁用自动刷新
-        )
-
-
 # ── RedisFeatureFlagStore 降级测试（无 Redis 环境） ───────────────────────
 
 

tests/unit/test_generation_feature_flag.py

@@ -1,332 +0,0 @@
-"""generate_video 任务 Feature Flag 灰度引擎选择单元测试.
-
-覆盖：
-- _resolve_render_engine 正常返回 unified / legacy
-- Feature Flag 不可用时 fallback 到 unified
-- 白名单 / 百分比 / 全局开关各场景
-- _render_with_legacy_engine 命令构建与输出验证
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from types import ModuleType
-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")
-
-from pathlib import Path
-
-# ── Mock worker 模块以避免数据库连接 ──────────────────────────────────────────
-
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "apps", "worker"))
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", ".."))
-
-_mock_db_mod = ModuleType("worker_app.db")
-_mock_db_mod.SessionLocal = MagicMock()
-sys.modules.setdefault("worker_app.db", _mock_db_mod)
-
-_mock_celery_mod = ModuleType("worker_app.celery_app")
-_mock_celery_app = MagicMock()
-_mock_celery_app.task = lambda **kwargs: lambda fn: fn
-_mock_celery_mod.celery_app = _mock_celery_app
-sys.modules.setdefault("worker_app.celery_app", _mock_celery_mod)
-
-# Mock worker_app.core.config 避免 settings 加载
-_mock_config_mod = ModuleType("worker_app.core.config")
-_mock_settings = MagicMock()
-_mock_settings.redis_url = None
-_mock_settings.render_engine = "unified"
-_mock_config_mod.get_settings = lambda: _mock_settings
-sys.modules.setdefault("worker_app.core", ModuleType("worker_app.core"))
-sys.modules.setdefault("worker_app.core.config", _mock_config_mod)
-
-
-# ── 测试用数据类 ──────────────────────────────────────────────────────────────
-
-
-class _TestClip:
-    def __init__(self, asset_id, duration=30.0, clip_type="main", config=None, order=0):
-        self.id = f"clip_{asset_id}"
-        self.plan_id = "test-plan"
-        self.clip_type = clip_type
-        self.order = order
-        self.asset_id = asset_id
-        self.duration = duration
-        self.config = config or {}
-        self.start_time = 0.0
-        self.transition_effect = "cut"
-
-
-# ── RenderEngineResolver 基础行为测试 ───────────────────────────────────────
-
-
-def test_resolver_unified_when_enabled_100_percent():
-    """flag 全局开启（percentage=100）时，返回 unified。"""
-    from video_processing.render_engine_resolver import RenderEngineResolver
-
-    from packages.adapters.redis.feature_flag_store import (
-        FeatureFlagConfig,
-        InMemoryFeatureFlagStore,
-    )
-
-    store = InMemoryFeatureFlagStore()
-    store.set(FeatureFlagConfig(name="render_engine", enabled=True, percentage=100))
-    resolver = RenderEngineResolver(default_engine="legacy", store=store)
-
-    assert resolver.get_engine(user_id="user-123") == "unified"
-
-
-def test_resolver_legacy_when_flag_disabled():
-    """flag 全局关闭时，返回默认引擎 legacy。"""
-    from video_processing.render_engine_resolver import RenderEngineResolver
-
-    from packages.adapters.redis.feature_flag_store import (
-        FeatureFlagConfig,
-        InMemoryFeatureFlagStore,
-    )
-
-    store = InMemoryFeatureFlagStore()
-    store.set(FeatureFlagConfig(name="render_engine", enabled=False, percentage=100))
-    resolver = RenderEngineResolver(default_engine="legacy", store=store)
-
-    assert resolver.get_engine(user_id="user-123") == "legacy"
-
-
-def test_resolver_whitelist_overrides_percentage_0():
-    """白名单用户即使 percentage=0 也走 unified。"""
-    from video_processing.render_engine_resolver import RenderEngineResolver
-
-    from packages.adapters.redis.feature_flag_store import (
-        FeatureFlagConfig,
-        InMemoryFeatureFlagStore,
-    )
-
-    store = InMemoryFeatureFlagStore()
-    store.set(
-        FeatureFlagConfig(
-            name="render_engine",
-            enabled=True,
-            percentage=0,
-            whitelist={"user-vip"},
-        )
-    )
-    resolver = RenderEngineResolver(default_engine="legacy", store=store)
-
-    assert resolver.get_engine(user_id="user-vip") == "unified"
-    assert resolver.get_engine(user_id="user-other") == "legacy"
-
-
-def test_resolver_percentage_0_all_legacy():
-    """percentage=0 且无白名单时，全部走 legacy。"""
-    from video_processing.render_engine_resolver import RenderEngineResolver
-
-    from packages.adapters.redis.feature_flag_store import (
-        FeatureFlagConfig,
-        InMemoryFeatureFlagStore,
-    )
-
-    store = InMemoryFeatureFlagStore()
-    store.set(FeatureFlagConfig(name="render_engine", enabled=True, percentage=0))
-    resolver = RenderEngineResolver(default_engine="legacy", store=store)
-
-    for i in range(50):
-        assert resolver.get_engine(user_id=f"user-{i}") == "legacy"
-
-
-def test_resolver_default_unified_when_flag_off():
-    """默认引擎设为 unified 且 flag 关闭时，返回 unified。"""
-    from video_processing.render_engine_resolver import RenderEngineResolver
-
-    from packages.adapters.redis.feature_flag_store import (
-        FeatureFlagConfig,
-        InMemoryFeatureFlagStore,
-    )
-
-    store = InMemoryFeatureFlagStore()
-    store.set(FeatureFlagConfig(name="render_engine", enabled=False, percentage=0))
-    resolver = RenderEngineResolver(default_engine="unified", store=store)
-
-    assert resolver.get_engine(user_id="user-123") == "unified"
-
-
-# ── _render_with_legacy_engine 集成测试 ──────────────────────────────────────
-
-
-def test_legacy_engine_single_clip_keeps_original_fps():
-    """单 clip 场景：输出保持原帧率（不做 fps 归一化），分辨率缩放正确。"""
-    import subprocess
-    import tempfile
-
-    from video_processing.ffmpeg_utils import probe_video_info
-
-    from apps.worker.worker_app.tasks.generation import _render_with_legacy_engine
-
-    with tempfile.TemporaryDirectory() as tmpdir:
-        tmp_path = Path(tmpdir)
-        input_path = tmp_path / "input.mp4"
-        output_path = tmp_path / "output.mp4"
-
-        # 生成 1 秒 30fps 测试视频（带音频）
-        subprocess.run(
-            [
-                "ffmpeg",
-                "-y",
-                "-f",
-                "lavfi",
-                "-i",
-                "color=c=red:s=640x360:d=1:r=30",
-                "-f",
-                "lavfi",
-                "-i",
-                "anullsrc=r=44100:cl=stereo:d=1",
-                "-c:v",
-                "libx264",
-                "-pix_fmt",
-                "yuv420p",
-                "-c:a",
-                "aac",
-                "-shortest",
-                str(input_path),
-            ],
-            check=True,
-            capture_output=True,
-        )
-
-        clip = _TestClip(asset_id="asset-1", duration=1.0)
-        asset_path_map = {"asset-1": input_path}
-
-        duration, file_size = _render_with_legacy_engine(
-            task_id="test-task",
-            virtual_clips=[clip],
-            asset_path_map=asset_path_map,
-            work_dir=tmp_path,
-            output_path=output_path,
-        )
-
-        assert output_path.exists()
-        assert file_size > 0
-        assert duration > 0
-
-        # 旧引擎保持原帧率（30fps），不做 fps 归一化
-        info = probe_video_info(str(output_path))
-        assert abs(info.get("fps", 0) - 30.0) < 0.5
-        assert info.get("width") == 1280
-        assert info.get("height") == 720
-
-
-def test_legacy_engine_two_clips_concat_duration():
-    """多 clip 场景：concat 后时长为两片段之和。"""
-    import subprocess
-    import tempfile
-
-    from apps.worker.worker_app.tasks.generation import _render_with_legacy_engine
-
-    with tempfile.TemporaryDirectory() as tmpdir:
-        tmp_path = Path(tmpdir)
-        input1 = tmp_path / "input1.mp4"
-        input2 = tmp_path / "input2.mp4"
-        output_path = tmp_path / "output.mp4"
-
-        for idx, inp in enumerate([input1, input2]):
-            color = "red" if idx == 0 else "blue"
-            subprocess.run(
-                [
-                    "ffmpeg",
-                    "-y",
-                    "-f",
-                    "lavfi",
-                    "-i",
-                    f"color=c={color}:s=640x360:d=1:r=30",
-                    "-f",
-                    "lavfi",
-                    "-i",
-                    "anullsrc=r=44100:cl=stereo:d=1",
-                    "-c:v",
-                    "libx264",
-                    "-pix_fmt",
-                    "yuv420p",
-                    "-c:a",
-                    "aac",
-                    "-shortest",
-                    str(inp),
-                ],
-                check=True,
-                capture_output=True,
-            )
-
-        clip1 = _TestClip(asset_id="asset-1", duration=1.0, clip_type="main", order=0)
-        clip2 = _TestClip(asset_id="asset-2", duration=1.0, clip_type="main", order=1)
-        asset_path_map = {"asset-1": input1, "asset-2": input2}
-
-        duration, file_size = _render_with_legacy_engine(
-            task_id="test-task",
-            virtual_clips=[clip1, clip2],
-            asset_path_map=asset_path_map,
-            work_dir=tmp_path,
-            output_path=output_path,
-        )
-
-        assert output_path.exists()
-        assert file_size > 0
-        assert abs(duration - 2.0) < 0.2
-
-
-def test_legacy_engine_broll_mode_supported():
-    """b_roll 类型的 clip 也被正确识别为主图层并渲染。"""
-    import subprocess
-    import tempfile
-
-    from apps.worker.worker_app.tasks.generation import _render_with_legacy_engine
-
-    with tempfile.TemporaryDirectory() as tmpdir:
-        tmp_path = Path(tmpdir)
-        input_path = tmp_path / "input.mp4"
-        output_path = tmp_path / "output.mp4"
-
-        subprocess.run(
-            [
-                "ffmpeg",
-                "-y",
-                "-f",
-                "lavfi",
-                "-i",
-                "color=c=green:s=640x360:d=1:r=30",
-                "-f",
-                "lavfi",
-                "-i",
-                "anullsrc=r=44100:cl=stereo:d=1",
-                "-c:v",
-                "libx264",
-                "-pix_fmt",
-                "yuv420p",
-                "-c:a",
-                "aac",
-                "-shortest",
-                str(input_path),
-            ],
-            check=True,
-            capture_output=True,
-        )
-
-        clip = _TestClip(
-            asset_id="asset-1",
-            duration=1.0,
-            clip_type="main",
-            config={"role": "b_roll"},
-        )
-        asset_path_map = {"asset-1": input_path}
-
-        duration, file_size = _render_with_legacy_engine(
-            task_id="test-task",
-            virtual_clips=[clip],
-            asset_path_map=asset_path_map,
-            work_dir=tmp_path,
-            output_path=output_path,
-        )
-
-        assert output_path.exists()
-        assert file_size > 0
-        assert duration > 0

tests/unit/test_generation_logging.py

@@ -17,11 +17,18 @@ from __future__ import annotations
 import json
 import sys
 from pathlib import Path
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "worker"))
 
+# ── 预注入 mock 模块，防止 worker_app.db 触发真实数据库连接 ──
+_mock_db_module = MagicMock()
+_mock_db_module.SessionLocal = MagicMock()
+sys.modules.setdefault("worker_app.db", _mock_db_module)
+if "worker_app" in sys.modules:
+    sys.modules["worker_app"].db = _mock_db_module
+
 from app.schemas.generation_task import GenerationTaskResponse
 
 from packages.domain.generation_task import GenerationTask, GenerationTaskStatus

tests/unit/test_generation_p3_optimizations.py

@@ -17,6 +17,15 @@ import pytest
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "worker"))
 
+# ── 预注入 mock 模块，防止 worker_app.db 触发真实数据库连接 ──
+# worker_app.db 在模块级别调用 ensure_database_exists() 尝试连接 PostgreSQL，
+# 增量测试单独跑这些文件时会失败。与 test_voice_clone_task.py 同理。
+_mock_db_module = MagicMock()
+_mock_db_module.SessionLocal = MagicMock()
+sys.modules.setdefault("worker_app.db", _mock_db_module)
+if "worker_app" in sys.modules:
+    sys.modules["worker_app"].db = _mock_db_module
+
 
 # ── P3-3: _verify_url_accessible 重试 ───────────────────────────────────────
 

tests/unit/test_render_adapter.py

@@ -1151,3 +1151,213 @@ class TestRenderPlanWithBgmAsr:
         assert "c_bad" in result.failed_clip_ids
         assert len(result.rendered_clip_ids) == 2
         assert len(result.failed_clip_ids) == 1
+
+
+# ── render_from_memory 测试 ──────────────────────────────────────────────────
+
+
+class TestRenderFromMemory:
+    """render_from_memory 内存模式渲染测试。"""
+
+    @patch("video_processing.render_adapter.upload_to_oss")
+    @patch("video_processing.render_adapter.UnifiedRenderService")
+    def test_successful_render(self, mock_render_cls, mock_upload, tmp_path):
+        """内存模式渲染成功。"""
+        mock_render = MagicMock()
+        mock_render.render.return_value = MagicMock(
+            output_path=tmp_path / "out.mp4",
+            duration=10.0,
+            file_size=1024,
+            width=1280,
+            height=720,
+        )
+        mock_render_cls.return_value = mock_render
+        mock_upload.return_value = "https://oss.example.com/out.mp4"
+
+        plan = FakePlan(id="mem_plan_001", config={"bgm": {"enabled": False}})
+        clips = [
+            _make_clip("c1", order=0, duration=5.0),
+            _make_clip("c2", order=1, duration=5.0),
+        ]
+        asset_path_map = {
+            "asset_c1.mp4": tmp_path / "c1.mp4",
+            "asset_c2.mp4": tmp_path / "c2.mp4",
+        }
+        # 创建假文件
+        for p in asset_path_map.values():
+            p.write_bytes(b"fake")
+
+        adapter, _, _ = _make_adapter()
+
+        result = adapter.render_from_memory(
+            plan=plan,
+            clips=clips,
+            asset_path_map=asset_path_map,
+            plan_id="mem_plan_001",
+            work_dir=tmp_path / "work",
+        )
+
+        assert result.success
+        assert result.duration == 10.0
+        assert result.file_size == 1024
+        assert result.width == 1280
+        assert result.height == 720
+        assert result.clip_count == 2
+        assert len(result.rendered_clip_ids) == 2
+        assert len(result.failed_clip_ids) == 0
+
+    @patch("video_processing.render_adapter.upload_to_oss")
+    @patch("video_processing.render_adapter.UnifiedRenderService")
+    def test_empty_clips_returns_failure(self, mock_render_cls, mock_upload, tmp_path):
+        """clips 为空时返回失败。"""
+        plan = FakePlan(id="mem_empty")
+        adapter, _, _ = _make_adapter()
+
+        result = adapter.render_from_memory(
+            plan=plan,
+            clips=[],
+            asset_path_map={},
+            plan_id="mem_empty",
+            work_dir=tmp_path / "work",
+        )
+
+        assert not result.success
+        assert "没有可渲染的片段" in result.error_message
+        mock_render_cls.assert_not_called()
+
+    @patch("video_processing.render_adapter.upload_to_oss")
+    @patch("video_processing.render_adapter.UnifiedRenderService")
+    def test_empty_asset_map_returns_failure(self, mock_render_cls, mock_upload, tmp_path):
+        """asset_path_map 为空时返回失败。"""
+        plan = FakePlan(id="mem_no_assets")
+        clips = [_make_clip("c1", order=0, duration=5.0)]
+        adapter, _, _ = _make_adapter()
+
+        result = adapter.render_from_memory(
+            plan=plan,
+            clips=clips,
+            asset_path_map={},
+            plan_id="mem_no_assets",
+            work_dir=tmp_path / "work",
+        )
+
+        assert not result.success
+        assert "素材路径映射为空" in result.error_message
+        mock_render_cls.assert_not_called()
+
+    @patch("video_processing.render_adapter.upload_to_oss")
+    @patch("video_processing.render_adapter.UnifiedRenderService")
+    def test_bgm_prepared_for_memory_mode(self, mock_render_cls, mock_upload, tmp_path):
+        """内存模式下 BGM 配置也会被正确处理。"""
+        mock_render = MagicMock()
+        mock_render.render.return_value = MagicMock(
+            output_path=tmp_path / "out.mp4",
+            duration=5.0,
+            file_size=512,
+            width=1280,
+            height=720,
+        )
+        mock_render_cls.return_value = mock_render
+        mock_upload.return_value = "https://oss.example.com/out.mp4"
+
+        plan = FakePlan(
+            id="mem_bgm",
+            config={
+                "bgm": {
+                    "enabled": True,
+                    "preset_id": "preset_001",
+                }
+            },
+        )
+        clips = [_make_clip("c1", order=0, duration=5.0)]
+        asset_path_map = {"asset_c1.mp4": tmp_path / "c1.mp4"}
+        asset_path_map["asset_c1.mp4"].write_bytes(b"fake")
+
+        adapter, _, _ = _make_adapter()
+
+        # mock _prepare_bgm 返回一个假的 bgm 路径
+        fake_bgm_path = tmp_path / "bgm.mp3"
+        fake_bgm_path.write_bytes(b"fake bgm")
+        with patch.object(adapter, "_prepare_bgm", return_value=str(fake_bgm_path)):
+            result = adapter.render_from_memory(
+                plan=plan,
+                clips=clips,
+                asset_path_map=asset_path_map,
+                plan_id="mem_bgm",
+                work_dir=tmp_path / "work",
+            )
+
+        assert result.success
+        call_kwargs = mock_render_cls.call_args
+        assert call_kwargs.kwargs["bgm_path"] == str(fake_bgm_path)
+
+    @patch("video_processing.render_adapter.upload_to_oss")
+    @patch("video_processing.render_adapter.UnifiedRenderService")
+    def test_resolution_from_config_memory_mode(self, mock_render_cls, mock_upload, tmp_path):
+        """内存模式下从 plan.config.export.resolution 读取分辨率。"""
+        mock_render = MagicMock()
+        mock_render.render.return_value = MagicMock(
+            output_path=tmp_path / "out.mp4",
+            duration=5.0,
+            file_size=512,
+            width=720,
+            height=1280,
+        )
+        mock_render_cls.return_value = mock_render
+        mock_upload.return_value = "https://oss.example.com/out.mp4"
+
+        plan = FakePlan(
+            id="mem_res",
+            config={"export": {"resolution": "720x1280"}},
+        )
+        clips = [_make_clip("c1", order=0, duration=5.0)]
+        asset_path_map = {"asset_c1.mp4": tmp_path / "c1.mp4"}
+        asset_path_map["asset_c1.mp4"].write_bytes(b"fake")
+
+        adapter, _, _ = _make_adapter()
+
+        result = adapter.render_from_memory(
+            plan=plan,
+            clips=clips,
+            asset_path_map=asset_path_map,
+            plan_id="mem_res",
+            work_dir=tmp_path / "work",
+        )
+
+        assert result.success
+        call_kwargs = mock_render_cls.call_args
+        assert call_kwargs.kwargs["output_width"] == 720
+        assert call_kwargs.kwargs["output_height"] == 1280
+
+    @patch("video_processing.render_adapter.upload_to_oss")
+    @patch("video_processing.render_adapter.UnifiedRenderService")
+    def test_ffmpeg_error_captured_memory_mode(self, mock_render_cls, mock_upload, tmp_path):
+        """内存模式下 FFmpeg 错误也会被正确捕获。"""
+        import subprocess
+
+        mock_render = MagicMock()
+        mock_render.render.side_effect = subprocess.CalledProcessError(
+            returncode=1,
+            cmd=["ffmpeg", "-i", "input.mp4", "output.mp4"],
+            stderr="test error output",
+        )
+        mock_render_cls.return_value = mock_render
+
+        plan = FakePlan(id="mem_err")
+        clips = [_make_clip("c1", order=0, duration=5.0)]
+        asset_path_map = {"asset_c1.mp4": tmp_path / "c1.mp4"}
+        asset_path_map["asset_c1.mp4"].write_bytes(b"fake")
+
+        adapter, _, _ = _make_adapter()
+
+        result = adapter.render_from_memory(
+            plan=plan,
+            clips=clips,
+            asset_path_map=asset_path_map,
+            plan_id="mem_err",
+            work_dir=tmp_path / "work",
+        )
+
+        assert not result.success
+        assert "FFmpeg渲染失败" in result.error_message
+        assert "test error output" in result.error_detail

tests/unit/test_unified_render_service.py

@@ -47,6 +47,7 @@ class FakeClip:
     transition_effect: str = "cut"
     transition_duration: float = 0.0
     status: str = "ready"
+    playback_speed: float = 1.0
     config: dict[str, Any] = field(default_factory=dict)
 
 
@@ -68,6 +69,7 @@ def _make_clip(
     transition_effect: str = "cut",
     transition_duration: float = 0.0,
     config: dict[str, Any] | None = None,
+    playback_speed: float = 1.0,
 ) -> FakeClip:
     return FakeClip(
         id=clip_id,
@@ -78,6 +80,7 @@ def _make_clip(
         transition_effect=transition_effect,
         transition_duration=transition_duration,
         config=config or {},
+        playback_speed=playback_speed,
     )
 
 
@@ -1925,6 +1928,88 @@ class TestConcatNormalizeVideoResolution:
         vf_value = cmd[vf_idx + 1]
         assert "crop=" in vf_value, "background 层应有 crop 滤镜"
 
+    def test_pass_through_speed_up_correct_duration(self):
+        """直通模式加速（speed=2x）：视频+音频均调速，-t 时长为原始的 1/2。"""
+        clips = [_make_clip("c1", "main", order=0, duration=10.0, playback_speed=2.0)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        svc = _make_service(clips, asset_paths)
+
+        with (
+            _patch_path_exists(),
+            patch("video_processing.unified_render_service.probe_duration", return_value=10.0),
+            patch("video_processing.unified_render_service.run_ffmpeg") as mock_run,
+        ):
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            svc._render_pass_through(layers, Path("/tmp/out.mp4"))
+
+        assert mock_run.called
+        cmd = mock_run.call_args[0][0]
+        cmd_str = " ".join(cmd)
+
+        # 视频调速：setpts=PTS/2.0
+        assert "setpts=PTS/2.0" in cmd_str, "加速场景应有 setpts=PTS/speed 滤镜"
+
+        # 音频调速：atempo
+        assert "atempo" in cmd_str, "加速场景应有 atempo 音频调速滤镜"
+
+        # 输出时长应为原始 / speed = 10 / 2 = 5 秒
+        t_idx = cmd.index("-t")
+        t_value = float(cmd[t_idx + 1])
+        assert abs(t_value - 5.0) < 0.01, f"加速后 -t 时长应为 5.0s，实际 {t_value}s"
+
+    def test_pass_through_slow_down_correct_duration(self):
+        """直通模式减速（speed=0.5x）：视频+音频均调速，-t 时长为原始的 2 倍（不被截断）。"""
+        clips = [_make_clip("c1", "main", order=0, duration=10.0, playback_speed=0.5)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        svc = _make_service(clips, asset_paths)
+
+        with (
+            _patch_path_exists(),
+            patch("video_processing.unified_render_service.probe_duration", return_value=10.0),
+            patch("video_processing.unified_render_service.run_ffmpeg") as mock_run,
+        ):
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            svc._render_pass_through(layers, Path("/tmp/out.mp4"))
+
+        assert mock_run.called
+        cmd = mock_run.call_args[0][0]
+        cmd_str = " ".join(cmd)
+
+        # 视频调速：setpts=PTS/0.5
+        assert "setpts=PTS/0.5" in cmd_str, "减速场景应有 setpts=PTS/speed 滤镜"
+
+        # 音频调速：atempo
+        assert "atempo" in cmd_str, "减速场景应有 atempo 音频调速滤镜"
+
+        # 输出时长应为原始 / speed = 10 / 0.5 = 20 秒（减速后视频变长，不应被截断）
+        t_idx = cmd.index("-t")
+        t_value = float(cmd[t_idx + 1])
+        assert abs(t_value - 20.0) < 0.01, f"减速后 -t 时长应为 20.0s，实际 {t_value}s"
+
+    def test_pass_through_speed_with_video_duration_cap(self):
+        """直通模式调速 + video_duration 截断：取调速后时长与 video_duration 的较小值。"""
+        clips = [_make_clip("c1", "main", order=0, duration=10.0, playback_speed=2.0)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        svc = _make_service(clips, asset_paths)
+
+        with (
+            _patch_path_exists(),
+            patch("video_processing.unified_render_service.probe_duration", return_value=10.0),
+            patch("video_processing.unified_render_service.run_ffmpeg") as mock_run,
+        ):
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            # video_duration=3.0 < 调速后时长 5.0，应取 3.0
+            svc._render_pass_through(layers, Path("/tmp/out.mp4"), video_duration=3.0)
+
+        assert mock_run.called
+        cmd = mock_run.call_args[0][0]
+        t_idx = cmd.index("-t")
+        t_value = float(cmd[t_idx + 1])
+        assert abs(t_value - 3.0) < 0.01, f"video_duration 更小时应取 video_duration，实际 {t_value}s"
+
 
 class TestConcatNormalizeVideoFps:
     """视频帧率归一化：fps 滤镜统一到目标 fps。
@@ -2262,3 +2347,409 @@ class TestConcatNormalizeFourItemsComplete:
         cmd = mock_run.call_args[0][0]
         assert "aac" in cmd
         assert "concat=n=3:v=0:a=1" in " ".join(cmd)
+
+
+class TestVoiceoverTopLevelConfigBridge:
+    """顶层 voice_id + custom_text 桥接到 tts 配置的兼容性测试.
+
+    前端一键生成页面传 config.voice_id + config.custom_text（顶层字段），
+    统一渲染引擎从 config.tts 读取。桥接逻辑确保两条路径都能工作。
+    """
+
+    def test_top_level_voice_id_with_text_triggers_tts(self):
+        """顶层 voice_id + custom_text 能触发 TTS 配音（桥接生效）。"""
+        from unittest.mock import MagicMock
+
+        clips = [_make_clip("c1", "main", order=0, duration=5.0)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        plan = FakePlan(
+            id="plan_tts_001",
+            config={
+                "voice_id": "longxiaoxia_v3",
+                "custom_text": "大家好，欢迎来到我的频道",
+            },
+        )
+        svc = UnifiedRenderService(
+            plan=plan,
+            clips=clips,
+            asset_path_map=asset_paths,
+            work_dir=Path("/tmp/test_tts"),
+        )
+
+        mock_seg = MagicMock()
+        mock_seg.audio_path = Path("/tmp/test_tts/tts/voiceover_full.wav")
+        mock_seg.start_time = 0.0
+        mock_seg.duration = 3.0
+        mock_result = MagicMock()
+        mock_result.success = True
+        mock_result.segments = [mock_seg]
+        mock_result.total_duration = 3.0
+
+        with (
+            _patch_path_exists(),
+            patch("video_processing.unified_render_service.probe_duration", return_value=5.0),
+            patch(
+                "video_processing.tts_engine.TtsEngine.generate_full_voiceover",
+                return_value=mock_result,
+            ),
+        ):
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            result = svc._maybe_add_voiceover_layer(layers, video_duration=5.0)
+
+        assert result is True, "顶层 voice_id + custom_text 应触发 TTS 配音"
+        # 应有 audio 图层
+        audio_layer = next((layer for layer in layers if layer.role == "audio"), None)
+        assert audio_layer is not None, "应添加 audio 图层"
+        assert len(audio_layer.clips) == 1, "应有 1 个配音片段"
+
+    def test_tts_config_takes_priority(self):
+        """config.tts.enabled 已配置时，以 tts 配置为准，不触发桥接。"""
+        clips = [_make_clip("c1", "main", order=0, duration=5.0)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        # tts.enabled=True 但 text 为空（应失败），顶层有 text
+        plan = FakePlan(
+            id="plan_tts_002",
+            config={
+                "voice_id": "longxiaoxia_v3",
+                "custom_text": "顶层文本不生效",
+                "tts": {
+                    "enabled": True,
+                    "voice_id": "longxiaochun_v3",
+                    "text": "",  # tts 配置里 text 为空
+                },
+            },
+        )
+        svc = UnifiedRenderService(
+            plan=plan,
+            clips=clips,
+            asset_path_map=asset_paths,
+            work_dir=Path("/tmp/test_tts"),
+        )
+
+        with (
+            _patch_path_exists(),
+            patch("video_processing.unified_render_service.probe_duration", return_value=5.0),
+        ):
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            result = svc._maybe_add_voiceover_layer(layers, video_duration=5.0)
+
+        # tts.enabled=True 但 text 为空 → 生成失败 → 返回 False
+        # 关键是不触发桥接（不会用顶层的 custom_text）
+        assert result is False
+
+    def test_top_level_voice_id_without_text_no_trigger(self):
+        """只有 voice_id 没有 custom_text 不触发 TTS 配音。"""
+        clips = [_make_clip("c1", "main", order=0, duration=5.0)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        plan = FakePlan(
+            id="plan_tts_003",
+            config={"voice_id": "longxiaoxia_v3", "custom_text": ""},
+        )
+        svc = UnifiedRenderService(
+            plan=plan,
+            clips=clips,
+            asset_path_map=asset_paths,
+            work_dir=Path("/tmp/test_tts"),
+        )
+
+        with (
+            _patch_path_exists(),
+            patch("video_processing.unified_render_service.probe_duration", return_value=5.0),
+        ):
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            result = svc._maybe_add_voiceover_layer(layers, video_duration=5.0)
+
+        assert result is False
+
+    def test_no_voice_config_no_trigger(self):
+        """没有 voice_id 也没有 tts 配置时，不触发配音。"""
+        clips = [_make_clip("c1", "main", order=0, duration=5.0)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        svc = _make_service(clips, asset_paths)
+
+        with (
+            _patch_path_exists(),
+            patch("video_processing.unified_render_service.probe_duration", return_value=5.0),
+        ):
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            result = svc._maybe_add_voiceover_layer(layers, video_duration=5.0)
+
+        assert result is False
+        # 没有 audio 图层
+        assert not any(layer.role == "audio" for layer in layers)
+
+
+class TestVoiceoverSubtitleAlign:
+    """预设配音 + 自动字幕 → 字幕对齐 TTS 配音.
+
+    前端预设配音模式只传 voice_id，不传 custom_text。
+    配合自动字幕时，用 ASR 识别结果生成逐字幕配音。
+    """
+
+    def _make_mock_timeline(self, segments_data):
+        """构造模拟的 SubtitleTimeline."""
+        from packages.domain.subtitle import SubtitleSegment, SubtitleTimeline
+
+        segments = [SubtitleSegment(text=s["text"], start=s["start"], end=s["end"]) for s in segments_data]
+        return SubtitleTimeline(segments=segments, total_duration=10.0)
+
+    def test_preset_voice_with_auto_subtitle_triggers_tts(self):
+        """预设配音 + 自动字幕 → 触发字幕对齐 TTS 配音。"""
+        from unittest.mock import MagicMock, PropertyMock
+
+        clips = [_make_clip("c1", "main", order=0, duration=10.0)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        plan = FakePlan(
+            id="plan_sub_001",
+            config={
+                "voice_id": "longxiaoxia_v3",
+                "subtitle": {
+                    "enabled": True,
+                    "auto_generated": True,
+                },
+            },
+        )
+
+        mock_asr = MagicMock()
+        svc = UnifiedRenderService(
+            plan=plan,
+            clips=clips,
+            asset_path_map=asset_paths,
+            work_dir=Path("/tmp/test_tts_sub"),
+            asr_service=mock_asr,
+        )
+
+        # 模拟 ASR 结果（通过缓存注入）
+        svc._asr_timeline_cache = self._make_mock_timeline(
+            [
+                {"text": "大家好欢迎来到我的频道", "start": 0.0, "end": 2.5},
+                {"text": "今天给大家分享一个小技巧", "start": 2.5, "end": 5.0},
+                {"text": "记得点赞关注哦", "start": 5.0, "end": 7.0},
+            ]
+        )
+        svc._asr_timeline_cached = True
+
+        with _patch_path_exists():
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            with patch(
+                "video_processing.tts_engine.TtsEngine.generate_subtitle_voiceover",
+            ) as mock_sub_vo:
+                # 构造模拟返回
+                mock_seg1 = MagicMock()
+                mock_seg1.audio_path = Path("/tmp/tts/seg_000.wav")
+                mock_seg1.start_time = 0.0
+                mock_seg1.duration = 2.5
+                mock_seg2 = MagicMock()
+                mock_seg2.audio_path = Path("/tmp/tts/seg_001.wav")
+                mock_seg2.start_time = 2.5
+                mock_seg2.duration = 2.5
+                mock_result = MagicMock()
+                mock_result.success = True
+                mock_result.segments = [mock_seg1, mock_seg2]
+                mock_result.total_duration = 5.0
+                mock_sub_vo.return_value = mock_result
+
+                result = svc._maybe_add_voiceover_layer(layers, video_duration=10.0)
+
+        assert result is True, "预设配音+自动字幕应触发 TTS 配音"
+        # 应调用字幕对齐模式
+        mock_sub_vo.assert_called_once()
+        # 应有 audio 图层
+        audio_layer = next((layer for layer in layers if layer.role == "audio"), None)
+        assert audio_layer is not None
+        assert len(audio_layer.clips) == 2  # 2 个字幕对应 2 段配音
+
+    def test_preset_voice_without_auto_subtitle_no_trigger(self):
+        """只有 voice_id 没有自动字幕 → 不触发配音。"""
+        clips = [_make_clip("c1", "main", order=0, duration=10.0)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        plan = FakePlan(
+            id="plan_sub_002",
+            config={
+                "voice_id": "longxiaoxia_v3",
+                "subtitle": {"enabled": True, "auto_generated": False},
+            },
+        )
+        mock_asr = MagicMock()
+        svc = UnifiedRenderService(
+            plan=plan,
+            clips=clips,
+            asset_path_map=asset_paths,
+            work_dir=Path("/tmp/test_tts_sub"),
+            asr_service=mock_asr,
+        )
+
+        with _patch_path_exists():
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            result = svc._maybe_add_voiceover_layer(layers, video_duration=10.0)
+
+        assert result is False
+        assert not any(layer.role == "audio" for layer in layers)
+
+    def test_preset_voice_no_asr_service_no_trigger(self):
+        """有 voice_id + 自动字幕但没有 ASR 服务 → 不触发。"""
+        clips = [_make_clip("c1", "main", order=0, duration=10.0)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        plan = FakePlan(
+            id="plan_sub_003",
+            config={
+                "voice_id": "longxiaoxia_v3",
+                "subtitle": {"enabled": True, "auto_generated": True},
+            },
+        )
+        # 不传 asr_service
+        svc = UnifiedRenderService(
+            plan=plan,
+            clips=clips,
+            asset_path_map=asset_paths,
+            work_dir=Path("/tmp/test_tts_sub"),
+        )
+
+        with _patch_path_exists():
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            result = svc._maybe_add_voiceover_layer(layers, video_duration=10.0)
+
+        assert result is False
+
+    def test_preset_voice_asr_empty_segments_skip(self):
+        """ASR 无识别结果 → 跳过配音，不报错。"""
+        clips = [_make_clip("c1", "main", order=0, duration=10.0)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        plan = FakePlan(
+            id="plan_sub_004",
+            config={
+                "voice_id": "longxiaoxia_v3",
+                "subtitle": {"enabled": True, "auto_generated": True},
+            },
+        )
+        mock_asr = MagicMock()
+        svc = UnifiedRenderService(
+            plan=plan,
+            clips=clips,
+            asset_path_map=asset_paths,
+            work_dir=Path("/tmp/test_tts_sub"),
+            asr_service=mock_asr,
+        )
+
+        # ASR 返回空结果
+        svc._asr_timeline_cache = self._make_mock_timeline([])
+        svc._asr_timeline_cached = True
+
+        with _patch_path_exists():
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            # 不抛异常，返回 False 即可
+            result = svc._maybe_add_voiceover_layer(layers, video_duration=10.0)
+
+        assert result is False
+
+    def test_asr_cache_reuse_between_subtitle_and_voiceover(self):
+        """ASR 结果缓存：字幕和配音共用一次 ASR 调用。"""
+        clips = [_make_clip("c1", "main", order=0, duration=10.0)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        plan = FakePlan(
+            id="plan_sub_005",
+            config={
+                "voice_id": "longxiaoxia_v3",
+                "subtitle": {"enabled": True, "auto_generated": True},
+            },
+        )
+        mock_asr = MagicMock()
+        svc = UnifiedRenderService(
+            plan=plan,
+            clips=clips,
+            asset_path_map=asset_paths,
+            work_dir=Path("/tmp/test_tts_sub"),
+            asr_service=mock_asr,
+        )
+
+        # 先模拟调用过一次 ASR（比如字幕模块先调用）
+        svc._asr_timeline_cache = self._make_mock_timeline(
+            [
+                {"text": "测试字幕", "start": 0.0, "end": 2.0},
+            ]
+        )
+        svc._asr_timeline_cached = True
+
+        with _patch_path_exists():
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            with patch(
+                "video_processing.tts_engine.TtsEngine.generate_subtitle_voiceover",
+            ) as mock_sub_vo:
+                mock_seg = MagicMock()
+                mock_seg.audio_path = Path("/tmp/tts/seg_000.wav")
+                mock_seg.start_time = 0.0
+                mock_seg.duration = 2.0
+                mock_result = MagicMock()
+                mock_result.success = True
+                mock_result.segments = [mock_seg]
+                mock_result.total_duration = 2.0
+                mock_sub_vo.return_value = mock_result
+
+                result = svc._maybe_add_voiceover_layer(layers, video_duration=10.0)
+
+        assert result is True
+        # ASR 服务不应被再次调用（使用缓存）
+        mock_asr.transcribe.assert_not_called()
+
+    def test_tts_config_align_mode_subtitle_also_works(self):
+        """标准 tts 配置 + align_mode=subtitle 也走字幕对齐模式。"""
+        clips = [_make_clip("c1", "main", order=0, duration=10.0)]
+        asset_paths = {"asset_c1.mp4": Path("/tmp/asset_c1.mp4")}
+        plan = FakePlan(
+            id="plan_sub_006",
+            config={
+                "tts": {
+                    "enabled": True,
+                    "voice_id": "longxiaoxia_v3",
+                    "text": "",
+                    "align_mode": "subtitle",
+                },
+                "subtitle": {"enabled": True, "auto_generated": True},
+            },
+        )
+        mock_asr = MagicMock()
+        svc = UnifiedRenderService(
+            plan=plan,
+            clips=clips,
+            asset_path_map=asset_paths,
+            work_dir=Path("/tmp/test_tts_sub"),
+            asr_service=mock_asr,
+        )
+
+        svc._asr_timeline_cache = self._make_mock_timeline(
+            [
+                {"text": "字幕1", "start": 0.0, "end": 3.0},
+                {"text": "字幕2", "start": 3.0, "end": 6.0},
+            ]
+        )
+        svc._asr_timeline_cached = True
+
+        with _patch_path_exists():
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            with patch(
+                "video_processing.tts_engine.TtsEngine.generate_subtitle_voiceover",
+            ) as mock_sub_vo:
+                mock_seg = MagicMock()
+                mock_seg.audio_path = Path("/tmp/tts/seg_000.wav")
+                mock_seg.start_time = 0.0
+                mock_seg.duration = 6.0
+                mock_result = MagicMock()
+                mock_result.success = True
+                mock_result.segments = [mock_seg, mock_seg]
+                mock_result.total_duration = 6.0
+                mock_sub_vo.return_value = mock_result
+
+                result = svc._maybe_add_voiceover_layer(layers, video_duration=10.0)
+
+        assert result is True
+        mock_sub_vo.assert_called_once()