Merge PR #1827: AI数字人v3 完整联调版（TTS直生+smart-cover+前后端冲突解决）(#1827)

4efa71ec 合并时 tests/unit/test_lipsync_routes.py 误取了 develop #1809 版本
（synthesize_speech/route._resolve_voice_id/断言 audio_url 移除），与合并后
v3 #1822 双模式实现不一致，导致 7 个单测失败。改用后端解冲突分支
backend/ai-avatar-merge-1827 (0e994072) 中已适配 v3 的版本：
mock submit_synthesize_task、emotion 兴奋→excited、双模式 audio_url 保留。
本地验证该文件 28 passed、lipsync/avatar/tts 相关 79 passed。

.gitea/workflows/ci-pipeline.yml

@@ -20,6 +20,7 @@ on:
         default: "手动触发 - CI漏触发补跑"
 permissions:
   contents: read
+  pull-requests: read
 concurrency:
   group: ci-pipeline-${{ gitea.ref }}
   cancel-in-progress: true
@@ -88,9 +89,22 @@ jobs:
         GITHUB_TOKEN: ${{ github.token }}
       run: |
         set -eu
+        # 优先用 git diff 判断 PR 改动范围（比 API 稳定）
         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)]")
+        if command -v git >/dev/null 2>&1 && [ -d .git ]; then
+          FILES=$(git diff --name-only origin/develop...HEAD 2>/dev/null || true)
+        fi
+        if [ -z "${FILES:-}" ]; then
+          # fallback 到 API
+          API_URL="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?limit=300"
+          FILES=$(curl -sf -H "Authorization: token ${GITHUB_TOKEN}" "$API_URL" | python3 -c "import sys,json; [print(f['filename']) for f in json.load(sys.stdin)]" 2>/dev/null || true)
+        fi
+        if [ -z "${FILES:-}" ]; then
+          echo "⚠️ 无法获取变更文件列表，保守运行完整 CI"
+          echo "skip_backend=false" >> $GITHUB_OUTPUT
+          echo "skip_frontend=false" >> $GITHUB_OUTPUT
+          exit 0
+        fi
         FRONTEND_COUNT=$(echo "$FILES" | grep -c '^apps/web/' || true)
         BACKEND_COUNT=$(echo "$FILES" | grep -cv '^apps/web/' || true)
         TOTAL=$(echo "$FILES" | grep -cv '^$' || true)

alembic/versions/069_project_is_default_idempotent.py

@@ -0,0 +1,72 @@
+"""Projects is_default + partial unique index for idempotent default project (Issue #1775)
+
+Revision ID: 069_project_is_default
+Revises: 068_user_profile_completed
+Create Date: 2026-09-08
+
+背景：
+小程序端 getOrCreateDefaultProject 在重试/并发/前端重复调用下，
+仅靠应用层"先查再插"不保证幂等，会给同一用户重复创建默认项目。
+
+改动：
+1. projects 表新增 is_default 布尔列（默认 false）
+2. 部分唯一索引 uq_projects_owner_default：(owner_user_id) WHERE is_default = true
+   —— 保证每个用户至多一个默认项目
+3. 存量数据回填：把名为"默认项目"的存量项目按创建时间最早者标记为 is_default=true
+   （只标记不删除；存量重复项目的清理另行确认后单独执行）
+
+注意：部分唯一索引依赖 PostgreSQL，不支持 downgrade 到其他方言。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "069_project_is_default"
+down_revision = "068_user_profile_completed"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 1. 新增 is_default 列
+    op.add_column(
+        "projects",
+        sa.Column(
+            "is_default",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("false"),
+        ),
+    )
+
+    # 2. 存量回填：每个拥有"默认项目"的用户，只把最早创建的那一个标记为默认。
+    #    用 ROW_NUMBER() 取每组第一条；非"默认项目"命名的项目不标记（保守，不动用户自建项目）。
+    op.execute("""
+        UPDATE projects p
+        SET is_default = true
+        WHERE p.id IN (
+            SELECT id FROM (
+                SELECT id,
+                       ROW_NUMBER() OVER (
+                           PARTITION BY owner_user_id
+                           ORDER BY created_at ASC, id ASC
+                       ) AS rn
+                FROM projects
+                WHERE name = '默认项目'
+            ) t
+            WHERE t.rn = 1
+        )
+        """)
+
+    # 3. 部分唯一索引：每用户至多一个默认项目（只约束 is_default = true 的行）
+    op.execute("""
+        CREATE UNIQUE INDEX uq_projects_owner_default
+        ON projects (owner_user_id)
+        WHERE is_default = true
+        """)
+
+
+def downgrade() -> None:
+    op.execute("DROP INDEX IF EXISTS uq_projects_owner_default")
+    op.drop_column("projects", "is_default")

alembic/versions/070_add_scripts_table.py

@@ -0,0 +1,48 @@
+"""Add scripts table for oral broadcast script library (Issue #1795)
+
+Revision ID: 070_add_scripts
+Revises: 069_project_is_default
+Create Date: 2026-09-08
+
+新建 scripts 表，支持口播文案 CRUD + 分段存储。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "070_add_scripts"
+down_revision = "069_project_is_default"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "scripts",
+        sa.Column("id", sa.String(36), nullable=False),
+        sa.Column("user_id", sa.String(36), nullable=False),
+        sa.Column("title", sa.String(255), nullable=False),
+        sa.Column("content", sa.Text(), nullable=False, server_default=""),
+        sa.Column("segments", sa.JSON(), nullable=False, server_default="[]"),
+        sa.Column("tags", sa.JSON(), nullable=False, server_default="[]"),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("ix_scripts_user_id", "scripts", ["user_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_scripts_user_id", table_name="scripts")
+    op.drop_table("scripts")

alembic/versions/071_add_lipsync_jobs_table.py

@@ -0,0 +1,47 @@
+"""add lipsync jobs table
+
+Revision ID: 071_add_lipsync_jobs
+Revises: 070_add_scripts
+Create Date: 2026-09-08
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "071_add_lipsync_jobs"
+down_revision = "070_add_scripts"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "lipsync_jobs",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("user_id", sa.String(36), nullable=False, index=True),
+        sa.Column("project_id", sa.String(36), nullable=False, server_default=""),
+        sa.Column("video_url", sa.Text(), nullable=False),
+        sa.Column("audio_url", sa.Text(), nullable=False),
+        sa.Column("enable_video_loop", sa.Boolean(), nullable=False, server_default=sa.text("false")),
+        sa.Column("mediakit_task_id", sa.String(200), nullable=False, server_default="", index=True),
+        sa.Column("status", sa.String(20), nullable=False, server_default="pending", index=True),
+        sa.Column("output_video_url", sa.Text(), nullable=False, server_default=""),
+        sa.Column("output_duration", sa.Float(), nullable=False, server_default=sa.text("0.0")),
+        sa.Column("error_message", sa.Text(), nullable=False, server_default=""),
+        sa.Column("error_code", sa.String(100), nullable=False, server_default=""),
+        sa.Column("submitted_at", sa.DateTime(), nullable=True),
+        sa.Column("completed_at", sa.DateTime(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+    )
+    # 复合索引：用户 + 状态（列表查询常用）
+    op.create_index("ix_lipsync_jobs_user_status", "lipsync_jobs", ["user_id", "status"])
+    # 项目 + 用户（项目维度查询）
+    op.create_index("ix_lipsync_jobs_project_user", "lipsync_jobs", ["project_id", "user_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_lipsync_jobs_project_user", table_name="lipsync_jobs")
+    op.drop_index("ix_lipsync_jobs_user_status", table_name="lipsync_jobs")
+    op.drop_table("lipsync_jobs")

alembic/versions/072_add_ai_avatar_render_jobs_table.py

@@ -0,0 +1,48 @@
+"""add ai avatar render jobs table
+
+Revision ID: 072_add_ai_avatar_render
+Revises: 071_add_lipsync_jobs
+Create Date: 2026-09-09
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "072_add_ai_avatar_render"
+down_revision = "071_add_lipsync_jobs"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "ai_avatar_render_jobs",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("user_id", sa.String(36), nullable=False, index=True),
+        sa.Column("project_id", sa.String(36), nullable=False, server_default=""),
+        sa.Column("lipsync_job_id", sa.String(36), nullable=False),
+        sa.Column("script_id", sa.String(36), nullable=False),
+        sa.Column("b_roll_segments", sa.JSON(), nullable=False, server_default="[]"),
+        sa.Column("title_config", sa.JSON(), nullable=False, server_default="{}"),
+        sa.Column("cover_config", sa.JSON(), nullable=False, server_default="{}"),
+        sa.Column("status", sa.String(20), nullable=False, server_default="pending", index=True),
+        sa.Column("progress", sa.Integer(), nullable=False, server_default=sa.text("0")),
+        sa.Column("output_video_url", sa.Text(), nullable=False, server_default=""),
+        sa.Column("output_cover_url", sa.Text(), nullable=False, server_default=""),
+        sa.Column("output_duration", sa.Float(), nullable=False, server_default=sa.text("0.0")),
+        sa.Column("error_message", sa.Text(), nullable=False, server_default=""),
+        sa.Column("submitted_at", sa.DateTime(), nullable=True),
+        sa.Column("started_at", sa.DateTime(), nullable=True),
+        sa.Column("completed_at", sa.DateTime(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+    )
+    op.create_index("ix_ai_avatar_render_user_status", "ai_avatar_render_jobs", ["user_id", "status"])
+    op.create_index("ix_ai_avatar_render_project_user", "ai_avatar_render_jobs", ["project_id", "user_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_ai_avatar_render_project_user", table_name="ai_avatar_render_jobs")
+    op.drop_index("ix_ai_avatar_render_user_status", table_name="ai_avatar_render_jobs")
+    op.drop_table("ai_avatar_render_jobs")

alembic/versions/073_add_lipsync_tts_fields.py

@@ -0,0 +1,45 @@
+"""lipsync_jobs 增加 TTS 直生字段（voice_id/script_text/speed/emotion）
+
+Revision ID: 073_add_lipsync_tts_fields
+Revises: 072_add_ai_avatar_render
+Create Date: 2026-09-09
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "073_add_lipsync_tts_fields"
+down_revision = "072_add_ai_avatar_render"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 对口型支持「传音色 + 文案直接生成」：后端内部先 TTS 合成音频再提交对口型
+    op.add_column(
+        "lipsync_jobs",
+        sa.Column("voice_id", sa.String(200), nullable=False, server_default=""),
+    )
+    op.add_column(
+        "lipsync_jobs",
+        sa.Column("script_text", sa.Text(), nullable=False, server_default=""),
+    )
+    op.add_column(
+        "lipsync_jobs",
+        sa.Column("speed", sa.Float(), nullable=False, server_default=sa.text("1.0")),
+    )
+    op.add_column(
+        "lipsync_jobs",
+        sa.Column("emotion", sa.String(20), nullable=False, server_default=""),
+    )
+    # audio_url 改为可空：直生模式下音频由后端 TTS 合成后回填
+    op.alter_column("lipsync_jobs", "audio_url", existing_type=sa.Text(), nullable=True)
+
+
+def downgrade() -> None:
+    op.alter_column("lipsync_jobs", "audio_url", existing_type=sa.Text(), nullable=False)
+    op.drop_column("lipsync_jobs", "emotion")
+    op.drop_column("lipsync_jobs", "speed")
+    op.drop_column("lipsync_jobs", "script_text")
+    op.drop_column("lipsync_jobs", "voice_id")

alembic/versions/074_ai_avatar_render_script_id_optional.py

@@ -0,0 +1,36 @@
+"""ai_avatar_render_jobs.script_id 放宽为可空串（手动文案直生场景不关联文案库）
+
+Revision ID: 074_render_script_id_optional
+Revises: 073_add_lipsync_tts_fields
+Create Date: 2026-09-09
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "074_render_script_id_optional"
+down_revision = "073_add_lipsync_tts_fields"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 列保持 NOT NULL（空串占位），仅应用层允许不传；这里显式补 server_default 防止历史约束歧义
+    with op.batch_alter_table("ai_avatar_render_jobs") as batch:
+        batch.alter_column(
+            "script_id",
+            existing_type=sa.String(length=36),
+            nullable=False,
+            server_default="",
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("ai_avatar_render_jobs") as batch:
+        batch.alter_column(
+            "script_id",
+            existing_type=sa.String(length=36),
+            nullable=False,
+            server_default=None,
+        )

apps/api/app/api/router.py

@@ -1,4 +1,5 @@
 from app.api.routes.ai import router as ai_router
+from app.api.routes.ai_avatar_render import router as ai_avatar_render_router
 from app.api.routes.asset_diagnosis import router as asset_diagnosis_router
 from app.api.routes.asset_libraries import router as asset_libraries_router
 from app.api.routes.assets import router as assets_router
@@ -15,7 +16,9 @@ from app.api.routes.generation_variant_plans import router as generation_variant
 from app.api.routes.health import router as health_check_router
 from app.api.routes.ingest_jobs import router as ingest_jobs_router
 from app.api.routes.internal_render import router as internal_render_router
+from app.api.routes.lipsync import router as lipsync_router
 from app.api.routes.projects import router as projects_router
+from app.api.routes.scripts import router as scripts_router
 from app.api.routes.share import router as share_router
 from app.api.routes.subscription import router as subscription_router
 from app.api.routes.tags import router as tags_router
@@ -38,6 +41,11 @@ api_router.include_router(
     auth_router,
     tags=["Auth"],
 )
+api_router.include_router(
+    lipsync_router,
+    prefix="/lipsync",
+    tags=["Lipsync"],
+)
 api_router.include_router(
     projects_router,
     prefix="/projects",
@@ -171,3 +179,13 @@ api_router.include_router(
     internal_render_router,
     tags=["Internal"],
 )
+api_router.include_router(
+    scripts_router,
+    prefix="/scripts",
+    tags=["ScriptLibrary"],
+)
+api_router.include_router(
+    ai_avatar_render_router,
+    prefix="/ai-avatar/render",
+    tags=["AI Avatar Render"],
+)

apps/api/app/api/routes/ai_avatar_render.py

@@ -0,0 +1,209 @@
+"""AI数字人渲染合成 API 路由 — #1798.
+
+接口：
+  POST   /api/v1/ai-avatar/render              提交渲染任务
+  GET    /api/v1/ai-avatar/render/jobs          任务列表
+  GET    /api/v1/ai-avatar/render/{job_id}      任务详情
+  POST   /api/v1/ai-avatar/render/{job_id}/cancel  取消任务
+  POST   /api/v1/ai-avatar/render/{job_id}/retry   重试失败任务
+"""
+
+from __future__ import annotations
+
+import logging
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session
+from app.schemas.ai_avatar_render import (
+    AiAvatarRenderJobResponse,
+    CreateAiAvatarRenderRequest,
+    SmartCoverRequest,
+    SmartCoverResponse,
+)
+from app.services.ai_avatar_cover_service import generate_smart_cover
+from app.services.ai_avatar_render_service import (
+    AiAvatarRenderError,
+    AiAvatarRenderService,
+)
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.orm import Session
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _get_service(db: Session = Depends(get_db_session)) -> AiAvatarRenderService:
+    return AiAvatarRenderService(db)
+
+
+# ── POST / — 提交渲染任务 ────────────────────────────────────────────────
+
+
+@router.post("", response_model=AiAvatarRenderJobResponse, status_code=201)
+def create_render_job(
+    body: CreateAiAvatarRenderRequest,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    svc: AiAvatarRenderService = Depends(_get_service),
+):
+    """提交 AI 数字人渲染任务.
+
+    将对口型视频 + B-roll 素材 + 标题叠加 + 封面提取合成最终输出视频。
+    """
+    try:
+        job = svc.create_render_job(
+            user_id=current_user.user.id,
+            lipsync_job_id=body.lipsync_job_id,
+            script_id=body.script_id,
+            b_roll_segments=[s.model_dump() for s in body.b_roll_segments],
+            title_config=body.title_config,
+            cover_config=body.cover_config,
+            project_id=body.project_id,
+        )
+    except AiAvatarRenderError as exc:
+        status_map = {
+            "LipsyncJobNotFound": 404,
+            "LipsyncJobNotCompleted": 400,
+            "LipsyncJobNoOutput": 400,
+            "ScriptNotFound": 404,
+        }
+        raise HTTPException(
+            status_code=status_map.get(exc.code, 400),
+            detail={"code": exc.code, "message": str(exc)},
+        ) from exc
+
+    # 异步触发渲染
+    try:
+        from app.tasks.ai_avatar_render import execute_ai_avatar_render
+
+        execute_ai_avatar_render.delay(job.id)
+    except Exception:
+        logger.warning("Celery 任务提交失败，渲染任务已创建但未触发执行: %s", job.id)
+
+    return job
+
+
+# ── GET /jobs — 任务列表 ─────────────────────────────────────────────────
+
+
+@router.get("/jobs", response_model=dict)
+def list_render_jobs(
+    project_id: str = Query("", description="项目 ID 过滤"),
+    status: str = Query("", description="状态过滤"),
+    offset: int = Query(0, ge=0),
+    limit: int = Query(20, ge=1, le=100),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    svc: AiAvatarRenderService = Depends(_get_service),
+):
+    """获取 AI 数字人渲染任务列表."""
+    items, total = svc.list_render_jobs(
+        user_id=current_user.user.id,
+        project_id=project_id,
+        status=status,
+        offset=offset,
+        limit=limit,
+    )
+    return {
+        "items": [AiAvatarRenderJobResponse.model_validate(j) for j in items],
+        "total": total,
+        "offset": offset,
+        "limit": limit,
+    }
+
+
+# ── GET /{job_id} — 任务详情 ─────────────────────────────────────────────
+
+
+@router.get("/{job_id}", response_model=AiAvatarRenderJobResponse)
+def get_render_job(
+    job_id: str,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    svc: AiAvatarRenderService = Depends(_get_service),
+):
+    """获取渲染任务详情."""
+    job = svc.get_render_job(job_id, current_user.user.id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="渲染任务不存在")
+    return job
+
+
+# ── POST /{job_id}/cancel — 取消任务 ─────────────────────────────────────
+
+
+@router.post("/{job_id}/cancel", response_model=AiAvatarRenderJobResponse)
+def cancel_render_job(
+    job_id: str,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    svc: AiAvatarRenderService = Depends(_get_service),
+):
+    """取消渲染任务（仅 pending 状态可取消）."""
+    job = svc.cancel_render_job(job_id, current_user.user.id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="渲染任务不存在")
+    if job.status != "cancelled":
+        raise HTTPException(
+            status_code=400,
+            detail=f"任务状态 {job.status} 不可取消，仅 pending 可取消",
+        )
+    return job
+
+
+# ── POST /{job_id}/retry — 重试失败任务 ──────────────────────────────────
+
+
+@router.post("/{job_id}/retry", response_model=AiAvatarRenderJobResponse)
+def retry_render_job(
+    job_id: str,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    svc: AiAvatarRenderService = Depends(_get_service),
+):
+    """重试失败的渲染任务."""
+    job = svc.retry_render_job(job_id, current_user.user.id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="渲染任务不存在")
+    if job.status != "pending":
+        raise HTTPException(
+            status_code=400,
+            detail=f"仅 failed 状态的任务可重试，当前状态: {job.status}",
+        )
+
+    # 重新触发渲染
+    try:
+        from app.tasks.ai_avatar_render import execute_ai_avatar_render
+
+        execute_ai_avatar_render.delay(job.id)
+    except Exception:
+        logger.warning("Celery 任务提交失败，重试任务已重置但未触发执行: %s", job.id)
+
+    return job
+
+
+
+# ── POST /smart-cover — 智能获取封面（MediaKit 抽帧 + 评分选帧）────────
+
+
+@router.post("/smart-cover", response_model=SmartCoverResponse)
+def generate_avatar_smart_cover(
+    body: SmartCoverRequest,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> SmartCoverResponse:
+    """智能获取数字人视频封面.
+
+    复用智能剪辑的 MediaKit 抽帧 + 质量评分选最佳帧逻辑（非 FFmpeg 简单截帧），
+    并将选中帧转存到自家 OSS，返回非临时的封面公网 URL。
+
+    前端「智能获取封面」按钮可直接调用本接口；不依赖渲染任务完成。
+    """
+    video_url = (body.video_url or "").strip()
+    if not video_url.startswith(("http://", "https://")):
+        raise HTTPException(status_code=400, detail="video_url 必须是合法的 HTTP/HTTPS URL")
+
+    cover_url = generate_smart_cover(video_url, max_frames=body.max_frames)
+    if not cover_url:
+        return SmartCoverResponse(
+            cover_url="",
+            status="fallback_failed",
+            message="智能抽帧失败（MediaKit 不可用或抽帧异常），请稍后重试",
+        )
+    logger.info("智能封面生成成功: user=%s", current_user.user.id)
+    return SmartCoverResponse(cover_url=cover_url, status="completed")

apps/api/app/api/routes/asset_libraries.py

@@ -20,7 +20,7 @@ from packages.application import (
     GetProjectUseCase,
     ListAssetLibrariesUseCase,
 )
-from packages.domain import AssetLibrary, AssetLibraryKind
+from packages.domain import AssetLibraryKind
 
 from ._helpers import check_project_access
 
@@ -120,30 +120,11 @@ def ensure_default_library(
 
     kind = AssetLibraryKind(request.kind)
 
-    # 查找该项目下同 kind 的素材库，返回第一个
-    existing = asset_library_repository.find_by_project(request.project_id)
-    for lib in existing:
-        if lib.kind == kind:
-            return _to_asset_library_response(lib)
-
-    # 不存在 → 自动创建
-    import uuid
-    from datetime import datetime, timezone
-
-    now = datetime.now(timezone.utc)
+    # Issue #1775: 幂等获取/创建——依赖唯一约束 uq_asset_libraries_project_kind，
+    # 并发创建冲突时回滚重查返回已有记录，不再依赖应用层"先查后插"，也不会 500。
     default_name = _DEFAULT_LIBRARY_NAMES.get(request.kind, f"{request.kind}素材库")
-    library = AssetLibrary(
-        id=str(uuid.uuid4()),
-        project_id=request.project_id,
-        name=default_name,
-        kind=kind,
-        asset_count=0,
-        total_size=0,
-        created_at=now,
-        updated_at=now,
-    )
-    created = asset_library_repository.create(library)
-    return _to_asset_library_response(created)
+    library = asset_library_repository.get_or_create_default_library(request.project_id, kind, name=default_name)
+    return _to_asset_library_response(library)
 
 
 @router.delete("/{library_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)

apps/api/app/api/routes/lipsync.py

@@ -0,0 +1,199 @@
+"""对口型 API 路由 — #1796 MediaKit 对口型, #1809 参数调整.
+
+接口：
+  POST   /api/v1/lipsync/jobs          提交对口型任务
+  GET    /api/v1/lipsync/jobs          任务列表
+  GET    /api/v1/lipsync/jobs/{id}     任务详情
+  POST   /api/v1/lipsync/jobs/{id}/refresh  刷新任务状态
+  POST   /api/v1/lipsync/jobs/{id}/cancel   取消任务
+"""
+
+from __future__ import annotations
+
+import logging
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import (
+    get_cosyvoice_service,
+    get_db_session,
+    get_voice_clone_profile_repository,
+)
+from app.schemas.lipsync import CreateLipsyncJobRequest, LipsyncJobResponse
+from app.services.lipsync_service import LipsyncService
+from app.services.mediakit_client import MediaKitError
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Query
+from sqlalchemy.orm import Session
+
+from packages.application.cosyvoice_service import CosyVoiceError, CosyVoiceService
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _get_service(
+    db: Session = Depends(get_db_session),
+    voice_clone_repo=Depends(get_voice_clone_profile_repository),
+    cosyvoice_service: CosyVoiceService = Depends(get_cosyvoice_service),
+) -> LipsyncService:
+    # voice_clone_repo 用于克隆音色 profile 解析；cosyvoice_service 用于 TTS 直生
+    # （TTS 合成、音色解析、错误码归一化都在 LipsyncService 内部完成）
+    return LipsyncService(
+        db,
+        cosyvoice_service=cosyvoice_service,
+        voice_clone_repo=voice_clone_repo,
+    )
+
+
+# ── POST /jobs — 提交对口型任务 ───────────────────────────────────────────
+
+
+@router.post("/jobs", response_model=LipsyncJobResponse, status_code=201)
+def create_lipsync_job(
+    body: CreateLipsyncJobRequest,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    svc: LipsyncService = Depends(_get_service),
+):
+    """提交对口型任务.
+
+    #1809/#1822: 前端传 {video_url, voice_id, script_text, speed?, emotion?}，
+    后端内部解析音色、调 TTS 合成音频、转存 OSS，再提交 MediaKit；
+    也支持直接传 {video_url, audio_url}。
+    """
+    try:
+        job = svc.create_job(
+            user_id=current_user.user.id,
+            video_url=body.video_url,
+            audio_url=body.audio_url,
+            voice_id=body.voice_id,
+            script_text=body.script_text,
+            speed=body.speed,
+            emotion=body.emotion,
+            enable_video_loop=body.enable_video_loop,
+            project_id=body.project_id,
+        )
+    except ValueError as exc:
+        # 参数无效（如 voice_id 格式不对、文本过长等）
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except CosyVoiceError as exc:
+        # TTS 合成基础设施失败（API/网络/认证）
+        raise HTTPException(
+            status_code=502,
+            detail={"code": "TTSSynthesisFailed", "message": str(exc)},
+        ) from exc
+    except MediaKitError as exc:
+        # TTS 合成失败 / 音色无权访问 → 400/403；MediaKit 提交失败 → 502
+        status_code = 502
+        if exc.code in ("VoiceForbidden",):
+            status_code = 403
+        elif exc.code in ("InvalidInput", "TTSInvalidParam", "VoiceNotReady"):
+            status_code = 400
+        elif exc.code == "TTSSynthesisFailed":
+            status_code = 502
+        raise HTTPException(
+            status_code=status_code,
+            detail={
+                "code": exc.code,
+                "message": str(exc),
+                "request_id": getattr(exc, "request_id", ""),
+            },
+        ) from exc
+    except Exception as exc:
+        # 兜底：任何未预期的错误返回 400 而非 500
+        logger.error("创建对口型任务异常: %s", exc, exc_info=True)
+        raise HTTPException(
+            status_code=400,
+            detail=f"创建对口型任务失败: {exc}",
+        ) from exc
+
+    return job
+
+
+# ── GET /jobs — 任务列表 ─────────────────────────────────────────────────
+
+
+@router.get("/jobs", response_model=dict)
+def list_lipsync_jobs(
+    project_id: str = Query("", description="项目 ID 过滤"),
+    status: str = Query("", description="状态过滤"),
+    offset: int = Query(0, ge=0),
+    limit: int = Query(20, ge=1, le=100),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    svc: LipsyncService = Depends(_get_service),
+):
+    """获取对口型任务列表."""
+    items, total = svc.list_jobs(
+        user_id=current_user.user.id,
+        project_id=project_id,
+        status=status,
+        offset=offset,
+        limit=limit,
+    )
+    return {
+        "items": [LipsyncJobResponse.model_validate(j) for j in items],
+        "total": total,
+        "offset": offset,
+        "limit": limit,
+    }
+
+
+# ── GET /jobs/{job_id} — 任务详情 ────────────────────────────────────────
+
+
+@router.get("/jobs/{job_id}", response_model=LipsyncJobResponse)
+def get_lipsync_job(
+    job_id: str,
+    background: BackgroundTasks,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    svc: LipsyncService = Depends(_get_service),
+):
+    """获取对口型任务详情.
+
+    非终态任务：先返回 DB 缓存，挂后台刷新（下次轮询拿到新状态），
+    避免 MediaKit 慢响应阻塞前端轮询。
+    """
+    job = svc.get_job(job_id, current_user.user.id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="任务不存在")
+
+    if job.status not in ("completed", "failed"):
+        background.add_task(svc.refresh_job_status, job_id, current_user.user.id)
+
+    return job
+
+
+# ── POST /jobs/{job_id}/refresh — 刷新状态 ───────────────────────────────
+
+
+@router.post("/jobs/{job_id}/refresh", response_model=LipsyncJobResponse)
+def refresh_lipsync_job(
+    job_id: str,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    svc: LipsyncService = Depends(_get_service),
+):
+    """从 MediaKit 拉取最新状态并更新."""
+    job = svc.refresh_job_status(job_id, current_user.user.id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="任务不存在")
+    return job
+
+
+# ── POST /jobs/{job_id}/cancel — 取消任务 ────────────────────────────────
+
+
+@router.post("/jobs/{job_id}/cancel", response_model=LipsyncJobResponse)
+def cancel_lipsync_job(
+    job_id: str,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    svc: LipsyncService = Depends(_get_service),
+):
+    """取消对口型任务（仅 pending/submitted 状态可取消）."""
+    job = svc.cancel_job(job_id, current_user.user.id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="任务不存在")
+    if job.status != "cancelled":
+        raise HTTPException(
+            status_code=400,
+            detail=f"任务状态 {job.status} 不可取消，仅 pending/submitted 可取消",
+        )
+    return job

apps/api/app/api/routes/projects.py

@@ -1,13 +1,14 @@
 from typing import Any
 
 from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_project_repository
+from app.dependencies import get_asset_library_repository, get_project_repository
 from app.schemas.project import (
     CreateProjectRequest,
     ListProjectsResponse,
     ProjectResponse,
 )
 from fastapi import APIRouter, Depends, HTTPException, Response, status
+from pydantic import BaseModel
 
 from packages.application import (
     CreateProjectCommand,
@@ -16,10 +17,20 @@ from packages.application import (
     GetProjectUseCase,
     ListProjectsUseCase,
 )
+from packages.domain import AssetLibraryKind
 
 router = APIRouter()
 
 
+class DefaultContextResponse(BaseModel):
+    """幂等默认上下文响应（Issue #1775）：默认项目 + 各类型默认素材库 ID。"""
+
+    project_id: str
+    image_library_id: str
+    video_library_id: str
+    voice_library_id: str
+
+
 def _to_project_response(item) -> ProjectResponse:
     return ProjectResponse(
         id=item.id,
@@ -72,6 +83,35 @@ def create_project(
     return _to_project_response(project)
 
 
+@router.post("/ensure-default", response_model=DefaultContextResponse)
+def ensure_default_project_and_libraries(
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+    asset_library_repository: Any = Depends(get_asset_library_repository),
+) -> DefaultContextResponse:
+    """幂等获取/创建当前用户的默认项目和三类默认素材库（Issue #1775）。
+
+    - 同一用户永远只有一个默认项目（部分唯一索引 uq_projects_owner_default）
+    - 同一项目同 kind 永远只有一个默认素材库（唯一约束 uq_asset_libraries_project_kind）
+    - 并发调用/失败重试：唯一约束冲突时返回已存在记录，不报 500
+    - 项目和素材库的创建各自在仓储事务内幂等，冲突回滚后重查返回同一条
+    """
+    user_id = authenticated_user.user.id
+    project = project_repository.get_or_create_default_project(user_id)
+
+    libraries = {}
+    for kind in (AssetLibraryKind.VIDEO, AssetLibraryKind.VOICE, AssetLibraryKind.IMAGE):
+        library = asset_library_repository.get_or_create_default_library(project.id, kind)
+        libraries[kind] = library.id
+
+    return DefaultContextResponse(
+        project_id=project.id,
+        image_library_id=libraries[AssetLibraryKind.IMAGE],
+        video_library_id=libraries[AssetLibraryKind.VIDEO],
+        voice_library_id=libraries[AssetLibraryKind.VOICE],
+    )
+
+
 @router.delete("/{project_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 def delete_project(
     project_id: str,

apps/api/app/api/routes/scripts.py

@@ -0,0 +1,123 @@
+"""Script (口播文案库) CRUD routes — Issue #1795."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session
+from app.schemas.script import (
+    CreateScriptRequest,
+    ScriptListResponse,
+    ScriptResponse,
+    ScriptSegment,
+    UpdateScriptRequest,
+)
+from app.services.script_service import ScriptNotFoundError, ScriptService
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from sqlalchemy.orm import Session
+
+router = APIRouter()
+
+
+def _get_service(session: Session = Depends(get_db_session)) -> ScriptService:
+    return ScriptService(session)
+
+
+def _to_response(script) -> ScriptResponse:
+    segments = script.segments or []
+    return ScriptResponse(
+        id=script.id,
+        user_id=script.user_id,
+        title=script.title,
+        content=script.content,
+        segments=[
+            ScriptSegment(text=s.get("text", ""), duration=s.get("duration")) if isinstance(s, dict) else s
+            for s in segments
+        ],
+        tags=script.tags or [],
+        created_at=script.created_at,
+        updated_at=script.updated_at,
+    )
+
+
+@router.get("", response_model=ScriptListResponse)
+def list_scripts(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=200),
+    tag: Optional[str] = Query(None, description="按标签筛选"),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    svc: ScriptService = Depends(_get_service),
+) -> ScriptListResponse:
+    user_id = authenticated_user.user.id
+    items, total = svc.list_scripts(user_id, skip=skip, limit=limit, tag=tag)
+    return ScriptListResponse(
+        items=[_to_response(i) for i in items],
+        total=total,
+    )
+
+
+@router.post("", response_model=ScriptResponse, status_code=status.HTTP_201_CREATED)
+def create_script(
+    request: CreateScriptRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    svc: ScriptService = Depends(_get_service),
+) -> ScriptResponse:
+    user_id = authenticated_user.user.id
+    script = svc.create_script(
+        user_id=user_id,
+        title=request.title,
+        content=request.content,
+        segments=[s.model_dump() for s in request.segments],
+        tags=request.tags,
+    )
+    return _to_response(script)
+
+
+@router.get("/{script_id}", response_model=ScriptResponse)
+def get_script(
+    script_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    svc: ScriptService = Depends(_get_service),
+) -> ScriptResponse:
+    user_id = authenticated_user.user.id
+    try:
+        script = svc.get_script(script_id, user_id)
+    except ScriptNotFoundError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Script not found") from exc
+    return _to_response(script)
+
+
+@router.put("/{script_id}", response_model=ScriptResponse)
+def update_script(
+    script_id: str,
+    request: UpdateScriptRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    svc: ScriptService = Depends(_get_service),
+) -> ScriptResponse:
+    user_id = authenticated_user.user.id
+    try:
+        script = svc.update_script(
+            script_id=script_id,
+            user_id=user_id,
+            title=request.title,
+            content=request.content,
+            segments=[s.model_dump() for s in request.segments] if request.segments is not None else None,
+            tags=request.tags,
+        )
+    except ScriptNotFoundError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Script not found") from exc
+    return _to_response(script)
+
+
+@router.delete("/{script_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
+def delete_script(
+    script_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    svc: ScriptService = Depends(_get_service),
+) -> Response:
+    user_id = authenticated_user.user.id
+    deleted = svc.delete_script(script_id, user_id)
+    if not deleted:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Script not found")
+    return

apps/api/app/api/routes/templates.py

@@ -106,6 +106,10 @@ def list_templates(
     tag: str | None = Query(None, description="按标签筛选"),
     keyword: str | None = Query(None, description="按名称关键词搜索"),
     mode: str | None = Query(None, description="按剪辑模式筛选"),
+    valid_only: bool = Query(
+        False,
+        description="仅返回已配置片段的模板（剪辑页传 true；模板编辑器不传，可查看全部模板含草稿）",
+    ),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
 ) -> ListTemplatesResponse:
@@ -116,6 +120,7 @@ def list_templates(
             tag=tag,
             keyword=keyword,
             mode=mode,
+            valid_only=valid_only,
         )
         use_case = ListTemplatesUseCase(template_repository)
         templates = use_case.execute(user_id, skip=skip, limit=limit, filter=tpl_filter)

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

@@ -36,17 +36,11 @@ from app.services.asset_segment_tracker import (
     remove_used_segment,
 )
 from app.services.edit_plan_service import EditPlanService
-from app.services.edit_template_service import EditTemplateService
+from app.services.edit_template_service import EditTemplateService, TemplateNotFoundError
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Query, status
 from sqlalchemy.orm import Session
 
 from packages.adapters.sqlalchemy_impl.asset_repository import SQLAlchemyAssetRepository
-from packages.adapters.sqlalchemy_impl.template_clip_config_repository import (
-    SQLAlchemyTemplateClipConfigRepository,
-)
-from packages.adapters.sqlalchemy_impl.template_repository import (
-    SQLAlchemyTemplateRepository,
-)
 from packages.domain.plan_generator_utils import (
     _calc_random_start_time,
     build_scene_segments,
@@ -399,73 +393,42 @@ def _safe_segment_duration(value, default: float) -> float:
 
 def _get_template_segments(
     template_id: str,
+    user_id: str,
     tpl_svc: EditTemplateService,
-    db: Session,
 ) -> list[tuple[int, float, float]]:
     """获取模板的片段配置（顺序、最短时长、最长时长）.
 
-    优先从新模板系统（template_clip_configs）查询，
-    若不存在则回退到旧模板系统（template_segments）。
+    单一数据源：模板主表为 ``templates``（用户自建，归属 user_id）/
+    ``edit_templates``（全局模板库），片段配置主表为 ``template_clip_configs``
+    （由 ``EditTemplateService.list_clip_configs_for_editor`` 统一读取）。
+
+    不再使用"新表抛异常 → 降级直查配置表 → 再降级查 segments"的异常控制流，
+    也不在正常请求中打印 ``ValueError: 模板不存在`` 堆栈。
+
+    Args:
+        template_id: 模板 ID
+        user_id: 当前登录用户 ID（用于归属校验）
+        tpl_svc: 模板编辑器服务
 
     Returns:
-        [(segment_order, duration_min, duration_max), ...] 按 order 排序
+        [(segment_order, duration_min, duration_max), ...] 按 order 排序；
+        模板存在但未配置片段时返回空列表。
+
+    Raises:
+        TemplateNotFoundError: 模板不存在、已删除或不归属于当前用户。
     """
-    # 优先查新模板系统
-    try:
-        clip_configs = tpl_svc.list_clip_configs(template_id)
-        if clip_configs:
-            result = []
-            for cc in clip_configs:
-                dur_min = _safe_segment_duration(cc.min_duration, _DEFAULT_EDITOR_CLIP_DURATION)
-                dur_max = _safe_segment_duration(
-                    cc.max_duration or cc.min_duration,
-                    _DEFAULT_EDITOR_CLIP_DURATION,
-                )
-                dur_min, dur_max = min(dur_min, dur_max), max(dur_min, dur_max)
-                result.append((cc.order, dur_min, dur_max))
-            return sorted(result, key=lambda x: x[0])
-    except Exception:
-        logger.warning("新模板系统查询clip_configs失败（主表可能不存在），直接查clip_configs表", exc_info=True)
+    clip_configs = tpl_svc.list_clip_configs_for_editor(template_id, user_id)
 
-    # 兜底：直接查 template_clip_configs 表（片段表有 template_id 外键，不依赖模板主表）
-    try:
-        direct_repo = SQLAlchemyTemplateClipConfigRepository(db)
-        direct_configs = direct_repo.list_by_template(template_id)
-        if direct_configs:
-            result = []
-            for cc in direct_configs:
-                dur_min = _safe_segment_duration(cc.min_duration, _DEFAULT_EDITOR_CLIP_DURATION)
-                dur_max = _safe_segment_duration(
-                    cc.max_duration or cc.min_duration,
-                    _DEFAULT_EDITOR_CLIP_DURATION,
-                )
-                dur_min, dur_max = min(dur_min, dur_max), max(dur_min, dur_max)
-                result.append((cc.order, dur_min, dur_max))
-            return sorted(result, key=lambda x: x[0])
-    except Exception:
-        logger.warning("直接查clip_configs表也失败，继续回退旧系统", exc_info=True)
-
-    # 回退到旧模板系统（template_segments表）
-    try:
-        old_repo = SQLAlchemyTemplateRepository(db)
-        segments = old_repo.list_segments(template_id)
-        if segments:
-            result = []
-            for s in segments:
-                dur_min = _safe_segment_duration(s.duration_min, _DEFAULT_EDITOR_CLIP_DURATION)
-                dur_max = _safe_segment_duration(s.duration_max, _DEFAULT_EDITOR_CLIP_DURATION)
-                dur_min, dur_max = min(dur_min, dur_max), max(dur_min, dur_max)
-                result.append((s.segment_order, dur_min, dur_max))
-            return sorted(result, key=lambda x: x[0])
-    except Exception:
-        logger.warning("旧模板系统查询segments失败", exc_info=True)
-
-    # 所有途径都失败：模板没有片段配置（可能是无效测试模板）
-    logger.error(
-        "模板无片段配置：template_id=%s（可能是 is_active=false 的无效模板）",
-        template_id,
-    )
-    return []
+    result = []
+    for cc in clip_configs:
+        dur_min = _safe_segment_duration(cc.min_duration, _DEFAULT_EDITOR_CLIP_DURATION)
+        dur_max = _safe_segment_duration(
+            cc.max_duration or cc.min_duration,
+            _DEFAULT_EDITOR_CLIP_DURATION,
+        )
+        dur_min, dur_max = min(dur_min, dur_max), max(dur_min, dur_max)
+        result.append((cc.order, dur_min, dur_max))
+    return sorted(result, key=lambda x: x[0])
 
 
 def _recommended_time_conflicts(
@@ -668,13 +631,21 @@ def create_clips_from_assets_editor(
     7. 素材时长为 0 或缺失时报 400，不创建无效片段
     """
     tpl_svc, plan_svc = services
+    user_id = str(current_user.user.id)
 
-    # 1. 查询模板 segments
-    segments = _get_template_segments(template_id, tpl_svc, db)
+    # 1. 查询模板片段配置。模板不存在/已删除/无权限 → 404；
+    #    模板存在但确实未配置片段 → 422（配置错误，与 404 区分）。
+    try:
+        segments = _get_template_segments(template_id, user_id, tpl_svc)
+    except TemplateNotFoundError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="模板不存在或无权访问",
+        ) from exc
     if not segments:
         raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="模板没有片段配置，无法创建片段",
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail="模板未配置片段",
         )
 
     # 防御：schema validator 已过滤 null/空串，这里再归一化一次，

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

@@ -41,29 +41,33 @@ def get_draft_plan_id(
     这是模板编辑器路由的核心依赖——所有编辑器端点都先经过这里，
     确保 template_id → plan_id 的映射始终存在。
 
-    兼容策略：优先从新模板系统（edit_templates 表）查找，
-    若不存在则回退到旧模板系统（templates 表），确保用户自建模板可用。
+    模板读取遵循单一数据源、显式判定（不使用异常降级）：
+    - 用户自建模板在旧表 ``templates``（归属 user_id，is_active=True）；
+    - 全局模板在新表 ``edit_templates``（无 user_id，全局可读）。
+    模板不存在、已删除或不归属于当前用户时，一律返回 404。
     """
     tpl_svc, plan_svc = services
     user_id = str(current_user.user.id)
 
+    # 0. 门禁：校验模板存在且可访问（即使草稿已缓存命中也要校验，
+    #    避免模板被删除/无权访问后仍可通过既有草稿 plan 继续操作）。
+    old_repo = SQLAlchemyTemplateRepository(db)
+    old_template = old_repo.get_active(template_id, user_id)
+    is_global_template = tpl_svc.get_template(template_id) is not None
+    if old_template is None and not is_global_template:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="模板不存在")
+
     # 1. 草稿已存在 → 直接返回
     draft = tpl_svc.get_template_draft(template_id)
     if draft is not None:
         return draft.id
 
-    # 2. 新系统有模板 → 用新服务创建草稿
-    if tpl_svc.get_template(template_id) is not None:
+    # 2. 全局模板（新系统）→ 用新服务创建草稿
+    if is_global_template:
         draft = tpl_svc.create_template_draft(template_id, user_id=user_id)
         return draft.id
 
-    # 3. 回退到旧模板系统（templates 表）
-    old_repo = SQLAlchemyTemplateRepository(db)
-    old_template = old_repo.get(template_id, user_id=user_id)
-    if old_template is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="模板不存在")
-
-    # 4. 基于旧模板创建草稿计划
+    # 3. 旧模板（templates 表）→ 基于旧模板创建草稿计划
     from app.services.plan_generator_service import PlanGeneratorService
 
     from packages.domain.edit_template import EditTemplate, EditTemplateStatus

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

@@ -150,7 +150,7 @@ def rollback_template(
     try:
         tpl = tpl_svc.rollback_to_version(template_id, request.version)
     except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
 
     clip_configs = tpl_svc.list_clip_configs(template_id)
     return EditorRollbackResponse(

apps/api/app/api/routes/tts.py

@@ -173,6 +173,14 @@ def synthesize(
         # job.voice_id 统一存解析后的 CosyVoice voice_id
         actual_voice_id = resolved_profile.voice_id
 
+    # 语速/情绪等合成参数随 metadata 落库，workflow 提交 CosyVoice 时读取透传
+    synthesis_meta = {
+        "speed": request.speed,
+        "emotion": request.emotion or "",
+    }
+    if request.metadata_:
+        synthesis_meta.update(request.metadata_)
+
     use_case = CreateTTSJobUseCase(repository)
     job = use_case.execute(
         user_id=user_id,
@@ -180,7 +188,7 @@ def synthesize(
         voice_id=actual_voice_id,
         voice_model=request.voice_model,
         voice_clone_profile_id=voice_clone_profile_id,
-        metadata=request.metadata_,
+        metadata=synthesis_meta,
     )
 
     # 提交 CosyVoice 合成任务
@@ -567,6 +575,7 @@ def preview_tts(
             text=request.text,
             voice_id=actual_voice_id,
             speed=request.speed,
+            emotion=request.emotion,
         )
     except CosyVoiceError as e:
         raise HTTPException(

apps/api/app/api/routes/upload.py

@@ -208,6 +208,8 @@ def _create_pending_asset(
     find-or-create：prepare 阶段已按 file_hash/client_upload_id 预建的占位记录
     会被 find_by_library_and_file_hash/find_by_library_and_client_upload_id 命中，
     直接复用并补齐字段（避免 pre-create + complete 重复建两条）。
+
+    Issue #1776: 素材库计数由 asset_repository.create() 自动维护。
     """
     # 1. 按 client_upload_id / file_hash 查找现有记录
     existing = None
@@ -389,6 +391,7 @@ async def prepare_direct_upload(
                 file_size=request.file_size,
             )
             pending_asset_id = pending.id
+            # Issue #1776: 计数由 asset_repository.create() 自动维护
         except Exception as error:
             # 预建失败不阻塞签名：complete 仍可按 OSS 文件 + hash 兜底去重
             logger.warning("预建 asset 占位失败，降级走 old flow: %s", error)
@@ -474,6 +477,7 @@ async def complete_direct_upload(
         client_upload_id=request.client_upload_id,
         file_size=request.file_size,
     )
+    # Issue #1776: 计数由 asset_repository.create() 自动维护
 
     job = _submit_ingest_job(
         project_id=request.project_id,
@@ -568,6 +572,7 @@ async def upload_asset(
         file_hash=file_hash,
         client_upload_id=client_upload_id,
     )
+    # Issue #1776: 计数由 asset_repository.create() 自动维护
 
     job = _submit_ingest_job(
         project_id=project_id,

apps/api/app/schemas/ai_avatar_render.py

@@ -0,0 +1,124 @@
+"""AI数字人渲染合成管线 API Schema — #1798."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class BRollSegment(BaseModel):
+    """B-roll 片段配置."""
+
+    script_segment_index: int = Field(..., ge=0, description="对应文案片段索引")
+    asset_url: str = Field(..., description="B-roll 素材 URL")
+    mode: str = Field(..., description="插入模式: fullscreen 或 pip")
+    start_time: float = Field(..., ge=0.0, description="在对口型视频中的起始时间(秒)")
+    end_time: float = Field(..., ge=0.0, description="在对口型视频中的结束时间(秒)")
+    pip_position: Optional[str] = Field("bottom_right", description="pip 模式位置")
+    pip_scale: Optional[float] = Field(0.3, ge=0.05, le=1.0, description="pip 模式缩放比例")
+
+    @field_validator("mode")
+    @classmethod
+    def validate_mode(cls, v: str) -> str:
+        v = v.strip().lower()
+        if v not in ("fullscreen", "pip"):
+            raise ValueError("mode 必须为 fullscreen 或 pip")
+        return v
+
+    @field_validator("asset_url")
+    @classmethod
+    def validate_asset_url(cls, v: str) -> str:
+        v = v.strip()
+        if not v:
+            raise ValueError("asset_url 不能为空")
+        if not v.startswith(("http://", "https://")):
+            raise ValueError("asset_url 必须是 HTTP/HTTPS URL")
+        return v
+
+    @field_validator("end_time")
+    @classmethod
+    def validate_end_time(cls, v: float, info: Any) -> float:
+        start = info.data.get("start_time", 0.0)
+        if v <= start:
+            raise ValueError("end_time 必须大于 start_time")
+        return v
+
+
+class CreateAiAvatarRenderRequest(BaseModel):
+    """创建渲染任务请求."""
+
+    lipsync_job_id: str = Field(..., description="对口型任务 ID")
+    script_id: str = Field("", description="文案 ID（选自文案库时传；手动输入文案直生场景可留空）")
+    b_roll_segments: list[BRollSegment] = Field(default_factory=list, description="B-roll 片段列表")
+    title_config: dict[str, Any] = Field(default_factory=dict, description="标题配置")
+    cover_config: dict[str, Any] = Field(default_factory=dict, description="封面配置")
+    project_id: str = Field("", description="项目 ID")
+
+    @field_validator("lipsync_job_id")
+    @classmethod
+    def validate_lipsync_job_id(cls, v: str) -> str:
+        v = v.strip()
+        if not v:
+            raise ValueError("lipsync_job_id 不能为空")
+        return v
+
+    @field_validator("script_id")
+    @classmethod
+    def validate_script_id(cls, v: str) -> str:
+        # script_id 可选：手动输入文案（TTS 直生）场景不关联文案库条目
+        return (v or "").strip()
+
+
+class AiAvatarRenderJobResponse(BaseModel):
+    """渲染任务响应."""
+
+    id: str
+    user_id: str
+    project_id: str
+    lipsync_job_id: str
+    script_id: str = ""
+    b_roll_segments: list[dict[str, Any]]
+    title_config: dict[str, Any]
+    cover_config: dict[str, Any]
+    status: str
+    progress: int
+    output_video_url: str
+    output_cover_url: str
+    output_duration: float
+    error_message: str
+    submitted_at: Optional[datetime] = None
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class AiAvatarRenderProgressResponse(BaseModel):
+    """渲染进度响应."""
+
+    status: str
+    progress: int
+    output_video_url: str
+    output_cover_url: str
+    output_duration: float
+    error_message: str
+
+
+class SmartCoverRequest(BaseModel):
+    """智能封面请求 — MediaKit 抽帧 + 质量评分选最佳帧."""
+
+    video_url: str = Field(..., description="数字人视频 URL（对口型/渲染成片）")
+    max_frames: int = Field(5, ge=1, le=10, description="抽帧数量（默认 5）")
+
+
+class SmartCoverResponse(BaseModel):
+    """智能封面响应."""
+
+    cover_url: str = Field("", description="封面图公网 URL（OSS，非临时）；失败为空")
+    status: str = Field("completed", description="completed / fallback_failed")
+    message: str = Field("", description="失败原因（如有）")

apps/api/app/schemas/lipsync.py

@@ -0,0 +1,100 @@
+"""对口型 API Schema 定义 — #1796 / #1809 / #1822.
+
+支持两种输入模式（二选一）：
+1. TTS 直生模式（推荐）：传 voice_id + script_text（+ speed/emotion），
+   后端内部先调 CosyVoice 合成音频，再提交 MediaKit 对口型。
+2. 直接音频模式：传 video_url + audio_url（音频已由调用方准备好）。
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class LipsyncJobResponse(BaseModel):
+    """对口型任务响应."""
+
+    id: str
+    user_id: str
+    project_id: str
+    video_url: str
+    audio_url: str
+    enable_video_loop: bool
+    voice_id: str = ""
+    script_text: str = ""
+    speed: float = 1.0
+    emotion: str = ""
+    mediakit_task_id: str
+    status: str
+    output_video_url: str
+    output_duration: float
+    error_message: str
+    error_code: str
+    submitted_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class CreateLipsyncJobRequest(BaseModel):
+    """创建对口型任务请求.
+
+    两种模式（二选一）：
+    - TTS 直生：voice_id + script_text 必填（+ 可选 speed/emotion）；audio_url 留空。
+    - 直接音频：video_url + audio_url 必填。
+    """
+
+    video_url: str = Field(..., description="人物视频 URL（MP4，≤30min，单人真人）")
+
+    # 模式 2：直接音频
+    audio_url: str = Field("", description="驱动音频 URL（mp3/aac/wav/m4a/flac）；直生模式留空")
+
+    # 模式 1：TTS 直生
+    voice_id: str = Field("", description="音色 ID（预置音色或克隆音色 profile UUID）")
+    script_text: str = Field("", description="要合成的文案（直生模式必填，最长 5000 字符）")
+    speed: float = Field(1.0, ge=0.5, le=2.0, description="语速（0.5-2.0），默认 1.0")
+    emotion: str = Field("", description="情绪（natural/excited/calm/friendly 或中文 自然/兴奋/沉稳/亲切）")
+
+    enable_video_loop: bool = Field(False, description="音频长于视频时是否循环画面")
+    project_id: str = Field("", description="项目 ID（可选）")
+
+    @model_validator(mode="after")
+    def _validate_input_mode(self) -> "CreateLipsyncJobRequest":
+        video = (self.video_url or "").strip()
+        if not video:
+            raise ValueError("video_url 不能为空")
+        if not video.startswith(("http://", "https://")):
+            raise ValueError("video_url 必须是 HTTP/HTTPS URL")
+        lower = video.lower().split("?")[0]
+        if not lower.endswith(".mp4"):
+            raise ValueError("video_url 仅支持 MP4 格式")
+
+        has_audio = bool((self.audio_url or "").strip())
+        has_tts = bool((self.voice_id or "").strip()) and bool((self.script_text or "").strip())
+
+        if not has_audio and not has_tts:
+            raise ValueError(
+                "必须提供驱动音频：要么传 audio_url（直接音频模式），"
+                "要么同时传 voice_id + script_text（TTS 直生模式）"
+            )
+
+        if has_tts and len(self.script_text) > 5000:
+            raise ValueError("script_text 最长 5000 字符")
+
+        if has_audio:
+            au = self.audio_url.strip()
+            if not au.startswith(("http://", "https://")):
+                raise ValueError("audio_url 必须是 HTTP/HTTPS URL")
+            au_lower = au.lower().split("?")[0]
+            allowed = (".mp3", ".aac", ".wav", ".m4a", ".flac")
+            if not any(au_lower.endswith(ext) for ext in allowed):
+                raise ValueError(f"audio_url 格式不支持，仅支持: {', '.join(allowed)}")
+            self.audio_url = au
+
+        return self

apps/api/app/schemas/script.py

@@ -0,0 +1,45 @@
+"""Script (口播文案库) Pydantic schemas — Issue #1795."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ScriptSegment(BaseModel):
+    """单段文案."""
+
+    text: str
+    duration: Optional[float] = None
+
+
+class ScriptResponse(BaseModel):
+    id: str
+    user_id: str
+    title: str
+    content: str
+    segments: List[ScriptSegment] = Field(default_factory=list)
+    tags: List[str] = Field(default_factory=list)
+    created_at: datetime
+    updated_at: datetime
+
+
+class ScriptListResponse(BaseModel):
+    items: list[ScriptResponse]
+    total: int = 0
+
+
+class CreateScriptRequest(BaseModel):
+    title: str = Field(..., min_length=1, max_length=255)
+    content: str = ""
+    segments: List[ScriptSegment] = Field(default_factory=list)
+    tags: List[str] = Field(default_factory=list)
+
+
+class UpdateScriptRequest(BaseModel):
+    title: Optional[str] = Field(None, min_length=1, max_length=255)
+    content: Optional[str] = None
+    segments: Optional[List[ScriptSegment]] = None
+    tags: Optional[List[str]] = None

apps/api/app/schemas/tts.py

@@ -16,6 +16,7 @@ class TTSSynthesizeRequest(BaseModel):
     output_name: str = Field("", description="输出文件名")
     language: str = Field("zh-CN", description="语言")
     speed: float = Field(1.0, ge=0.5, le=2.0, description="语速")
+    emotion: str = Field("", description="情绪（natural/excited/calm/friendly，或中文 自然/兴奋/沉稳/亲切）")
     voice_model: str = Field("", description="语音模型名称")
     voice_clone_profile_id: str = Field("", description="关联的音色克隆档案 ID")
     format: str = Field("mp3", description="输出格式（mp3/wav/pcm）")
@@ -109,6 +110,7 @@ class TTSPreviewRequest(BaseModel):
     text: str = Field(..., min_length=1, max_length=200, description="合成文本，限制 200 字")
     voice_id: str = Field(..., min_length=1, description="音色 ID")
     speed: float = Field(1.0, ge=0.5, le=2.0, description="语速")
+    emotion: str = Field("", description="情绪（natural/excited/calm/friendly，或中文）")
     pitch: float = Field(1.0, ge=0.5, le=2.0, description="音调（预留，当前未使用）")
 
 

apps/api/app/services/ai_avatar_cover_service.py

@@ -0,0 +1,162 @@
+"""AI 数字人封面服务 — 复用智能剪辑的 MediaKit 抽帧 + 质量评分选最佳帧.
+
+与 generation_cover.py 的智能选帧能力对齐（不再用 FFmpeg 简单截帧）：
+1. MediaKit extract_frames 抽取多帧（默认 5 帧，SpecifiedFrames 策略）
+2. cover_frame_scorer.score_frames 按清晰度/亮度/色彩评分选最佳
+3. 下载最佳帧并转存 OSS，返回公网封面 URL
+
+降级：MediaKit 不可用或抽帧失败时返回空字符串，由调用方决定回退策略。
+"""
+
+from __future__ import annotations
+
+import logging
+import tempfile
+import uuid
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+def select_best_cover_frame(video_url: str, *, max_frames: int = 5) -> str:
+    """从视频抽取多帧并评分选最佳帧，返回最佳帧的临时 URL.
+
+    Args:
+        video_url: 可公网访问的视频 URL
+        max_frames: 抽帧数量
+
+    Returns:
+        最佳帧图片 URL；失败返回空字符串
+    """
+    if not video_url:
+        return ""
+    try:
+        from packages.shared.cover_frame_scorer import score_frames
+        from packages.shared.mediakit_client import get_mediakit_client
+
+        mk = get_mediakit_client()
+        if not mk.is_available:
+            logger.warning("[数字人封面] MediaKit 未配置，无法智能抽帧")
+            return ""
+
+        snapshots = mk.extract_frames(
+            video_url=video_url,
+            strategy="SpecifiedFrames",
+            max_frames=max_frames,
+            poll_interval=2.0,
+            max_poll_attempts=5,
+            max_retries=0,
+        )
+        if not snapshots:
+            logger.warning("[数字人封面] MediaKit 未返回帧: %s", video_url[:80])
+            return ""
+
+        if len(snapshots) == 1:
+            return snapshots[0].get("image_url") or snapshots[0].get("url") or ""
+
+        # 下载各帧评分
+        import httpx
+
+        candidates = []
+        for snap in snapshots:
+            url = snap.get("image_url") or snap.get("url") or ""
+            if not url:
+                continue
+            tmp_path: Optional[str] = None
+            try:
+                resp = httpx.get(url, timeout=15, follow_redirects=True)
+                resp.raise_for_status()
+                with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
+                    tmp.write(resp.content)
+                    tmp_path = tmp.name
+                candidates.append({"image_path": tmp_path, "url": url})
+            except Exception:
+                candidates.append({"image_path": None, "url": url, "score": 0.0})
+
+        if not candidates:
+            return snapshots[0].get("image_url") or snapshots[0].get("url") or ""
+
+        scored = score_frames(candidates)
+        best = scored[0] if scored else None
+        best_url = best.get("url", "") if best else ""
+
+        # 清理临时文件
+        for c in candidates:
+            p = c.get("image_path")
+            if p:
+                try:
+                    Path(p).unlink(missing_ok=True)
+                except Exception:
+                    pass
+
+        logger.info(
+            "[数字人封面] 智能选帧完成: candidates=%d best_score=%s",
+            len(candidates),
+            best.get("score") if best else "n/a",
+        )
+        return best_url
+
+    except Exception:
+        logger.warning("[数字人封面] 智能选帧失败", exc_info=True)
+        return ""
+
+
+def persist_cover_to_oss(frame_url: str, *, job_id: str = "", prefix: str = "ai-avatar/covers") -> str:
+    """下载帧图并转存到 OSS，返回公网封面 URL.
+
+    Args:
+        frame_url: MediaKit 返回的临时帧图 URL
+        job_id: 关联任务 ID（用于 OSS key 命名）
+        prefix: OSS key 前缀
+
+    Returns:
+        OSS 公网 URL；失败回退原始 frame_url
+    """
+    if not frame_url:
+        return ""
+    tmp_path: Optional[str] = None
+    try:
+        import httpx
+
+        resp = httpx.get(frame_url, timeout=30, follow_redirects=True)
+        resp.raise_for_status()
+        if not resp.content:
+            return frame_url
+
+        with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
+            tmp.write(resp.content)
+            tmp_path = tmp.name
+
+        from packages.shared.storage import get_shared_storage_service
+
+        storage = get_shared_storage_service()
+        token = job_id or uuid.uuid4().hex[:12]
+        cover_key = f"{prefix}/{token}/cover_{uuid.uuid4().hex[:8]}.jpg"
+        public_url = storage.upload_file(
+            file_or_path=tmp_path,
+            storage_key=cover_key,
+            content_type="image/jpeg",
+        )
+        logger.info("[数字人封面] 封面已转存 OSS: key=%s", cover_key)
+        return public_url or frame_url
+    except Exception:
+        logger.warning("[数字人封面] 封面转存 OSS 失败，返回原始 URL", exc_info=True)
+        return frame_url
+    finally:
+        if tmp_path:
+            try:
+                Path(tmp_path).unlink(missing_ok=True)
+            except Exception:
+                pass
+
+
+def generate_smart_cover(video_url: str, *, job_id: str = "", max_frames: int = 5) -> str:
+    """一站式：MediaKit 智能抽帧选最佳 → 转存 OSS，返回封面公网 URL.
+
+    供独立封面接口与渲染管线复用。失败返回空字符串。
+    """
+    best_frame = select_best_cover_frame(video_url, max_frames=max_frames)
+    if not best_frame:
+        return ""
+    return persist_cover_to_oss(best_frame, job_id=job_id)

apps/api/app/services/ai_avatar_render_service.py

@@ -0,0 +1,394 @@
+"""AI数字人渲染合成 Service — #1798.
+
+职责：
+- 创建/查询/取消渲染任务
+- 调用 Celery 异步任务执行渲染
+- B-roll 合成 + 标题叠加 + 封面提取
+- 用户隔离
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.models import (
+    AiAvatarRenderJob,
+    LipsyncJobModel,
+    ScriptModel,
+)
+from packages.domain.video_filter_builder import (
+    build_cover_extract_command,
+    build_title_drawtext_filter,
+)
+from packages.shared.storage import get_shared_storage_service
+
+logger = logging.getLogger(__name__)
+
+
+class AiAvatarRenderError(Exception):
+    """渲染服务异常."""
+
+    def __init__(self, message: str, code: str = "RenderError"):
+        self.code = code
+        super().__init__(message)
+
+
+class AiAvatarRenderService:
+    """AI数字人渲染合成 Service."""
+
+    def __init__(self, db: Session):
+        self.db = db
+
+    # ── 创建任务 ──────────────────────────────────────────────────────────
+
+    def create_render_job(
+        self,
+        *,
+        user_id: str,
+        lipsync_job_id: str,
+        script_id: str = "",
+        b_roll_segments: list[dict[str, Any]] | None = None,
+        title_config: dict[str, Any],
+        cover_config: dict[str, Any],
+        project_id: str = "",
+    ) -> AiAvatarRenderJob:
+        """创建渲染任务.
+
+        Raises:
+            AiAvatarRenderError: 校验失败
+        """
+        # 1. 验证对口型任务
+        lipsync_job = (
+            self.db.query(LipsyncJobModel)
+            .filter(
+                LipsyncJobModel.id == lipsync_job_id,
+                LipsyncJobModel.user_id == user_id,
+            )
+            .first()
+        )
+        if lipsync_job is None:
+            raise AiAvatarRenderError("对口型任务不存在", code="LipsyncJobNotFound")
+        if lipsync_job.status != "completed":
+            raise AiAvatarRenderError(
+                f"对口型任务状态为 {lipsync_job.status}，仅 completed 状态可渲染",
+                code="LipsyncJobNotCompleted",
+            )
+        if not lipsync_job.output_video_url:
+            raise AiAvatarRenderError("对口型任务输出视频 URL 为空", code="LipsyncJobNoOutput")
+
+        # 2. 验证文案归属（仅当选了文案库条目时；手动输入文案直生场景 script_id 可空）
+        script_id = (script_id or "").strip()
+        if script_id:
+            script = (
+                self.db.query(ScriptModel)
+                .filter(
+                    ScriptModel.id == script_id,
+                    ScriptModel.user_id == user_id,
+                )
+                .first()
+            )
+            if script is None:
+                raise AiAvatarRenderError("文案不存在或无权访问", code="ScriptNotFound")
+
+        # 3. 创建渲染任务
+        job_id = str(uuid.uuid4())
+        job = AiAvatarRenderJob(
+            id=job_id,
+            user_id=user_id,
+            project_id=project_id,
+            lipsync_job_id=lipsync_job_id,
+            script_id=script_id,
+            b_roll_segments=[s if isinstance(s, dict) else s.model_dump() for s in (b_roll_segments or [])],
+            title_config=title_config,
+            cover_config=cover_config,
+            status="pending",
+        )
+        self.db.add(job)
+        self.db.flush()
+
+        job.submitted_at = datetime.now(timezone.utc)
+        self.db.commit()
+        self.db.refresh(job)
+        return job
+
+    # ── 查询任务 ──────────────────────────────────────────────────────────
+
+    def get_render_job(self, job_id: str, user_id: str) -> Optional[AiAvatarRenderJob]:
+        """获取渲染任务详情（用户隔离）."""
+        return (
+            self.db.query(AiAvatarRenderJob)
+            .filter(
+                AiAvatarRenderJob.id == job_id,
+                AiAvatarRenderJob.user_id == user_id,
+            )
+            .first()
+        )
+
+    def list_render_jobs(
+        self,
+        *,
+        user_id: str,
+        project_id: str = "",
+        status: str = "",
+        offset: int = 0,
+        limit: int = 20,
+    ) -> tuple[list[AiAvatarRenderJob], int]:
+        """获取渲染任务列表（分页 + 用户隔离）."""
+        query = self.db.query(AiAvatarRenderJob).filter(AiAvatarRenderJob.user_id == user_id)
+        if project_id:
+            query = query.filter(AiAvatarRenderJob.project_id == project_id)
+        if status:
+            query = query.filter(AiAvatarRenderJob.status == status)
+
+        total = query.count()
+        items = query.order_by(AiAvatarRenderJob.created_at.desc()).offset(offset).limit(limit).all()
+        return items, total
+
+    # ── 取消任务 ──────────────────────────────────────────────────────────
+
+    def cancel_render_job(self, job_id: str, user_id: str) -> Optional[AiAvatarRenderJob]:
+        """取消渲染任务（仅 pending 状态可取消）."""
+        job = self.get_render_job(job_id, user_id)
+        if job is None:
+            return None
+        if job.status in ("pending", "submitted"):
+            job.status = "cancelled"
+            job.updated_at = datetime.now(timezone.utc)
+            self.db.commit()
+            self.db.refresh(job)
+        return job
+
+    # ── 重试任务 ──────────────────────────────────────────────────────────
+
+    def retry_render_job(self, job_id: str, user_id: str) -> Optional[AiAvatarRenderJob]:
+        """重试失败的渲染任务."""
+        job = self.get_render_job(job_id, user_id)
+        if job is None:
+            return None
+        if job.status != "failed":
+            return None
+        job.status = "pending"
+        job.progress = 0
+        job.error_message = ""
+        job.output_video_url = ""
+        job.output_cover_url = ""
+        job.output_duration = 0.0
+        job.started_at = None
+        job.completed_at = None
+        job.updated_at = datetime.now(timezone.utc)
+        self.db.commit()
+        self.db.refresh(job)
+        return job
+
+    # ── 执行渲染（Celery 异步调用） ──────────────────────────────────────
+
+    def execute_render(self, job_id: str) -> None:
+        """执行渲染管线.
+
+        由 Celery 异步任务调用，流程:
+        1. 下载对口型输出视频 (20%)
+        2. 构建 FFmpeg 滤镜链 (40%)
+        3. 执行 FFmpeg 渲染 (80%)
+        4. 提取封面 (90%)
+        5. 上传到 OSS (95%)
+        6. 更新任务状态 (100%)
+        """
+        job = self.db.query(AiAvatarRenderJob).filter(AiAvatarRenderJob.id == job_id).first()
+        if job is None:
+            logger.error("渲染任务不存在: %s", job_id)
+            return
+
+        if job.status == "cancelled":
+            logger.info("渲染任务已取消: %s", job_id)
+            return
+
+        try:
+            # 更新状态为 processing
+            job.status = "processing"
+            job.started_at = datetime.now(timezone.utc)
+            job.progress = 5
+            job.updated_at = datetime.now(timezone.utc)
+            self.db.commit()
+
+            # 获取对口型任务信息
+            lipsync_job = self.db.query(LipsyncJobModel).filter(LipsyncJobModel.id == job.lipsync_job_id).first()
+            if lipsync_job is None:
+                raise AiAvatarRenderError("关联的对口型任务不存在", code="LipsyncJobNotFound")
+
+            # 1. 下载对口型输出视频 (20%)
+            input_video_path = self._download_video(lipsync_job.output_video_url)
+            job.progress = 20
+            self.db.commit()
+
+            # 2. 构建 FFmpeg 滤镜链 (40%)
+            from packages.domain.video_filter_builder import build_broll_overlay_filter
+
+            filter_complex = build_broll_overlay_filter(
+                b_roll_segments=job.b_roll_segments,
+                video_duration=lipsync_job.output_duration,
+            )
+
+            # 标题叠加
+            title_filter = build_title_drawtext_filter(job.title_config)
+            if title_filter:
+                if filter_complex:
+                    filter_complex += f"[vout]{title_filter}[vout_titled];"
+                else:
+                    filter_complex = f"[0:v]{title_filter}[vout_titled];"
+
+            # 清理末尾分号
+            if filter_complex.endswith(";"):
+                filter_complex = filter_complex[:-1]
+
+            # 最终输出标签
+            final_label = "vout_titled" if title_filter else ("vout" if filter_complex else None)
+
+            job.progress = 40
+            self.db.commit()
+
+            # 3. 执行 FFmpeg 渲染 (80%)
+            with tempfile.TemporaryDirectory() as tmpdir:
+                output_video_path = os.path.join(tmpdir, "output.mp4")
+
+                cmd = self._build_ffmpeg_command(
+                    input_video=input_video_path,
+                    b_roll_segments=job.b_roll_segments,
+                    filter_complex=filter_complex,
+                    final_label=final_label,
+                    output_path=output_video_path,
+                )
+
+                exit_code = os.system(cmd)
+                if exit_code != 0:
+                    raise AiAvatarRenderError(f"FFmpeg 渲染失败，退出码: {exit_code}", code="FFmpegFailed")
+
+                job.progress = 80
+                self.db.commit()
+
+                # 4. 提取封面 (90%)
+                cover_path = ""
+                if job.cover_config:
+                    cover_path = os.path.join(tmpdir, "cover.jpg")
+                    cover_cmd = build_cover_extract_command(job.cover_config, cover_path)
+                    cover_cmd = cover_cmd.replace("INPUT_VIDEO", output_video_path)
+                    cover_exit = os.system(cover_cmd)
+                    if cover_exit != 0:
+                        logger.warning("封面提取失败，跳过: %s", cover_cmd)
+                        cover_path = ""
+
+                job.progress = 90
+                self.db.commit()
+
+                # 5. 上传到 OSS (95%)
+                output_video_url = self._upload_to_oss(output_video_path, f"ai-avatar/{job_id}/output.mp4")
+                job.output_video_url = output_video_url
+
+                # 封面：优先复用智能剪辑的 MediaKit 抽帧 + 质量评分选最佳帧；
+                # MediaKit 不可用时回退到 FFmpeg 已按 cover_config 抽取的 cover_path
+                smart_cover_url = ""
+                if output_video_url:
+                    try:
+                        from app.services.ai_avatar_cover_service import (
+                            generate_smart_cover,
+                        )
+
+                        smart_cover_url = generate_smart_cover(output_video_url, job_id=job_id, max_frames=5)
+                    except Exception:
+                        logger.warning("智能封面(MediaKit)失败，回退 FFmpeg 封面 job_id=%s", job_id, exc_info=True)
+
+                if smart_cover_url:
+                    job.output_cover_url = smart_cover_url
+                elif cover_path:
+                    output_cover_url = self._upload_to_oss(cover_path, f"ai-avatar/{job_id}/cover.jpg")
+                    job.output_cover_url = output_cover_url
+
+                # 获取输出视频时长
+                job.output_duration = lipsync_job.output_duration
+                job.progress = 95
+                self.db.commit()
+
+            # 6. 完成
+            job.status = "completed"
+            job.progress = 100
+            job.completed_at = datetime.now(timezone.utc)
+            job.updated_at = datetime.now(timezone.utc)
+            self.db.commit()
+            logger.info("渲染任务完成: %s", job_id)
+
+        except AiAvatarRenderError as exc:
+            job.status = "failed"
+            job.error_message = str(exc)
+            job.updated_at = datetime.now(timezone.utc)
+            self.db.commit()
+            logger.error("渲染任务失败 [%s]: %s", job_id, exc)
+        except Exception as exc:
+            job.status = "failed"
+            job.error_message = f"渲染异常: {str(exc)}"
+            job.updated_at = datetime.now(timezone.utc)
+            self.db.commit()
+            logger.exception("渲染任务异常 [%s]", job_id)
+
+    def _download_video(self, url: str) -> str:
+        """下载视频到临时文件."""
+        import httpx
+
+        tmp = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False)
+        try:
+            with httpx.Client(timeout=120) as client:
+                resp = client.get(url)
+                resp.raise_for_status()
+                tmp.write(resp.content)
+            return tmp.name
+        except Exception:
+            if os.path.exists(tmp.name):
+                os.unlink(tmp.name)
+            raise
+
+    def _build_ffmpeg_command(
+        self,
+        *,
+        input_video: str,
+        b_roll_segments: list[dict[str, Any]],
+        filter_complex: str,
+        final_label: Optional[str],
+        output_path: str,
+    ) -> str:
+        """构建 FFmpeg 命令."""
+        # 输入文件
+        inputs = f"-i {input_video}"
+        for seg in b_roll_segments:
+            asset_url = seg.get("asset_url", "")
+            if asset_url:
+                inputs += f" -i {asset_url}"
+
+        # 滤镜
+        if filter_complex and final_label:
+            filter_arg = f'-filter_complex "{filter_complex}" -map "[{final_label}]"'
+        elif filter_complex:
+            filter_arg = f'-filter_complex "{filter_complex}"'
+        else:
+            filter_arg = ""
+
+        return f"ffmpeg {inputs} {filter_arg} -c:v libx264 -preset fast -crf 23 -y {output_path}"
+
+    def _upload_to_oss(self, local_path: str, oss_key: str) -> str:
+        """上传文件到 OSS，返回 URL.
+
+        使用 SharedStorageService 统一存储服务。
+        """
+        storage = get_shared_storage_service()
+        url = storage.upload_file_smart(local_path, oss_key)
+        if url is None:
+            raise AiAvatarRenderError(
+                f"上传文件到 OSS 失败: {oss_key}",
+                code="OSSUploadFailed",
+            )
+        logger.info("上传文件到 OSS 成功: %s -> %s", local_path, url)
+        return url

apps/api/app/services/edit_plan_service.py

@@ -789,20 +789,22 @@ class EditPlanService:
         if plan and hasattr(plan, "config") and plan.config:
             rhythm_template = plan.config.get("rhythm_template")
 
+        # #1768：先获取素材时长，传入 plan_clip_durations 用于最大片段钳制
+        asset_ids = [c.asset_id for c in clips if c.asset_id]
+        durations = self.get_asset_durations(asset_ids)
+        asset_durations_for_plan = [durations.get(c.asset_id, 0.0) for c in clips]
+
         target = plan_clip_durations(
             len(clips),
             voice,
             transition_effects=[c.transition_effect for c in clips],
             transition_durations=[float(c.transition_duration or 0.0) for c in clips],
             rhythm_template=rhythm_template,
+            asset_durations=asset_durations_for_plan,
         )
         if not target:
             return None
 
-        # 素材时长（短素材起点钳 0）
-        asset_ids = [c.asset_id for c in clips if c.asset_id]
-        durations = self.get_asset_durations(asset_ids)
-
         clips_data: list[dict] = []
         for i, c in enumerate(clips):
             dur = float(target[i])
@@ -932,6 +934,17 @@ class EditPlanService:
                 rhythm_templates_for_variants.append(template)
                 logger.info("变体 %d 节奏模板: plan=%s template=%s", idx, plan_ids[idx], template)
 
+        # #1767：BGM 池差异化分配（让批量变体使用不同 BGM / 段落 / 音量）
+        from packages.domain.bgm_pool import allocate_bgm_pool_for_variants
+
+        source_bgm_config = {}
+        source_plan = self.get_plan(source_plan_id)
+        if source_plan and source_plan.config:
+            source_bgm_config = source_plan.config.get("bgm", {}) or {}
+
+        variant_seeds_for_bgm = [rng.randint(0, 999999) for _ in plan_ids]
+        bgm_pool_assignments = allocate_bgm_pool_for_variants(source_bgm_config, variant_seeds_for_bgm)
+
         # 为每个变体生成独立视觉扰动参数（让批量视频画面本身更不同）
         from packages.domain.variant_plan_selector import generate_visual_perturbation
 
@@ -950,8 +963,20 @@ class EditPlanService:
 
                 pixel_pert = generate_pixel_perturbation(rng)
                 config_update["pixel_perturbation"] = pixel_pert
+                # #1767：写入 BGM 池分配（覆盖 bgm 配置中的 preset_id / audio_offset / volume_adjust_db）
+                if idx < len(bgm_pool_assignments):
+                    existing_bgm = dict((source_plan.config or {}).get("bgm", {}) or {})
+                    existing_bgm.update(bgm_pool_assignments[idx])
+                    config_update["bgm"] = existing_bgm
                 self.update_plan_config(pid, config_update)
-                logger.info("变体 %d 视觉扰动+像素扰动: plan=%s vis=%s pix=%s", idx, pid, perturbation, pixel_pert)
+                logger.info(
+                    "变体 %d 视觉扰动+像素扰动+BGM池: plan=%s vis=%s pix=%s bgm=%s",
+                    idx,
+                    pid,
+                    perturbation,
+                    pixel_pert,
+                    bgm_pool_assignments[idx] if idx < len(bgm_pool_assignments) else None,
+                )
             except Exception:
                 logger.exception("变体 %d 视觉扰动生成失败（不阻断）: plan=%s", idx, pid)
 
@@ -1187,7 +1212,7 @@ class EditPlanService:
         config_asset_ids_count = len((plan.config or {}).get("asset_ids", []))
         clips_with_asset_count = sum(1 for c in clips if c.asset_id)
         logger.info(
-            "can_generate 诊断: plan=%s status=%s total_clips=%d " "clips_with_asset=%d config_asset_ids_count=%d",
+            "can_generate 诊断: plan=%s status=%s total_clips=%d clips_with_asset=%d config_asset_ids_count=%d",
             plan_id,
             plan.status,
             len(clips),
@@ -1199,7 +1224,7 @@ class EditPlanService:
             config_asset_ids = (plan.config or {}).get("asset_ids", [])
             if config_asset_ids:
                 logger.warning(
-                    "can_generate 最后防线触发: plan=%s clips=%d 均无素材，" "从 config.asset_ids(%d个) 自动分配",
+                    "can_generate 最后防线触发: plan=%s clips=%d 均无素材，从 config.asset_ids(%d个) 自动分配",
                     plan_id,
                     len(clips),
                     len(config_asset_ids),
@@ -1231,7 +1256,7 @@ class EditPlanService:
                     return False, "没有可渲染的就绪片段，自动修复后仍未分配素材"
             else:
                 logger.warning(
-                    "can_generate 失败: plan=%s clips=%d 均无素材，" "且 config.asset_ids 为空，无法自动修复",
+                    "can_generate 失败: plan=%s clips=%d 均无素材，且 config.asset_ids 为空，无法自动修复",
                     plan_id,
                     len(clips),
                 )

apps/api/app/services/edit_template_service.py

@@ -34,6 +34,17 @@ from packages.domain.template_clip_converter import (
 logger = logging.getLogger(__name__)
 
 
+class TemplateNotFoundError(Exception):
+    """模板不存在、已删除或当前用户无权访问.
+
+    与"模板存在但无片段配置"区分：路由层应映射为 HTTP 404。
+    """
+
+    def __init__(self, template_id: str) -> None:
+        self.template_id = template_id
+        super().__init__(f"模板不存在: {template_id}")
+
+
 class EditTemplateService:
     """模板管理服务
 
@@ -217,7 +228,14 @@ class EditTemplateService:
         skip: int = 0,
         limit: int = 100,
     ) -> List[TemplateClipConfig]:
-        """列出模板的片段配置"""
+        """列出模板的片段配置
+
+        注意：本方法要求模板存在于新表 ``edit_templates``（全局模板库），
+        主要服务于新模板系统的写入/发布路径。用户自建模板存放在旧表
+        ``templates``，不在 ``edit_templates`` 中，读取其片段配置请改用
+        :meth:`list_clip_configs_for_editor`，后者直接读取片段配置主表
+        ``template_clip_configs``，不依赖新模板主表、也不靠异常降级。
+        """
         # 确保模板存在
         self.get_template_or_raise(template_id)
         return self._clip_config_repo.list_by_template(
@@ -227,6 +245,52 @@ class EditTemplateService:
             limit=limit,
         )
 
+    def list_clip_configs_for_editor(
+        self,
+        template_id: str,
+        user_id: str,
+        *,
+        clip_type: Optional[ClipType] = None,
+        skip: int = 0,
+        limit: int = 100,
+    ) -> List[TemplateClipConfig]:
+        """编辑器读取模板片段配置的单一数据源入口.
+
+        片段配置主表是 ``template_clip_configs``（直接读取，不抛异常、不降级）。
+        模板主表按双表现状显式判定，不使用 try/except 控制流：
+
+        1. 用户自建模板在旧表 ``templates``（归属 user_id）→ 校验归属与未删除后直接读；
+        2. 全局模板在新表 ``edit_templates``（无 user_id，全局可读）→ 直接读；
+        3. 两者都没有 → 模板不存在/无权限，抛 :class:`TemplateNotFoundError`。
+
+        Args:
+            template_id: 模板 ID
+            user_id: 当前登录用户 ID（用于旧表模板归属校验）
+
+        Raises:
+            TemplateNotFoundError: 模板不存在、已删除或不归属于当前用户。
+        """
+        # 1) 用户自建模板（旧表 templates，归属 user_id）
+        if self._clip_config_repo.template_owned_by(template_id, user_id):
+            return self._clip_config_repo.list_by_template(
+                template_id,
+                clip_type=clip_type,
+                skip=skip,
+                limit=limit,
+            )
+
+        # 2) 全局模板（新表 edit_templates，无 user_id，全局可读）
+        if self._template_repo.get(template_id) is not None:
+            return self._clip_config_repo.list_by_template(
+                template_id,
+                clip_type=clip_type,
+                skip=skip,
+                limit=limit,
+            )
+
+        # 3) 两表都没有：不存在 / 已删除 / 无权限
+        raise TemplateNotFoundError(template_id)
+
     def get_clip_config(self, config_id: str) -> Optional[TemplateClipConfig]:
         """获取片段配置详情"""
         return self._clip_config_repo.get(config_id)

apps/api/app/services/lipsync_service.py

@@ -0,0 +1,338 @@
+"""对口型 Service — #1796 MediaKit 对口型业务逻辑, #1809 参数调整.
+
+职责：
+- 创建/查询对口型任务
+- 双输入模式：TTS 直生（voice_id + script_text，内部先合成音频转存 OSS）或直接音频（audio_url）
+- 调用 MediaKit 客户端提交异步任务
+- 轮询更新任务状态（中间状态同步 DB，成片转存自家 OSS）
+- 用户隔离（每个用户只能操作自己的任务）
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+from app.services.mediakit_client import (
+    STATUS_COMPLETED,
+    STATUS_FAILED,
+    STATUS_RUNNING,
+    MediaKitClient,
+    MediaKitError,
+    get_mediakit_client,
+)
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.models import LipsyncJobModel
+from packages.application.cosyvoice_service import CosyVoiceError, normalize_emotion
+from packages.shared.storage import get_shared_storage_service
+from packages.shared.url_security import ALLOWED_AUDIO_MIME_TYPES, safe_download_bytes
+
+logger = logging.getLogger(__name__)
+
+
+class LipsyncService:
+    """对口型任务 Service."""
+
+    def __init__(
+        self,
+        db: Session,
+        client: Optional[MediaKitClient] = None,
+        cosyvoice_service=None,
+        voice_clone_repo=None,
+    ):
+        self.db = db
+        self.client = client or get_mediakit_client()
+        self._cosyvoice = cosyvoice_service
+        self._voice_clone_repo = voice_clone_repo
+
+    def _get_cosyvoice(self):
+        """延迟获取 CosyVoiceService（与 tts 路由一致，含 OSS 预签名配置）."""
+        if self._cosyvoice is None:
+            from app.dependencies import get_cosyvoice_service
+
+            self._cosyvoice = get_cosyvoice_service()
+        return self._cosyvoice
+
+    def _resolve_voice_id(self, voice_id: str, user_id: str) -> str:
+        """将克隆音色 profile UUID 解析为 CosyVoice voice_id。
+
+        与 /tts/synthesize 保持一致：命中 profile → 校验归属 → 返回其 voice_id；
+        未命中（预置音色 ID 或克隆 CosyVoice voice_id）原样返回。
+        """
+        if not voice_id:
+            return ""
+        if self._voice_clone_repo is None:
+            try:
+                from app.dependencies import get_voice_clone_profile_repository
+
+                self._voice_clone_repo = get_voice_clone_profile_repository(self.db)
+            except Exception:
+                return voice_id
+        try:
+            profile = self._voice_clone_repo.get(voice_id)
+        except Exception:
+            return voice_id
+        if profile is None:
+            return voice_id
+        if getattr(profile, "user_id", "") != user_id:
+            raise MediaKitError("无权访问该音色", code="VoiceForbidden")
+        if not getattr(profile, "voice_id", ""):
+            raise MediaKitError("音色克隆尚未完成，请稍后再试", code="VoiceNotReady")
+        return profile.voice_id
+
+    def _synthesize_and_persist_audio(
+        self,
+        *,
+        user_id: str,
+        job_id: str,
+        voice_id: str,
+        script_text: str,
+        speed: float,
+        emotion: str,
+    ) -> str:
+        """TTS 直生：调 CosyVoice 合成音频并转存 OSS，返回可公网访问的音频 URL.
+
+        Raises:
+            MediaKitError: 合成失败
+        """
+        actual_voice_id = self._resolve_voice_id(voice_id, user_id)
+        cosyvoice = self._get_cosyvoice()
+        try:
+            result = cosyvoice.submit_synthesize_task(
+                text=script_text,
+                voice_id=actual_voice_id,
+                speed=speed,
+                emotion=normalize_emotion(emotion),
+            )
+        except CosyVoiceError as exc:
+            raise MediaKitError(f"TTS 合成失败: {exc}", code="TTSSynthesisFailed") from exc
+        except ValueError as exc:
+            raise MediaKitError(f"TTS 参数错误: {exc}", code="TTSInvalidParam") from exc
+
+        temp_url = result.get("audio_url", "")
+        if not temp_url:
+            raise MediaKitError("TTS 未返回音频 URL", code="TTSNoAudio")
+
+        # 转存到自家 OSS，避免临时 URL 过期导致 MediaKit 拉取失败
+        try:
+            audio_data = safe_download_bytes(
+                temp_url,
+                purpose="lipsync_tts_audio",
+                allowed_mime_types=ALLOWED_AUDIO_MIME_TYPES,
+                timeout=60.0,
+            )
+            storage = get_shared_storage_service()
+            storage_key = f"lipsync-tts/{user_id}/{job_id}.mp3"
+            permanent_url = storage.upload_file(io.BytesIO(audio_data), storage_key, content_type="audio/mpeg")
+            logger.info("对口型 TTS 音频已转存 OSS: job_id=%s key=%s", job_id, storage_key)
+            return permanent_url
+        except Exception as exc:
+            logger.warning("TTS 音频转存 OSS 失败，回退临时 URL: job_id=%s err=%s", job_id, exc)
+            return temp_url
+
+    # ── 创建任务 ──────────────────────────────────────────────────────────
+
+    def create_job(
+        self,
+        *,
+        user_id: str,
+        video_url: str,
+        audio_url: str = "",
+        voice_id: str = "",
+        script_text: str = "",
+        speed: float = 1.0,
+        emotion: str = "",
+        enable_video_loop: bool = False,
+        project_id: str = "",
+    ) -> LipsyncJobModel:
+        """创建对口型任务并提交到 MediaKit.
+
+        两种输入模式：
+        - TTS 直生：voice_id + script_text（audio_url 留空），后端先合成音频
+        - 直接音频：提供 audio_url
+
+        Raises:
+            MediaKitError: TTS 合成或 MediaKit 提交失败
+        """
+        # 0. TTS 直生模式：先合成音频（在创建 DB 记录之前完成，失败直接抛出）
+        if not audio_url:
+            if not (voice_id and script_text):
+                raise MediaKitError(
+                    "必须提供 audio_url 或 voice_id+script_text",
+                    code="InvalidInput",
+                )
+            # 预合成：用临时 job_id 命名 OSS 对象
+            pre_job_id = str(uuid.uuid4())
+            audio_url = self._synthesize_and_persist_audio(
+                user_id=user_id,
+                job_id=pre_job_id,
+                voice_id=voice_id,
+                script_text=script_text,
+                speed=speed,
+                emotion=emotion,
+            )
+
+        # 1. 创建数据库记录
+        job_id = str(uuid.uuid4())
+        job = LipsyncJobModel(
+            id=job_id,
+            user_id=user_id,
+            project_id=project_id,
+            video_url=video_url,
+            audio_url=audio_url,
+            enable_video_loop=enable_video_loop,
+            voice_id=voice_id or "",
+            script_text=script_text or "",
+            speed=speed,
+            emotion=normalize_emotion(emotion),
+            status="pending",
+        )
+        self.db.add(job)
+        self.db.flush()
+
+        # 3. 提交到 MediaKit
+        try:
+            result = self.client.submit_lipsync(
+                video_url=video_url,
+                audio_url=audio_url,
+                enable_video_loop=enable_video_loop,
+                client_token=job_id,  # 幂等控制
+            )
+            job.mediakit_task_id = result["task_id"]
+            job.status = "submitted"
+            job.submitted_at = datetime.now(timezone.utc)
+        except MediaKitError as exc:
+            job.status = "failed"
+            job.error_message = str(exc)
+            job.error_code = exc.code
+            logger.error("提交对口型任务失败: %s", exc)
+            raise
+
+        self.db.commit()
+        self.db.refresh(job)
+        return job
+
+    # ── 查询任务 ──────────────────────────────────────────────────────────
+
+    def get_job(self, job_id: str, user_id: str) -> Optional[LipsyncJobModel]:
+        """获取任务详情（用户隔离）."""
+        return (
+            self.db.query(LipsyncJobModel)
+            .filter(LipsyncJobModel.id == job_id, LipsyncJobModel.user_id == user_id)
+            .first()
+        )
+
+    def list_jobs(
+        self,
+        *,
+        user_id: str,
+        project_id: str = "",
+        status: str = "",
+        offset: int = 0,
+        limit: int = 20,
+    ) -> tuple[list[LipsyncJobModel], int]:
+        """获取任务列表（分页 + 用户隔离）."""
+        query = self.db.query(LipsyncJobModel).filter(LipsyncJobModel.user_id == user_id)
+        if project_id:
+            query = query.filter(LipsyncJobModel.project_id == project_id)
+        if status:
+            query = query.filter(LipsyncJobModel.status == status)
+
+        total = query.count()
+        items = query.order_by(LipsyncJobModel.created_at.desc()).offset(offset).limit(limit).all()
+        return items, total
+
+    # ── 更新任务状态（轮询） ──────────────────────────────────────────────
+
+    def refresh_job_status(self, job_id: str, user_id: str) -> Optional[LipsyncJobModel]:
+        """从 MediaKit 拉取最新状态并更新本地记录.
+
+        Returns:
+            更新后的 Job，或 None（任务不存在/不属于该用户）
+        """
+        job = self.get_job(job_id, user_id)
+        if job is None:
+            return None
+
+        # 终态不需要再轮询
+        if job.status in (STATUS_COMPLETED, "failed"):
+            return job
+
+        # 未提交的任务不轮询
+        if not job.mediakit_task_id:
+            return job
+
+        try:
+            status_data = self.client.get_task_status(job.mediakit_task_id)
+        except MediaKitError as exc:
+            logger.error("轮询对口型任务状态失败 [%s]: %s", job_id, exc)
+            return job
+
+        mk_status = status_data.get("status", STATUS_RUNNING)
+        logger.info("MediaKit 对口型状态 [%s]: %s", job_id, mk_status)
+
+        if mk_status == STATUS_COMPLETED:
+            result = status_data.get("result", {})
+            job.status = STATUS_COMPLETED
+            output_url = result.get("video_url", "")
+            # MediaKit 输出为临时 URL，转存自家 OSS 防止过期（失败则回退临时 URL）
+            job.output_video_url = self._persist_output_video(output_url, job_id, user_id)
+            job.output_duration = result.get("duration", 0.0)
+            job.completed_at = datetime.now(timezone.utc)
+        elif mk_status == STATUS_FAILED:
+            error = status_data.get("error", {})
+            job.status = "failed"
+            job.error_message = error.get("message", "任务执行失败")
+            job.error_code = error.get("code", "TaskFailed")
+            job.completed_at = datetime.now(timezone.utc)
+        else:
+            # 中间状态（running/processing/queued 等）同步到 DB，避免前端永远卡在 submitted
+            if isinstance(mk_status, str) and mk_status:
+                job.status = mk_status
+        job.updated_at = datetime.now(timezone.utc)
+        self.db.commit()
+        self.db.refresh(job)
+        return job
+
+    def _persist_output_video(self, temp_url: str, job_id: str, user_id: str) -> str:
+        """将 MediaKit 输出的临时视频 URL 转存到自家 OSS.
+
+        失败时回退返回原始临时 URL，不影响任务完成。
+        """
+        if not temp_url:
+            return ""
+        try:
+            import httpx
+
+            with httpx.Client(timeout=180.0, follow_redirects=True) as client:
+                resp = client.get(temp_url)
+                resp.raise_for_status()
+                data = resp.content
+            storage = get_shared_storage_service()
+            storage_key = f"lipsync-outputs/{user_id}/{job_id}.mp4"
+            permanent_url = storage.upload_file(io.BytesIO(data), storage_key, content_type="video/mp4")
+            logger.info("对口型输出视频已转存 OSS: job_id=%s key=%s", job_id, storage_key)
+            return permanent_url or temp_url
+        except Exception as exc:
+            logger.warning("对口型输出视频转存 OSS 失败，回退临时 URL: job_id=%s err=%s", job_id, exc)
+            return temp_url
+
+    # ── 取消任务 ──────────────────────────────────────────────────────────
+
+    def cancel_job(self, job_id: str, user_id: str) -> Optional[LipsyncJobModel]:
+        """取消任务（仅 pending/submitted 状态可取消）."""
+        job = self.get_job(job_id, user_id)
+        if job is None:
+            return None
+
+        if job.status in ("pending", "submitted"):
+            job.status = "cancelled"
+            job.updated_at = datetime.now(timezone.utc)
+            self.db.commit()
+            self.db.refresh(job)
+
+        return job

apps/api/app/services/mediakit_client.py

@@ -0,0 +1,243 @@
+"""MediaKit 客户端 — 封装火山引擎 AI MediaKit 对口型 API.
+
+接口文档：https://docs.volcengine.com/docs/6448/2656064
+
+异步任务流程：
+1. POST /api/v1/tools/lip-sync  提交对口型任务 → 返回 task_id
+2. GET  /api/v1/tasks/{task_id} 轮询任务状态 → running/completed/failed
+3. completed 时 result.video_url 为口型对齐视频（临时链接 24h 有效）
+
+设计原则：
+- API Key 从配置读取（settings.mediakit_api_key）
+- 未配置 API Key 时所有方法返回降级响应，不阻塞主流程
+- HTTP 超时/网络异常统一包装为 MediaKitError
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+import httpx
+
+from packages.config import get_api_settings
+
+logger = logging.getLogger(__name__)
+
+# ── 任务状态常量 ──────────────────────────────────────────────────────────
+STATUS_RUNNING = "running"
+STATUS_COMPLETED = "completed"
+STATUS_FAILED = "failed"
+
+
+class MediaKitError(Exception):
+    """MediaKit API 调用异常."""
+
+    def __init__(self, message: str, code: str = "", request_id: str = ""):
+        self.code = code
+        self.request_id = request_id
+        super().__init__(message)
+
+
+class MediaKitClient:
+    """火山引擎 AI MediaKit 对口型 API 客户端.
+
+    用法：
+        client = get_mediakit_client()
+        result = client.submit_lipsync(video_url="...", audio_url="...")
+        task_id = result["task_id"]
+
+        status = client.get_task_status(task_id)
+        # {"status": "completed", "result": {"video_url": "...", "duration": 60.5}}
+    """
+
+    def __init__(self) -> None:
+        settings = get_api_settings()
+        self._api_key = settings.mediakit_api_key
+        self._base_url = settings.mediakit_base_url.rstrip("/")
+        self._timeout = settings.mediakit_timeout
+
+    @property
+    def is_available(self) -> bool:
+        """是否已配置 API Key（未配置时自动降级）."""
+        return bool(self._api_key)
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+
+    # ── 提交对口型任务 ────────────────────────────────────────────────────
+
+    def submit_lipsync(
+        self,
+        *,
+        video_url: str,
+        audio_url: str,
+        enable_video_loop: bool = False,
+        callback_url: Optional[str] = None,
+        callback_args: Optional[str] = None,
+        client_token: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """提交视频口型对齐任务.
+
+        Args:
+            video_url: 人物视频 URL（MP4，≤30min，单人真人）
+            audio_url: 驱动音频 URL（mp3/aac/wav/m4a/flac）
+            enable_video_loop: 音频长于视频时是否循环画面
+            callback_url: 任务完成回调 URL
+            callback_args: 回调时原样返回的自定义参数
+            client_token: 幂等控制 token
+
+        Returns:
+            {"success": True, "task_id": "...", "request_id": "..."}
+
+        Raises:
+            MediaKitError: API 调用失败
+        """
+        if not self.is_available:
+            raise MediaKitError("MediaKit API Key 未配置", code="NotConfigured")
+
+        payload: dict[str, Any] = {
+            "video_url": video_url,
+            "audio_url": audio_url,
+        }
+        if enable_video_loop:
+            payload["enable_video_loop"] = True
+        if callback_url:
+            payload["callback_url"] = callback_url
+        if callback_args:
+            payload["callback_args"] = callback_args[:512]  # API 限制 512 字节
+        if client_token:
+            payload["client_token"] = client_token[:64]  # API 限制 64 字符
+
+        try:
+            with httpx.Client(timeout=self._timeout) as client:
+                resp = client.post(
+                    f"{self._base_url}/tools/lip-sync",
+                    headers=self._headers(),
+                    json=payload,
+                )
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.TimeoutException as exc:
+            raise MediaKitError(f"MediaKit API 超时 ({self._timeout}s)", code="Timeout") from exc
+        except httpx.HTTPStatusError as exc:
+            body = exc.response.text[:500]
+            raise MediaKitError(
+                f"MediaKit API HTTP {exc.response.status_code}: {body}",
+                code="HttpError",
+            ) from exc
+        except httpx.RequestError as exc:
+            raise MediaKitError(f"MediaKit API 网络错误: {exc}", code="NetworkError") from exc
+        except Exception as exc:
+            raise MediaKitError(f"MediaKit API 未知错误: {exc}", code="UnknownError") from exc
+
+        if not data.get("success"):
+            error = data.get("error", {})
+            raise MediaKitError(
+                error.get("message", "提交任务失败"),
+                code=error.get("code", "SubmitFailed"),
+                request_id=data.get("request_id", ""),
+            )
+
+        return {
+            "success": True,
+            "task_id": data["task_id"],
+            "request_id": data.get("request_id", ""),
+        }
+
+    # ── 查询任务状态 ──────────────────────────────────────────────────────
+
+    def get_task_status(self, task_id: str) -> dict[str, Any]:
+        """查询异步任务状态和结果.
+
+        Args:
+            task_id: 提交任务时返回的任务 ID
+
+        Returns:
+            {
+                "success": True,
+                "task_id": "...",
+                "status": "running" | "completed" | "failed",
+                "result": {"video_url": "...", "duration": 60.5} | None,
+                "error": {"code": "...", "message": "..."} | None,
+                "created_at": 1777291767,
+                "finished_at": 1777291851 | None,
+                "expires_at": 1777464650 | None,
+            }
+
+        Raises:
+            MediaKitError: API 调用失败
+        """
+        if not self.is_available:
+            raise MediaKitError("MediaKit API Key 未配置", code="NotConfigured")
+
+        try:
+            with httpx.Client(timeout=self._timeout) as client:
+                resp = client.get(
+                    f"{self._base_url}/tasks/{task_id}",
+                    headers=self._headers(),
+                )
+                resp.raise_for_status()
+                data = resp.json()
+        except httpx.TimeoutException as exc:
+            raise MediaKitError(f"MediaKit API 超时 ({self._timeout}s)", code="Timeout") from exc
+        except httpx.HTTPStatusError as exc:
+            body = exc.response.text[:500]
+            raise MediaKitError(
+                f"MediaKit API HTTP {exc.response.status_code}: {body}",
+                code="HttpError",
+            ) from exc
+        except httpx.RequestError as exc:
+            raise MediaKitError(f"MediaKit API 网络错误: {exc}", code="NetworkError") from exc
+        except Exception as exc:
+            raise MediaKitError(f"MediaKit API 未知错误: {exc}", code="UnknownError") from exc
+
+        if not data.get("success"):
+            error = data.get("error", {})
+            raise MediaKitError(
+                error.get("message", "查询任务失败"),
+                code=error.get("code", "QueryFailed"),
+                request_id=data.get("request_id", ""),
+            )
+
+        result: dict[str, Any] = {
+            "success": True,
+            "task_id": data.get("task_id", task_id),
+            "status": data.get("status", STATUS_RUNNING),
+            "result": data.get("result"),
+            "created_at": data.get("created_at"),
+            "finished_at": data.get("finished_at"),
+            "expires_at": data.get("expires_at"),
+        }
+
+        # 失败时提取错误信息
+        if data.get("status") == STATUS_FAILED:
+            error_obj = data.get("error", {})
+            result["error"] = {
+                "code": error_obj.get("code", "TaskFailed"),
+                "message": error_obj.get("message", "任务执行失败"),
+            }
+
+        return result
+
+
+# ── 单例 ──────────────────────────────────────────────────────────────────
+
+_client: Optional[MediaKitClient] = None
+
+
+def get_mediakit_client() -> MediaKitClient:
+    """获取 MediaKit 客户端单例."""
+    global _client
+    if _client is None:
+        _client = MediaKitClient()
+    return _client
+
+
+def reset_mediakit_client() -> None:
+    """重置客户端（测试用）."""
+    global _client
+    _client = None

apps/api/app/services/script_service.py

@@ -0,0 +1,109 @@
+"""ScriptService — Issue #1795 口播文案库 CRUD.
+
+纯 Service 层封装，routes 直接调用。
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.models import ScriptModel
+
+
+class ScriptNotFoundError(Exception):
+    """文案不存在或不属于当前用户."""
+
+
+class ScriptService:
+    """口播文案 CRUD."""
+
+    def __init__(self, db: Session) -> None:
+        self.db = db
+
+    # ── list ──────────────────────────────────────────────────────────────
+
+    def list_scripts(
+        self,
+        user_id: str,
+        skip: int = 0,
+        limit: int = 50,
+        tag: Optional[str] = None,
+    ) -> tuple[list[ScriptModel], int]:
+        """返回 (items, total)."""
+        q = self.db.query(ScriptModel).filter(ScriptModel.user_id == user_id)
+        if tag:
+            # JSON 数组包含查询
+            q = q.filter(ScriptModel.tags.contains([tag]))
+        total = q.count()
+        items = q.order_by(ScriptModel.created_at.desc()).offset(skip).limit(limit).all()
+        return items, total
+
+    # ── create ────────────────────────────────────────────────────────────
+
+    def create_script(
+        self,
+        user_id: str,
+        title: str,
+        content: str = "",
+        segments: list | None = None,
+        tags: list | None = None,
+    ) -> ScriptModel:
+        script = ScriptModel(
+            id=str(uuid.uuid4()),
+            user_id=user_id,
+            title=title,
+            content=content,
+            segments=segments if segments is not None else [],
+            tags=tags if tags is not None else [],
+        )
+        self.db.add(script)
+        self.db.commit()
+        self.db.refresh(script)
+        return script
+
+    # ── get ───────────────────────────────────────────────────────────────
+
+    def get_script(self, script_id: str, user_id: str) -> ScriptModel:
+        script = self.db.query(ScriptModel).filter(ScriptModel.id == script_id, ScriptModel.user_id == user_id).first()
+        if script is None:
+            raise ScriptNotFoundError(f"Script {script_id} not found")
+        return script
+
+    # ── update ────────────────────────────────────────────────────────────
+
+    def update_script(
+        self,
+        script_id: str,
+        user_id: str,
+        title: Optional[str] = None,
+        content: Optional[str] = None,
+        segments: Optional[list] = None,
+        tags: Optional[list] = None,
+    ) -> ScriptModel:
+        script = self.get_script(script_id, user_id)
+        if title is not None:
+            script.title = title
+        if content is not None:
+            script.content = content
+        if segments is not None:
+            script.segments = segments
+        if tags is not None:
+            script.tags = tags
+        script.updated_at = datetime.now(timezone.utc)
+        self.db.commit()
+        self.db.refresh(script)
+        return script
+
+    # ── delete ────────────────────────────────────────────────────────────
+
+    def delete_script(self, script_id: str, user_id: str) -> bool:
+        script = self.db.query(ScriptModel).filter(ScriptModel.id == script_id, ScriptModel.user_id == user_id).first()
+        if script is None:
+            return False
+        self.db.delete(script)
+        self.db.commit()
+        return True

apps/api/app/services/video_compose_service.py

@@ -39,6 +39,9 @@ from packages.domain.video_filter_builder import (
 )
 from packages.domain.video_filter_builder import build_concat_filter as _build_concat_filter_func
 from packages.domain.video_filter_builder import build_filter_complex as _build_filter_complex
+from packages.domain.video_filter_builder import (
+    build_title_drawtext_filter,
+)
 from packages.domain.video_filter_builder import build_xfade_filter as _build_xfade_filter_func
 from packages.domain.video_filter_builder import chain_filters as _chain_filters_func
 from packages.domain.video_filter_builder import has_audio as _has_audio_func
@@ -248,6 +251,27 @@ class VideoComposeService:
             transitions=[c.transition_effect for c in ready_clips],
         )
 
+        # ── #1789 标题 drawtext 滤镜叠加 ──
+        # 从 plan.config 读取 title_config，生成 drawtext 滤镜链入 filter_complex
+        title_cfg = (plan.config or {}).get("title", {}) or {}
+        if not isinstance(title_cfg, dict):
+            title_cfg = {}
+        # 同时兼容 plan.config["title_config"]（API 回写路径）
+        if not title_cfg.get("text") and not title_cfg.get("content"):
+            title_cfg_alt = (plan.config or {}).get("title_config", {}) or {}
+            if isinstance(title_cfg_alt, dict) and (title_cfg_alt.get("text") or title_cfg_alt.get("content")):
+                title_cfg = title_cfg_alt
+        drawtext_filter = build_title_drawtext_filter(title_cfg, output_width, output_height)
+        if drawtext_filter:
+            # 将最终输出标签从 [outv] 改为 [composed]，再链入 drawtext → [outv]
+            filter_complex = filter_complex.replace("[outv]", "[composed]")
+            filter_complex += f";[composed]{drawtext_filter}[outv]"
+            logger.info(
+                "[#1789] 标题 drawtext 滤镜已注入: plan_id=%s text=%s",
+                plan_id,
+                (title_cfg.get("text") or title_cfg.get("content") or "")[:30],
+            )
+
         # 构建完整命令
         command: list[str] = ["ffmpeg", "-y"]
 

apps/api/app/tasks/__init__.py

@@ -0,0 +1 @@
+"""Celery 异步任务模块."""

apps/api/app/tasks/ai_avatar_render.py

@@ -0,0 +1,48 @@
+"""AI数字人渲染 Celery 异步任务 — #1798."""
+
+from __future__ import annotations
+
+import logging
+
+from app.core.celery_app import celery_app
+from app.dependencies import get_db_session
+
+logger = logging.getLogger(__name__)
+
+
+@celery_app.task(bind=True, name="ai_avatar_render.execute", max_retries=2)
+def execute_ai_avatar_render(self, job_id: str) -> dict:
+    """执行 AI 数字人渲染管线.
+
+    进度更新:
+    - 0%: 任务开始
+    - 20%: 下载对口型视频完成
+    - 40%: 滤镜链构建完成
+    - 80%: FFmpeg 渲染完成
+    - 95%: 上传 OSS 完成
+    - 100%: 任务完成
+    """
+    logger.info("开始执行渲染任务: %s", job_id)
+    self.update_state(state="PROCESSING", meta={"progress": 0, "job_id": job_id})
+
+    try:
+        # 获取数据库 session
+        db_gen = get_db_session()
+        db = next(db_gen)
+        try:
+            from app.services.ai_avatar_render_service import AiAvatarRenderService
+
+            service = AiAvatarRenderService(db)
+            service.execute_render(job_id)
+        finally:
+            try:
+                next(db_gen)
+            except StopIteration:
+                pass
+
+        return {"status": "completed", "job_id": job_id}
+
+    except Exception as exc:
+        logger.exception("渲染任务执行异常 [%s]: %s", job_id, exc)
+        self.update_state(state="FAILED", meta={"progress": 0, "error": str(exc)})
+        raise

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

@@ -5,10 +5,22 @@ import apiClient from "../client"
 import { getOrCreateDefaultProject } from "../projects"
 import type { AssetLibraryItem } from "./types"
 
-/** 获取当前用户的所有素材库 */
-export const getAssetLibraries = async (): Promise<AssetLibraryItem[]> => {
-  const response = await apiClient.get("/asset-libraries")
-  return response.data.items || []
+/**
+ * 获取当前用户的素材库
+ *
+ * @param kind 可选，按素材库类型过滤（video/voice/image）。
+ *   后端 GET /asset-libraries 支持 kind 查询参数；这里同时在前端再按返回数据的
+ *   kind 字段兜底过滤一次，保证旧后端（忽略未知 query 参数）也不会把其他类型的库
+ *   混进来（#1777：视频选择器只展示视频库）。
+ */
+export const getAssetLibraries = async (
+  kind?: AssetLibraryItem["kind"],
+): Promise<AssetLibraryItem[]> => {
+  const response = await apiClient.get<{ items?: AssetLibraryItem[] }>("/asset-libraries", {
+    params: kind ? { kind } : undefined,
+  })
+  const items = response.data.items || []
+  return kind ? items.filter((lib) => lib.kind === kind) : items
 }
 
 /** 创建素材库（自动获取或创建默认项目以提供 project_id） */

apps/web/src/api/client.ts

@@ -55,6 +55,19 @@ apiClient.interceptors.response.use(
   async (error: AxiosError<{ detail?: string; message?: string; msg?: string }>) => {
     const originalRequest = error.config as InternalAxiosRequestConfig & {
       _retry?: boolean
+      /**
+       * 调用方自行处理错误提示时置 true：拦截器跳过全局 message 弹窗（#1777）。
+       * 例如失效模板自动回退时，调用方会弹「原模板已失效，已自动切换」，
+       * 不再叠加后端原始错误文案。错误仍会 reject，不影响 catch 逻辑。
+       */
+      _silentErrorToast?: boolean
+    }
+
+    // 调用方声明自行处理提示：标记为已展示，跳过下面所有全局 message 弹窗
+    if (originalRequest?._silentErrorToast) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ;(error as any).__msgShown = true
+      return Promise.reject(error)
     }
 
     // 401 → 尝试刷新 Token

apps/web/src/api/editing-planner/templates.ts

@@ -12,17 +12,25 @@ import type {
   ListCategoriesResponse,
 } from "./types"
 
-/** 获取模板列表 */
+/** 获取模板列表
+ *
+ * valid_only=true 时请求后端仅返回已配置片段的模板（剪辑页选模板使用，
+ * 避免选中无片段配置的模板导致 from-assets 400，#1769/#1772）；
+ * 后端尚未支持该参数时会忽略未知 query 字段，前端再按 segments/is_active 兜底过滤。
+ * 模板编辑器/我的模板不传，可查看全部模板（含未配置片段的草稿）。
+ */
 export const getEditingTemplates = async (params?: {
   category?: string
   tag?: string
   skip?: number
   limit?: number
+  validOnly?: boolean
 }): Promise<EditingTemplate[]> => {
   const response = await apiClient.get<ListTemplatesResponse>("/templates", {
     params: {
       skip: params?.skip ?? 0,
       limit: params?.limit ?? 50,
+      ...(params?.validOnly ? { valid_only: true } : {}),
     },
   })
   let list = response.data.items

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

@@ -0,0 +1,2 @@
+export * from "./scripts"
+export * from "./types"

apps/web/src/api/scripts/scripts.ts

@@ -0,0 +1,37 @@
+/**
+ * 文案库 API
+ * 对接后端 /api/v1/scripts（CRUD + 列表解包）
+ */
+import apiClient from "../client"
+import type {
+  ScriptItem,
+  ScriptListResponse,
+  CreateScriptRequest,
+  UpdateScriptRequest,
+} from "./types"
+
+/** 获取文案列表 — 必须解包 items（后端返回 {items,total}）*/
+export const getScripts = async (): Promise<ScriptItem[]> => {
+  const response = await apiClient.get<ScriptListResponse | ScriptItem[]>("/scripts")
+  const data = response.data as unknown
+  if (Array.isArray(data)) return data
+  const items = (data as { items?: ScriptItem[] })?.items
+  return Array.isArray(items) ? items : []
+}
+
+/** 新建文案 */
+export const createScript = async (data: CreateScriptRequest): Promise<ScriptItem> => {
+  const response = await apiClient.post<ScriptItem>("/scripts", data)
+  return response.data
+}
+
+/** 更新文案 */
+export const updateScript = async (id: string, data: UpdateScriptRequest): Promise<ScriptItem> => {
+  const response = await apiClient.put<ScriptItem>(`/scripts/${id}`, data)
+  return response.data
+}
+
+/** 删除文案 */
+export const deleteScript = async (id: string): Promise<void> => {
+  await apiClient.delete(`/scripts/${id}`)
+}

apps/web/src/api/scripts/types.ts

@@ -0,0 +1,24 @@
+/**
+ * 文案库 API — 类型定义
+ * 对接后端 /api/v1/scripts
+ */
+export interface ScriptItem {
+  id: string
+  title: string
+  content: string
+  char_count: number
+  created_at: string
+  updated_at?: string
+}
+
+export interface ScriptListResponse {
+  items: ScriptItem[]
+  total: number
+}
+
+export interface CreateScriptRequest {
+  title: string
+  content: string
+}
+
+export type UpdateScriptRequest = Partial<CreateScriptRequest>

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

@@ -91,7 +91,7 @@ export async function createClipsFromAssets(
   assetIds: string[],
   clipType = "main",
   requiredClipsCount?: number,
-  opts?: { signal?: AbortSignal },
+  opts?: { signal?: AbortSignal; silentErrorToast?: boolean },
 ): Promise<ClipsFromAssetsResponse> {
   const body: Record<string, unknown> = {
     asset_ids: assetIds,
@@ -104,7 +104,12 @@ export async function createClipsFromAssets(
   const response = await apiClient.post<ClipsFromAssetsResponse>(
     `/templates/${templateId}/editor/clips/from-assets`,
     body,
-    { timeout: 60000, signal: opts?.signal },
+    {
+      timeout: 60000,
+      signal: opts?.signal,
+      // _silentErrorToast 由 api/client.ts 响应拦截器读取（抑制全局错误 toast，#1777）
+      ...(opts?.silentErrorToast ? ({ _silentErrorToast: true } as Record<string, unknown>) : {}),
+    },
   )
   return response.data
 }

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

@@ -43,11 +43,17 @@ export async function updateEditPlanClips(
   templateId: string,
   clips: EditPlanClipInput[],
   signal?: AbortSignal,
+  /** 为 true 时抑制全局错误 toast（调用方自行提示，如失效模板回退 #1777） */
+  silentErrorToast?: boolean,
 ): Promise<{ count: number }> {
   const response = await apiClient.put(
     `/templates/${templateId}/editor/clips`,
     { clips },
-    { signal },
+    {
+      signal,
+      // _silentErrorToast 由 api/client.ts 响应拦截器读取（抑制全局错误 toast）
+      ...(silentErrorToast ? ({ _silentErrorToast: true } as Record<string, unknown>) : {}),
+    },
   )
   return response.data
 }

apps/web/src/api/tts/types.ts

@@ -103,6 +103,7 @@ export interface TTSPreviewRequest {
   voice_id: string
   speed?: number
   pitch?: number
+  emotion?: string // 情绪参数：natural/excited/calm/friendly
 }
 
 /** TTS 试听响应 */

apps/web/src/components/layout/MainLayout.css

@@ -5,7 +5,7 @@
      .xx-app-shell          全屏 flex 容器
      ├── header (xx-top-nav) 顶部导航（Header.tsx 管理）
      └── .xx-app-body       水平 flex 行
-         ├── .xx-app-sidebar  左侧侧边栏（240px / 64px 折叠）
+         ├── .xx-app-sidebar  左侧侧边栏（128px / 64px 折叠）
          └── .xx-app-content  主内容区（自适应）
 
    所有尺寸/颜色均使用 global.css 设计系统变量
@@ -31,7 +31,7 @@
 
 /* ── 侧边栏 ───────────────────────────────────────────────── */
 .xx-app-sidebar {
-  width: 240px;
+  width: 128px;
   flex-shrink: 0;
   position: sticky;
   top: 0;
@@ -103,6 +103,12 @@
   padding: var(--space-sm);
 }
 
+/* 展开态（侧边栏 128px）水平 padding 收窄，为菜单文字留出完整一行空间 */
+.xx-app-sidebar:not(.xx-collapsed) .xx-sidebar-content {
+  padding-left: var(--space-xs);
+  padding-right: var(--space-xs);
+}
+
 /* ── 主内容区 ─────────────────────────────────────────────── */
 .xx-app-content {
   flex: 1;
@@ -136,7 +142,7 @@
 
   /* 展开态恢复完整宽度 */
   .xx-app-sidebar:not(.xx-collapsed) {
-    width: 240px;
+    width: 128px;
   }
 
   .xx-app-sidebar:not(.xx-collapsed) .xx-sidebar-toggle {
@@ -159,7 +165,7 @@
     top: 56px; /* 移动端 Header 高度 */
     left: 0;
     bottom: 0;
-    width: 240px;
+    width: 128px;
     transform: translateX(-100%);
     transition: transform var(--transition-slow);
     box-shadow: none;

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

@@ -2,7 +2,7 @@
  * MainLayout - 主布局组件（Task 1.2）
  *
  * 三栏布局：左侧侧边栏 + 顶部导航栏 + 主内容区
- * - 侧边栏：240px 固定宽度，可折叠至 64px 图标栏
+ * - 侧边栏：128px 固定宽度，可折叠至 64px 图标栏
  * - 顶部导航：复用 Header 组件（68px 固定高度）
  * - 主内容区：自适应填充剩余空间
  * - 响应式：移动端（<768px）隐藏侧边栏

apps/web/src/components/layout/Sidebar.css

@@ -30,7 +30,7 @@
 
 /* 分组标题 */
 .xx-sidebar-group-title {
-  padding: var(--space-sm) var(--space-md) var(--space-xs);
+  padding: var(--space-sm) var(--space-sm) var(--space-xs);
   font-size: var(--font-size-xs);
   font-weight: var(--font-weight-semibold);
   color: var(--text-tertiary);
@@ -56,9 +56,9 @@
 .xx-sidebar-menu-item {
   display: flex;
   align-items: center;
-  gap: var(--space-sm);
-  padding: var(--space-sm) var(--space-md);
-  margin: 0 var(--space-xs);
+  gap: var(--space-xs);
+  padding: var(--space-sm) var(--space-xs);
+  margin: 0 var(--space-xxs);
   border-radius: var(--radius-sm);
   cursor: pointer;
   color: var(--text-secondary);
@@ -97,12 +97,12 @@
   align-items: center;
   justify-content: center;
   flex-shrink: 0;
-  width: 36px;
-  height: 36px;
-  border-radius: 10px;
+  width: 28px;
+  height: 28px;
+  border-radius: 8px;
   background: #f1f5f9;
   color: var(--text-secondary);
-  font-size: 18px;
+  font-size: 16px;
   line-height: 1;
   transition: 0.15s ease;
 }
@@ -119,7 +119,9 @@
 /* ── 菜单项文字 ───────────────────────────────────────────── */
 .xx-sidebar-menu-label {
   flex: 1;
+  min-width: 0;
   overflow: hidden;
+  white-space: nowrap;
   text-overflow: ellipsis;
 }
 
@@ -133,8 +135,16 @@
 /* 折叠时菜单项居中，仅图标 */
 .xx-sidebar-nav--collapsed .xx-sidebar-menu-item {
   justify-content: center;
-  padding: var(--space-sm);
-  margin: 0 var(--space-xxs);
+  padding: var(--space-xs);
+  margin: 0;
+}
+
+/* 折叠态图标恢复更大尺寸居中 */
+.xx-sidebar-nav--collapsed .xx-sidebar-menu-icon {
+  width: 32px;
+  height: 32px;
+  border-radius: 8px;
+  font-size: 16px;
 }
 
 /* 折叠时隐藏分组标题 */

apps/web/src/config/navigation.ts

@@ -18,6 +18,7 @@ import {
   ControlOutlined,
   CrownOutlined,
   UnorderedListOutlined,
+  UserOutlined,
 } from "@ant-design/icons"
 
 /** 导航项类型 */
@@ -57,6 +58,12 @@ export const NAV_ITEMS: NavItem[] = [
     path: "/app/titles",
     icon: React.createElement(FileTextOutlined),
   },
+  {
+    key: "scripts",
+    label: "文案库",
+    path: "/app/scripts",
+    icon: React.createElement(EditOutlined),
+  },
   {
     key: "voices",
     label: "配音库",
@@ -88,6 +95,12 @@ export const NAV_ITEMS: NavItem[] = [
     path: "/app/generate",
     icon: React.createElement(VideoCameraOutlined),
   },
+  {
+    key: "ai-avatar",
+    label: "AI数字人",
+    path: "/app/ai-avatar",
+    icon: React.createElement(UserOutlined),
+  },
   {
     key: "history",
     label: "任务历史",
@@ -131,6 +144,12 @@ export const NAV_GROUPS: NavGroup[] = [
         path: "/app/generate",
         icon: React.createElement(VideoCameraOutlined),
       },
+      {
+        key: "ai-avatar",
+        label: "AI数字人",
+        path: "/app/ai-avatar",
+        icon: React.createElement(UserOutlined),
+      },
       {
         key: "editing-planner",
         label: "剪辑模板",
@@ -160,6 +179,12 @@ export const NAV_GROUPS: NavGroup[] = [
         path: "/app/titles",
         icon: React.createElement(FileTextOutlined),
       },
+      {
+        key: "scripts",
+        label: "文案库",
+        path: "/app/scripts",
+        icon: React.createElement(EditOutlined),
+      },
       {
         key: "products",
         label: "成品库",

apps/web/src/pages/admin/Admin.css

@@ -11,7 +11,7 @@
 
 .admin-coming-soon-page {
   padding: 32px;
-  max-width: 1400px;
+  max-width: 1680px;
   margin: 0 auto;
 }
 

apps/web/src/pages/ai-avatar/AiAvatarPage.tsx

@@ -0,0 +1,522 @@
+/**
+ * AI数字人 — 主页面（v3）
+ * 5列水平面板布局
+ */
+import React, { useState, useCallback, useEffect, useRef } from "react"
+import { message } from "antd"
+import "./AiAvatar.css"
+import { useAiAvatar } from "./hooks/useAiAvatar"
+import { PanelVideoSelector } from "./components/PanelVideoSelector"
+import PanelVoiceSelector from "./components/PanelVoiceSelector"
+import PanelScriptAndLipsync from "./components/PanelScriptAndLipsync"
+import PanelTitleConfig from "./components/PanelTitleConfig"
+import PanelCoverAndGenerate from "./components/PanelCoverAndGenerate"
+import { ModalAssetPicker } from "./components/ModalAssetPicker"
+import ModalBRollEditor from "./components/ModalBRollEditor"
+import {
+  getScripts,
+  getAssetById,
+  createLipsyncJob,
+  getLipsyncJob,
+  submitRender,
+  generateSmartCover,
+} from "./api/aiAvatar"
+import {
+  normalizeEmotion,
+  buildTitleConfigPayload,
+  buildCoverConfigPayload,
+} from "./utils/contract"
+
+/** 面板折叠状态 */
+type PanelKey = "video" | "voice" | "script" | "title" | "cover"
+
+const AiAvatarPage: React.FC = () => {
+  const state = useAiAvatar()
+  const [collapsed, setCollapsed] = useState<Record<PanelKey, boolean>>({
+    video: false,
+    voice: false,
+    script: false,
+    title: false,
+    cover: false,
+  })
+
+  /* ── 对口型生成弹窗 ── */
+  const [showLipsyncModal, setShowLipsyncModal] = useState(false)
+  const [lipsyncStatus, setLipsyncStatus] = useState<"generating" | "completed" | "failed">(
+    "generating",
+  )
+  const [lipsyncErrorMessage, setLipsyncErrorMessage] = useState("")
+  /* ── 智能封面加载态 ── */
+  const [smartCoverLoading, setSmartCoverLoading] = useState(false)
+
+  /* ── 对口型轮询 ── */
+  const lipsyncTimerRef = useRef<ReturnType<typeof setInterval> | null>(null)
+
+  const togglePanel = useCallback((key: PanelKey) => {
+    setCollapsed((prev) => ({ ...prev, [key]: !prev[key] }))
+  }, [])
+
+  /* ── 对口型 ── */
+  const handleGenerateLipsync = useCallback(async () => {
+    // ② 缺项明确提示（#1809）：不再静默 return
+    const video = state.selectedVideo
+    const voice = state.selectedVoice
+    const text = state.scriptText.trim()
+    const missing: string[] = []
+    if (!video) missing.push("出镜视频")
+    if (!voice) missing.push("音色")
+    if (!text) missing.push("文案")
+    if (missing.length > 0 || !video || !voice) {
+      message.warning(`请先选择${missing.join("、")}`)
+      return
+    }
+    try {
+      // 显示生成弹窗
+      setShowLipsyncModal(true)
+      setLipsyncStatus("generating")
+      setLipsyncErrorMessage("")
+
+      // ① 先按素材 id 拿 file_url（#1809 补充：对齐后端新参数 video_url）
+      console.log("[对口型] 开始生成:", {
+        videoId: video.id,
+        voiceId: voice.voice_id,
+        voiceType: voice.type,
+        textLen: state.scriptText.length,
+      })
+      const asset = await getAssetById(video.id)
+      console.log("[对口型] getAssetById 响应:", {
+        id: asset?.id,
+        file_url: asset?.file_url?.substring(0, 100),
+      })
+      const videoUrl = asset?.file_url
+      if (!videoUrl) {
+        console.error("[对口型] file_url 为空，asset:", asset)
+        setShowLipsyncModal(false)
+        message.error("获取出镜视频播放地址失败，请重新选择素材")
+        return
+      }
+      // ② 模式A TTS直生：video_url + voice_id + script_text，语速/情绪英文枚举透传（#1822）
+      const payload = {
+        voice_id: voice.voice_id,
+        script_text: state.scriptText,
+        video_url: videoUrl,
+        speed: state.speed, // 语速 0.5~2.0
+        emotion: normalizeEmotion(state.emotion), // natural/excited/calm/friendly
+      }
+      console.log("[对口型] createLipsyncJob 请求:", payload)
+      const job = await createLipsyncJob(payload)
+      console.log("[对口型] createLipsyncJob 响应:", { id: job.id, status: job.status })
+      state.setLipsyncJob(job)
+      // 开始轮询
+      if (lipsyncTimerRef.current) clearInterval(lipsyncTimerRef.current)
+      lipsyncTimerRef.current = setInterval(async () => {
+        try {
+          const updated = await getLipsyncJob(job.id)
+          state.setLipsyncJob(updated)
+          console.log("[对口型] 轮询状态:", {
+            id: updated.id,
+            status: updated.status,
+            error: updated.error_message,
+          })
+          if (updated.status === "completed") {
+            if (lipsyncTimerRef.current) clearInterval(lipsyncTimerRef.current)
+            setLipsyncStatus("completed")
+            setTimeout(() => {
+              setShowLipsyncModal(false)
+              message.success("对口型视频生成完成")
+            }, 1000)
+          } else if (updated.status === "failed") {
+            if (lipsyncTimerRef.current) clearInterval(lipsyncTimerRef.current)
+            setLipsyncStatus("failed")
+            setLipsyncErrorMessage(updated.error_message || "对口型生成失败")
+          }
+        } catch (err) {
+          console.error("[对口型] 轮询错误:", err)
+        }
+      }, 3000)
+    } catch (err) {
+      console.error("[对口型] 创建失败:", {
+        status: (err as { response?: { status?: number } })?.response?.status,
+        data: (err as { response?: { data?: unknown } })?.response?.data,
+        message: err instanceof Error ? err.message : String(err),
+      })
+      setShowLipsyncModal(false)
+      message.error(err instanceof Error ? err.message : "对口型任务提交失败，请重试")
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [state.selectedVideo, state.selectedVoice, state.scriptText, state.speed, state.emotion])
+
+  // 取消对口型生成
+  const handleCancelLipsync = useCallback(() => {
+    if (lipsyncTimerRef.current) {
+      clearInterval(lipsyncTimerRef.current)
+      lipsyncTimerRef.current = null
+    }
+    setShowLipsyncModal(false)
+    setLipsyncStatus("generating")
+    setLipsyncErrorMessage("")
+  }, [])
+
+  // 清理轮询
+  useEffect(() => {
+    return () => {
+      if (lipsyncTimerRef.current) clearInterval(lipsyncTimerRef.current)
+    }
+  }, [])
+
+  /* ── 生成视频 ── */
+  const handleGenerate = useCallback(async () => {
+    // ② 前置条件提示（#1809）
+    if (!state.lipsyncJob || state.lipsyncJob.status !== "completed") {
+      message.warning("请先生成对口型视频，待对口型完成后再提交渲染")
+      return
+    }
+    state.setIsGenerating(true)
+    try {
+      await submitRender({
+        lipsync_job_id: state.lipsyncJob.id,
+        script_id: state.script?.id,
+        b_roll_segments: state.bRollSegments as never,
+        // 字段映射：build_title_drawtext_filter 真实口径 text/font_size/font_color/position/...
+        title_config: buildTitleConfigPayload(state.titleConfig),
+        // cover_config：智能封面 cover_url + 截帧 timestamp
+        cover_config: buildCoverConfigPayload(state.coverConfig, state.coverConfig.smart_cover_url),
+        resolution: state.resolution,
+      })
+      message.success("渲染任务已提交，可在视频管理中查看进度")
+    } catch (err) {
+      console.error("渲染任务提交失败:", err)
+      message.error(err instanceof Error ? err.message : "渲染任务提交失败，请重试")
+    } finally {
+      state.setIsGenerating(false)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    state.lipsyncJob,
+    state.script,
+    state.bRollSegments,
+    state.titleConfig,
+    state.coverConfig,
+    state.resolution,
+  ])
+
+  /* ── 智能封面：调后端 MediaKit 选帧接口（#1822） ── */
+  const handleSmartCover = useCallback(async () => {
+    // 基于对口型成片抽帧，必须先完成对口型
+    const videoUrl = state.lipsyncJob?.output_video_url
+    if (state.lipsyncJob?.status !== "completed" || !videoUrl) {
+      message.warning("请先生成对口型视频，完成后再智能获取封面")
+      return
+    }
+    setSmartCoverLoading(true)
+    try {
+      const res = await generateSmartCover(videoUrl, 5)
+      if (res.cover_url) {
+        state.setCoverConfig((prev) => ({
+          ...prev,
+          mode: "auto_frame",
+          smart_cover_url: res.cover_url,
+          thumbnail_url: res.cover_url,
+        }))
+        message.success("智能封面已生成")
+      } else {
+        message.error(res.message || "智能封面生成失败，请稍后重试")
+      }
+    } catch (err) {
+      console.error("智能封面生成失败:", err)
+      message.error(err instanceof Error ? err.message : "智能封面生成失败，请重试")
+    } finally {
+      setSmartCoverLoading(false)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [state.lipsyncJob])
+
+  /* ── 配置汇总 ── */
+  const summary = {
+    videoName: state.selectedVideo?.name || null,
+    voiceName: state.selectedVoice?.name || null,
+    scriptLength: state.scriptText.length,
+    lipsyncStatus: state.lipsyncJob?.status || null,
+    brollCount: state.bRollSegments.length,
+    hasTitle: state.titleConfig.title.length > 0,
+    hasCover: state.coverConfig.enabled,
+  }
+
+  return (
+    <div className="aa-page">
+      <div className="aa-page-header">
+        <h1>AI数字人</h1>
+      </div>
+      <div className="aa-page-body">
+        {/* 面板1：出镜视频 */}
+        <div className={`aa-panel aa-panel--p1${collapsed.video ? " collapsed" : ""}`}>
+          <div className="aa-panel__header" onClick={() => togglePanel("video")}>
+            <span className="aa-panel__title">出镜视频</span>
+            <span className="aa-panel__toggle">▼</span>
+          </div>
+          <div className="aa-panel__body">
+            <PanelVideoSelector
+              selectedVideo={state.selectedVideo}
+              onSelectVideo={() => state.setShowAssetPicker(true)}
+              onRemoveVideo={state.removeVideo}
+              titleConfig={state.titleConfig}
+            />
+          </div>
+        </div>
+
+        {/* 面板2：配音库 */}
+        <div className={`aa-panel aa-panel--p2${collapsed.voice ? " collapsed" : ""}`}>
+          <div className="aa-panel__header" onClick={() => togglePanel("voice")}>
+            <span className="aa-panel__title">配音库</span>
+            <span className="aa-panel__toggle">▼</span>
+          </div>
+          <div className="aa-panel__body">
+            <PanelVoiceSelector
+              voiceSource={state.voiceSource}
+              onVoiceSourceChange={state.setVoiceSource}
+              selectedVoice={state.selectedVoice}
+              onSelectVoice={state.setSelectedVoice}
+              emotion={state.emotion}
+              onEmotionChange={state.setEmotion}
+              speed={state.speed}
+              onSpeedChange={state.setSpeed}
+              language={state.language}
+              onLanguageChange={state.setLanguage}
+            />
+          </div>
+        </div>
+
+        {/* 面板3：文案 & 对口型 */}
+        <div className={`aa-panel aa-panel--p3${collapsed.script ? " collapsed" : ""}`}>
+          <div className="aa-panel__header" onClick={() => togglePanel("script")}>
+            <span className="aa-panel__title">文案 & 对口型</span>
+            <span className="aa-panel__toggle">▼</span>
+          </div>
+          <div className="aa-panel__body">
+            <PanelScriptAndLipsync
+              scriptText={state.scriptText}
+              onScriptTextChange={state.setScriptText}
+              onOpenScriptModal={() => state.setShowScriptModal(true)}
+              lipsyncJob={state.lipsyncJob}
+              onGenerateLipsync={handleGenerateLipsync}
+              bRollSegments={state.bRollSegments}
+              onOpenBRollModal={() => state.setShowBRollModal(true)}
+              onRemoveBRoll={state.removeBRollSegment}
+            />
+          </div>
+        </div>
+
+        {/* 面板4：标题配置 */}
+        <div className={`aa-panel aa-panel--p4${collapsed.title ? " collapsed" : ""}`}>
+          <div className="aa-panel__header" onClick={() => togglePanel("title")}>
+            <span className="aa-panel__title">标题配置</span>
+            <span className="aa-panel__toggle">▼</span>
+          </div>
+          <div className="aa-panel__body">
+            <PanelTitleConfig titleConfig={state.titleConfig} onUpdate={state.updateTitleConfig} />
+          </div>
+        </div>
+
+        {/* 面板5：封面 & 生成 */}
+        <div className={`aa-panel aa-panel--p5${collapsed.cover ? " collapsed" : ""}`}>
+          <div className="aa-panel__header" onClick={() => togglePanel("cover")}>
+            <span className="aa-panel__title">封面 & 生成</span>
+            <span className="aa-panel__toggle">▼</span>
+          </div>
+          <div className="aa-panel__body">
+            <PanelCoverAndGenerate
+              coverConfig={state.coverConfig}
+              onCoverConfigChange={(partial) =>
+                state.setCoverConfig((prev) => ({ ...prev, ...partial }))
+              }
+              onSmartCover={handleSmartCover}
+              smartCoverLoading={smartCoverLoading}
+              canSmartCover={state.lipsyncJob?.status === "completed"}
+              resolution={state.resolution}
+              onResolutionChange={state.setResolution}
+              isGenerating={state.isGenerating}
+              onGenerate={handleGenerate}
+              summary={summary}
+            />
+          </div>
+        </div>
+      </div>
+
+      {/* 素材库弹窗 */}
+      {state.showAssetPicker && (
+        <ModalAssetPicker
+          open={state.showAssetPicker}
+          onClose={() => state.setShowAssetPicker(false)}
+          onSelect={state.selectVideo}
+          selectedId={state.selectedVideo?.id}
+        />
+      )}
+
+      {/* 文案选择弹窗 */}
+      {state.showScriptModal && (
+        <ScriptSelectModalLazy
+          open={state.showScriptModal}
+          onClose={() => state.setShowScriptModal(false)}
+          onSelect={state.selectScript}
+        />
+      )}
+
+      {/* B-roll 编辑器弹窗 */}
+      {state.showBRollModal && (
+        <ModalBRollEditor
+          open={state.showBRollModal}
+          onClose={() => state.setShowBRollModal(false)}
+          existingSegments={state.bRollSegments}
+          scriptText={state.scriptText}
+          outputDuration={state.lipsyncJob?.output_duration ?? 0}
+          onConfirm={state.addBRollSegment}
+          onRemove={state.removeBRollSegment}
+        />
+      )}
+
+      {/* 对口型生成弹窗 */}
+      {showLipsyncModal && (
+        <div className="aa-modal-overlay">
+          <div className="aa-modal" onClick={(e) => e.stopPropagation()}>
+            <div className="aa-modal__header">
+              <span className="aa-modal__title">对口型生成</span>
+              <button className="aa-modal__close" onClick={handleCancelLipsync}>
+                ✕
+              </button>
+            </div>
+            <div
+              className="aa-modal__body"
+              style={{
+                display: "flex",
+                flexDirection: "column",
+                alignItems: "center",
+                padding: "40px 20px",
+              }}
+            >
+              {lipsyncStatus === "generating" && (
+                <>
+                  <div className="aa-lipsync-spinner" />
+                  <div style={{ marginTop: 20, fontSize: 15, color: "#1a1a2e" }}>
+                    对口型视频生成中…
+                  </div>
+                  <div style={{ marginTop: 8, fontSize: 13, color: "#8c8ca1" }}>
+                    请勿关闭页面，完成后将自动提示
+                  </div>
+                </>
+              )}
+              {lipsyncStatus === "completed" && (
+                <>
+                  <div style={{ fontSize: 48 }}>✅</div>
+                  <div style={{ marginTop: 16, fontSize: 15, color: "#1a1a2e" }}>
+                    对口型视频生成完成
+                  </div>
+                </>
+              )}
+              {lipsyncStatus === "failed" && (
+                <>
+                  <div style={{ fontSize: 48 }}>❌</div>
+                  <div style={{ marginTop: 16, fontSize: 15, color: "#1a1a2e" }}>
+                    对口型生成失败
+                  </div>
+                  {lipsyncErrorMessage && (
+                    <div style={{ marginTop: 8, fontSize: 13, color: "#ff4d4f" }}>
+                      {lipsyncErrorMessage}
+                    </div>
+                  )}
+                </>
+              )}
+            </div>
+            <div className="aa-modal__footer">
+              {lipsyncStatus === "generating" && (
+                <button className="aa-btn aa-btn--danger" onClick={handleCancelLipsync}>
+                  取消生成
+                </button>
+              )}
+              {lipsyncStatus !== "generating" && (
+                <button className="aa-btn" onClick={handleCancelLipsync}>
+                  关闭
+                </button>
+              )}
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+/** 文案选择弹窗（内联实现，轻量版） */
+const ScriptSelectModalLazy: React.FC<{
+  open: boolean
+  onClose: () => void
+  onSelect: (script: import("./types").Script) => void
+}> = ({ open, onClose, onSelect }) => {
+  const [scripts, setScripts] = useState<import("./types").Script[]>([])
+  const [search, setSearch] = useState("")
+  const [loading, setLoading] = useState(false)
+
+  useEffect(() => {
+    if (!open) return
+    setLoading(true)
+    getScripts()
+      .then((items) => setScripts(Array.isArray(items) ? items : []))
+      .catch(() => setScripts([]))
+      .finally(() => setLoading(false))
+  }, [open])
+
+  const filtered = scripts.filter(
+    (s) => !search || s.title.includes(search) || s.content.includes(search),
+  )
+
+  return (
+    <div className="aa-modal-overlay" onClick={onClose}>
+      <div className="aa-modal" onClick={(e) => e.stopPropagation()}>
+        <div className="aa-modal__header">
+          <span className="aa-modal__title">选择文案</span>
+          <button className="aa-modal__close" onClick={onClose}>
+            ✕
+          </button>
+        </div>
+        <div className="aa-modal__body">
+          <div className="aa-script-list-header">
+            <input
+              className="aa-input"
+              placeholder="搜索文案..."
+              value={search}
+              onChange={(e) => setSearch(e.target.value)}
+            />
+          </div>
+          {loading ? (
+            <div className="aa-empty">加载中...</div>
+          ) : filtered.length === 0 ? (
+            <div className="aa-empty">
+              <div className="aa-empty__icon">📝</div>
+              暂无文案，请手动输入或新建
+            </div>
+          ) : (
+            <div className="aa-script-list">
+              {filtered.map((s) => (
+                <div key={s.id} className="aa-script-item" onClick={() => onSelect(s)}>
+                  <span className="aa-script-item__icon">📄</span>
+                  <div className="aa-script-item__info">
+                    <div className="aa-script-item__title">{s.title}</div>
+                    <div className="aa-script-item__meta">
+                      {s.char_count}字 · {new Date(s.created_at).toLocaleDateString()}
+                    </div>
+                  </div>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+        <div className="aa-modal__footer">
+          <button className="aa-btn" onClick={onClose}>
+            取消
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default AiAvatarPage

apps/web/src/pages/ai-avatar/api/aiAvatar.ts

@@ -0,0 +1,94 @@
+/**
+ * AI数字人 — API 封装（#1822 契约对齐）
+ */
+import apiClient from "@/api/client"
+import type { Script, LipsyncJob, RenderJob, BRollSegment } from "../types"
+
+/* ── 文案库 ── */
+export const getScripts = async (): Promise<Script[]> => {
+  const response = await apiClient.get<{ items?: Script[] } | Script[]>("/scripts")
+  // 后端列表返回 { items, total } 分页对象，做兼容解包 + 数组防御（#1809 白屏修复）
+  const data = response.data as unknown
+  if (Array.isArray(data)) return data
+  const items = (data as { items?: Script[] })?.items
+  return Array.isArray(items) ? items : []
+}
+
+export const getScriptById = async (id: string): Promise<Script> => {
+  const response = await apiClient.get<Script>(`/scripts/${id}`)
+  return response.data
+}
+
+export const createScript = async (data: { title: string; content: string }): Promise<Script> => {
+  const response = await apiClient.post<Script>("/scripts", data)
+  return response.data
+}
+
+export const deleteScript = async (id: string): Promise<void> => {
+  await apiClient.delete(`/scripts/${id}`)
+}
+
+/* ── 素材单查（拿到 file_url 作为对口型的 video_url） ── */
+export const getAssetById = async (id: string): Promise<{ file_url?: string; id: string }> => {
+  const response = await apiClient.get<{ file_url?: string; id: string }>(`/assets/${id}`)
+  return response.data
+}
+
+/* ── 对口型（模式A：TTS 直生，后端内部合成音频；不要先调 TTS 拿 audio_url） ── */
+export const createLipsyncJob = async (data: {
+  /** 人物视频 URL（MP4）；由素材 id 经 getAssetById 拿 file_url，禁止传 video_asset_id */
+  video_url: string
+  /** 音色 ID（预置音色 或 克隆音色 profile UUID，后端会解析） */
+  voice_id: string
+  /** 要合成的文案（手动输入或文案库内容） */
+  script_text: string
+  /** 语速 0.5~2.0，默认 1.0 */
+  speed?: number
+  /** 情绪英文枚举：natural/excited/calm/friendly */
+  emotion?: string
+  enable_video_loop?: boolean
+  project_id?: string
+}): Promise<LipsyncJob> => {
+  const response = await apiClient.post<LipsyncJob>("/lipsync/jobs", data)
+  return response.data
+}
+
+export const getLipsyncJob = async (id: string): Promise<LipsyncJob> => {
+  const response = await apiClient.get<LipsyncJob>(`/lipsync/jobs/${id}`)
+  return response.data
+}
+
+/* ── 智能封面（MediaKit 抽帧 + 质量评分选最佳帧，独立于渲染任务） ── */
+export const generateSmartCover = async (
+  video_url: string,
+  max_frames = 5,
+): Promise<{ cover_url: string; status: string; message: string }> => {
+  const response = await apiClient.post<{ cover_url: string; status: string; message: string }>(
+    "/ai-avatar/render/smart-cover",
+    { video_url, max_frames },
+  )
+  return response.data
+}
+
+/* ── 渲染 ── */
+export const submitRender = async (data: {
+  lipsync_job_id: string
+  script_id?: string
+  b_roll_segments?: BRollSegment[]
+  title_config?: Record<string, unknown>
+  cover_config?: Record<string, unknown>
+  project_id?: string
+  resolution?: string
+}): Promise<RenderJob> => {
+  const response = await apiClient.post<RenderJob>("/ai-avatar/render", data)
+  return response.data
+}
+
+export const getRenderJob = async (jobId: string): Promise<RenderJob> => {
+  const response = await apiClient.get<RenderJob>(`/ai-avatar/render/${jobId}`)
+  return response.data
+}
+
+export const cancelRenderJob = async (jobId: string): Promise<void> => {
+  await apiClient.post(`/ai-avatar/render/${jobId}/cancel`)
+}

apps/web/src/pages/ai-avatar/components/ModalAssetPicker.tsx

@@ -0,0 +1,209 @@
+/**
+ * AI数字人 — 出镜视频选择弹窗（#1809 ③）
+ * 交互对齐智能剪辑 Step2：先选素材库（video 库）→ 再选该库内视频。
+ * 搜索框 + 素材库下拉 + 竖屏 9:16 视频缩略图网格 + 底部确认选择。
+ */
+import { useEffect, useState } from "react"
+import { getAssets, getAssetLibraries, type AssetItem, type AssetLibraryItem } from "@/api/assets"
+
+export interface ModalAssetPickerProps {
+  open: boolean
+  onClose: () => void
+  onSelect: (asset: AssetItem) => void
+  /** 已选中的素材 ID（用于高亮） */
+  selectedId?: string
+}
+
+export function ModalAssetPicker({ open, onClose, onSelect, selectedId }: ModalAssetPickerProps) {
+  const [keyword, setKeyword] = useState("")
+  const [libraries, setLibraries] = useState<AssetLibraryItem[]>([])
+  const [libraryId, setLibraryId] = useState<string>("")
+  const [assets, setAssets] = useState<AssetItem[]>([])
+  const [pickedId, setPickedId] = useState<string | null>(null)
+  const [loadingLibs, setLoadingLibs] = useState(false)
+  const [loadingAssets, setLoadingAssets] = useState(false)
+  const [error, setError] = useState("")
+
+  /* 弹窗打开：重置状态 */
+  useEffect(() => {
+    if (!open) return
+    setKeyword("")
+    setLibraries([])
+    setLibraryId("")
+    setAssets([])
+    setError("")
+    setPickedId(selectedId ?? null)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open])
+
+  /* 第一步：加载视频素材库列表（仅 kind=video，对齐智能剪辑 #1777） */
+  useEffect(() => {
+    if (!open) return
+    let cancelled = false
+    setLoadingLibs(true)
+    getAssetLibraries("video")
+      .then((libs) => {
+        if (cancelled) return
+        const list = Array.isArray(libs) ? libs : []
+        setLibraries(list)
+        // 默认选中第一个视频库
+        if (list.length > 0) setLibraryId((prev) => prev || list[0].id)
+      })
+      .catch(() => {
+        if (!cancelled) setError("素材库加载失败，请重试")
+      })
+      .finally(() => {
+        if (!cancelled) setLoadingLibs(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [open])
+
+  /* 第二步：选中库后拉取该库视频素材（关键字防抖） */
+  useEffect(() => {
+    if (!open || !libraryId) return
+    let cancelled = false
+    setLoadingAssets(true)
+    const load = async () => {
+      try {
+        // getAssets 返回 { items, total }；拉满一页（数字人口播视频库通常不大）
+        const { items } = await getAssets(libraryId, { page_size: 100 })
+        if (cancelled) return
+        let list = Array.isArray(items) ? items : []
+        // 仅保留视频素材（出镜视频要求）
+        list = list.filter((a) => a.mime_type?.includes("video"))
+        const kw = keyword.trim()
+        if (kw) list = list.filter((a) => a.name?.includes(kw))
+        setAssets(list)
+        setError("")
+      } catch {
+        if (!cancelled) {
+          setError("素材加载失败，请重试")
+          setAssets([])
+        }
+      } finally {
+        if (!cancelled) setLoadingAssets(false)
+      }
+    }
+    const timer = window.setTimeout(load, 300)
+    return () => {
+      cancelled = true
+      window.clearTimeout(timer)
+    }
+  }, [open, libraryId, keyword])
+
+  if (!open) return null
+
+  const handleConfirm = () => {
+    if (!pickedId) return
+    const asset = assets.find((a) => a.id === pickedId)
+    if (asset) onSelect(asset)
+    onClose()
+  }
+
+  return (
+    <div className="aa-modal-overlay" onClick={onClose}>
+      <div className="aa-modal" onClick={(e) => e.stopPropagation()}>
+        {/* 头部 */}
+        <div className="aa-modal__header">
+          <span className="aa-modal__title">选择出镜视频</span>
+          <button type="button" className="aa-modal__close" onClick={onClose} aria-label="关闭">
+            ×
+          </button>
+        </div>
+
+        {/* 主体：素材库选择 + 搜索 + 网格 */}
+        <div className="aa-modal__body">
+          {/* 第一步：选素材库 */}
+          <div className="aa-asset-search">
+            <select
+              className="aa-select"
+              style={{ width: 160, flex: "0 0 auto" }}
+              value={libraryId}
+              onChange={(e) => setLibraryId(e.target.value)}
+              disabled={loadingLibs || libraries.length === 0}
+            >
+              {libraries.length === 0 ? (
+                <option value="">{loadingLibs ? "素材库加载中…" : "暂无视频素材库"}</option>
+              ) : (
+                libraries.map((lib) => (
+                  <option key={lib.id} value={lib.id}>
+                    📁 {lib.name}
+                  </option>
+                ))
+              )}
+            </select>
+            <input
+              className="aa-input"
+              type="text"
+              placeholder="搜索素材名称…"
+              value={keyword}
+              onChange={(e) => setKeyword(e.target.value)}
+            />
+          </div>
+
+          {libraries.length === 0 && !loadingLibs ? (
+            <div className="aa-empty">
+              <div className="aa-empty__icon">📁</div>
+              暂无视频素材库，请先在「素材库」中创建视频库并上传视频
+            </div>
+          ) : loadingAssets ? (
+            <div className="aa-empty">
+              <div className="aa-empty__icon">⏳</div>
+              素材加载中…
+            </div>
+          ) : error ? (
+            <div className="aa-empty">
+              <div className="aa-empty__icon">⚠️</div>
+              {error}
+            </div>
+          ) : assets.length === 0 ? (
+            <div className="aa-empty">
+              <div className="aa-empty__icon">🎬</div>
+              该素材库暂无视频素材
+            </div>
+          ) : (
+            <div className="aa-asset-grid">
+              {assets.map((asset) => {
+                const isActive = asset.id === pickedId
+                const thumb = asset.thumbnail_url || asset.file_url
+                const isVideo = asset.mime_type?.includes("video")
+                return (
+                  <div
+                    key={asset.id}
+                    className={`aa-asset-card${isActive ? " selected" : ""}`}
+                    onClick={() => setPickedId(asset.id)}
+                  >
+                    {isVideo && !asset.thumbnail_url ? (
+                      <video src={asset.file_url} muted preload="metadata" />
+                    ) : (
+                      <img src={thumb} alt={asset.name} />
+                    )}
+                    {isActive && <div className="aa-asset-card__check">✓</div>}
+                    <div className="aa-asset-card__name">{asset.name}</div>
+                  </div>
+                )
+              })}
+            </div>
+          )}
+        </div>
+
+        {/* 底部：取消 + 确认选择 */}
+        <div className="aa-modal__footer">
+          <button type="button" className="aa-btn aa-btn--ghost" onClick={onClose}>
+            取消
+          </button>
+          <button
+            type="button"
+            className="aa-btn aa-btn--primary"
+            onClick={handleConfirm}
+            disabled={!pickedId}
+          >
+            确认选择
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

apps/web/src/pages/ai-avatar/components/ModalBRollEditor.tsx

@@ -0,0 +1,421 @@
+/**
+ * AI数字人 — B-roll 画面插入编辑器弹窗（#1809 ④⑤⑥）
+ *
+ * 布局：
+ * - 左侧：先选素材库（video 库）→ 再选该库视频素材（已被其他 segment 使用的素材
+ *   标灰 + "已选择" 遮罩，pointer-events:none 防重复选择）
+ * - 右侧：文案句子列表（点选对应段落，替代原数字索引框）/ 全屏 or 画中画 / 四角位置+大小
+ *   （开始/结束时间已删除，按句子字数占比 × 口播总时长自动估算）
+ * - 底部：已配置的画面插入列表（可删除）
+ */
+import React, { useEffect, useMemo, useState } from "react"
+import { getAssets, getAssetLibraries, type AssetItem, type AssetLibraryItem } from "@/api/assets"
+import type { BRollSegment, BRollInsertMode, PipPosition } from "../types"
+import { splitScriptIntoSentences, type ScriptSentence } from "../utils/sentences"
+
+interface ModalBRollEditorProps {
+  open: boolean
+  onClose: () => void
+  /** 当前已有的 B-roll segments（用于标灰已选素材） */
+  existingSegments: BRollSegment[]
+  /** 当前文案全文（用于分句） */
+  scriptText: string
+  /** 对口型成片总时长（秒），用于时间自动估算 */
+  outputDuration: number
+  onConfirm: (segment: BRollSegment) => void
+  onRemove: (id: string) => void
+}
+
+const PIP_POSITION_OPTIONS: { value: PipPosition; label: string }[] = [
+  { value: "top-left", label: "左上" },
+  { value: "top-right", label: "右上" },
+  { value: "bottom-left", label: "左下" },
+  { value: "bottom-right", label: "右下" },
+]
+
+const MODE_LABEL: Record<BRollInsertMode, string> = {
+  fullscreen: "全屏切换",
+  pip: "画中画",
+}
+
+const ModalBRollEditor: React.FC<ModalBRollEditorProps> = ({
+  open,
+  onClose,
+  existingSegments,
+  scriptText,
+  outputDuration,
+  onConfirm,
+  onRemove,
+}) => {
+  /* ── 素材库（④ 先选库再选素材） ── */
+  const [libraries, setLibraries] = useState<AssetLibraryItem[]>([])
+  const [libraryId, setLibraryId] = useState<string>("")
+  const [availableAssets, setAvailableAssets] = useState<AssetItem[]>([])
+  const [loadingLibs, setLoadingLibs] = useState(false)
+  const [loadingAssets, setLoadingAssets] = useState(false)
+  const [assetError, setAssetError] = useState("")
+
+  /* ── 右侧设置本地状态 ── */
+  const [selectedAsset, setSelectedAsset] = useState<AssetItem | null>(null)
+  const [selectedSentence, setSelectedSentence] = useState<ScriptSentence | null>(null)
+  const [mode, setMode] = useState<BRollInsertMode>("fullscreen")
+  const [pipPosition, setPipPosition] = useState<PipPosition>("top-right")
+  const [pipScale, setPipScale] = useState(0.3)
+
+  /** 文案分句（⑤） */
+  const sentences = useMemo(
+    () => splitScriptIntoSentences(scriptText, outputDuration),
+    [scriptText, outputDuration],
+  )
+
+  /** 已被现有 segments 占用的素材 id 集合（标灰、禁止重复选择） */
+  const usedAssetIds = useMemo(
+    () => new Set(existingSegments.map((seg) => seg.asset.id)),
+    [existingSegments],
+  )
+
+  /* 弹窗打开：重置选择 + 加载视频库列表 */
+  useEffect(() => {
+    if (!open) return
+    setSelectedAsset(null)
+    setSelectedSentence(null)
+    setMode("fullscreen")
+    setPipPosition("top-right")
+    setPipScale(0.3)
+    setLibraries([])
+    setLibraryId("")
+    setAvailableAssets([])
+    setAssetError("")
+    setLoadingLibs(true)
+    let cancelled = false
+    getAssetLibraries("video")
+      .then((libs) => {
+        if (cancelled) return
+        const list = Array.isArray(libs) ? libs : []
+        setLibraries(list)
+        if (list.length > 0) setLibraryId(list[0].id)
+      })
+      .catch(() => {
+        if (!cancelled) setAssetError("素材库加载失败，请重试")
+      })
+      .finally(() => {
+        if (!cancelled) setLoadingLibs(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [open])
+
+  /* 选中库后拉取该库视频素材 */
+  useEffect(() => {
+    if (!open || !libraryId) return
+    let cancelled = false
+    setLoadingAssets(true)
+    getAssets(libraryId, { page_size: 100 })
+      .then(({ items }) => {
+        if (cancelled) return
+        const list = (Array.isArray(items) ? items : []).filter((a) =>
+          a.mime_type?.includes("video"),
+        )
+        setAvailableAssets(list)
+        setAssetError("")
+      })
+      .catch(() => {
+        if (!cancelled) {
+          setAssetError("素材加载失败，请重试")
+          setAvailableAssets([])
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setLoadingAssets(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [open, libraryId])
+
+  if (!open) return null
+
+  /** 选择素材（已选素材因 pointer-events:none 不会触发） */
+  const handleSelectAsset = (asset: AssetItem) => {
+    if (usedAssetIds.has(asset.id)) return
+    setSelectedAsset(asset)
+  }
+
+  /** 确认添加一段 B-roll（⑥ 时间取所选句子的估算起止） */
+  const handleConfirm = () => {
+    if (!selectedAsset || !selectedSentence) return
+    const startTime = selectedSentence.startTime
+    const endTime = Math.max(selectedSentence.endTime, startTime + 0.5)
+    const segment: BRollSegment = {
+      id: crypto.randomUUID(),
+      asset: selectedAsset,
+      script_segment_index: selectedSentence.index,
+      start_time: startTime,
+      end_time: endTime,
+      mode,
+      pip_position: pipPosition,
+      pip_scale: mode === "pip" ? pipScale : 0.3,
+    }
+    onConfirm(segment)
+    // 重置素材/句子选择，保留模式设置便于连续添加
+    setSelectedAsset(null)
+    setSelectedSentence(null)
+  }
+
+  const canConfirm = selectedAsset !== null && selectedSentence !== null
+
+  return (
+    <div className="aa-modal-overlay" onClick={onClose}>
+      <div className="aa-modal aa-modal--wide" onClick={(e) => e.stopPropagation()}>
+        {/* 头部 */}
+        <div className="aa-modal__header">
+          <span className="aa-modal__title">🎞️ 画面插入（B-roll）</span>
+          <button type="button" className="aa-modal__close" onClick={onClose}>
+            ✕
+          </button>
+        </div>
+
+        {/* 主体：左素材 + 右设置 */}
+        <div className="aa-modal__body">
+          <div className="aa-broll-modal-body">
+            {/* 左侧：选库 + 素材网格 */}
+            <div className="aa-broll-left">
+              <div className="aa-broll-lib-row">
+                <select
+                  className="aa-select"
+                  value={libraryId}
+                  onChange={(e) => setLibraryId(e.target.value)}
+                  disabled={loadingLibs || libraries.length === 0}
+                >
+                  {libraries.length === 0 ? (
+                    <option value="">{loadingLibs ? "素材库加载中…" : "暂无视频素材库"}</option>
+                  ) : (
+                    libraries.map((lib) => (
+                      <option key={lib.id} value={lib.id}>
+                        📁 {lib.name}
+                      </option>
+                    ))
+                  )}
+                </select>
+              </div>
+              <div className="aa-broll-asset-grid">
+                {availableAssets.map((asset) => {
+                  const alreadySelected = usedAssetIds.has(asset.id)
+                  const isCurrent = selectedAsset?.id === asset.id
+                  const classNames = [
+                    "aa-broll-asset-thumb",
+                    isCurrent ? "selected" : "",
+                    alreadySelected ? "already-selected" : "",
+                  ]
+                    .filter(Boolean)
+                    .join(" ")
+                  return (
+                    <div
+                      key={asset.id}
+                      className={classNames}
+                      onClick={() => handleSelectAsset(asset)}
+                      title={asset.name}
+                    >
+                      {asset.thumbnail_url ? (
+                        <img src={asset.thumbnail_url} alt={asset.name} />
+                      ) : (
+                        <div className="aa-broll-asset-placeholder">🎬</div>
+                      )}
+                      <span className="aa-asset-card__name">{asset.name}</span>
+                    </div>
+                  )
+                })}
+                {loadingAssets ? (
+                  <div className="aa-empty" style={{ gridColumn: "1 / -1" }}>
+                    <div className="aa-empty__icon">⏳</div>
+                    素材加载中…
+                  </div>
+                ) : availableAssets.length === 0 ? (
+                  <div className="aa-empty" style={{ gridColumn: "1 / -1" }}>
+                    <div className="aa-empty__icon">🎬</div>
+                    {assetError || "该素材库暂无视频素材"}
+                  </div>
+                ) : null}
+              </div>
+            </div>
+
+            {/* 右侧：插入设置 */}
+            <div className="aa-broll-right">
+              <div className="aa-broll-settings">
+                {/* ⑤ 文案句子列表（替代段落索引数字框） */}
+                <div className="aa-form-field">
+                  <label className="aa-label">对应文案句子（点选）</label>
+                  {sentences.length === 0 ? (
+                    <div className="aa-sentence-empty">
+                      请先在「文案 & 对口型」面板填写或选择文案
+                    </div>
+                  ) : (
+                    <div className="aa-sentence-list">
+                      {sentences.map((sent) => {
+                        const active = selectedSentence?.index === sent.index
+                        return (
+                          <button
+                            key={sent.index}
+                            type="button"
+                            className={`aa-sentence-item${active ? " active" : ""}`}
+                            onClick={() => setSelectedSentence(sent)}
+                            title={sent.text}
+                          >
+                            <span className="aa-sentence-item__idx">{sent.index + 1}</span>
+                            <span className="aa-sentence-item__text">{sent.text}</span>
+                            {outputDuration > 0 && (
+                              <span className="aa-sentence-item__time">
+                                {sent.startTime.toFixed(1)}-{sent.endTime.toFixed(1)}s
+                              </span>
+                            )}
+                          </button>
+                        )
+                      })}
+                    </div>
+                  )}
+                </div>
+
+                {/* 插入模式 */}
+                <div className="aa-form-field">
+                  <label className="aa-label">插入模式</label>
+                  <div className="aa-broll-mode-toggle">
+                    <button
+                      type="button"
+                      className={`aa-broll-mode-btn${mode === "fullscreen" ? " active" : ""}`}
+                      onClick={() => setMode("fullscreen")}
+                    >
+                      全屏切换
+                    </button>
+                    <button
+                      type="button"
+                      className={`aa-broll-mode-btn${mode === "pip" ? " active" : ""}`}
+                      onClick={() => setMode("pip")}
+                    >
+                      画中画
+                    </button>
+                  </div>
+                </div>
+
+                {/* 画中画：四角位置 + 大小 */}
+                {mode === "pip" && (
+                  <>
+                    <div className="aa-form-field">
+                      <label className="aa-label">画中画位置</label>
+                      <div className="aa-pip-positions">
+                        {PIP_POSITION_OPTIONS.map((opt) => (
+                          <button
+                            key={opt.value}
+                            type="button"
+                            className={`aa-pip-pos-btn${
+                              pipPosition === opt.value ? " active" : ""
+                            }`}
+                            onClick={() => setPipPosition(opt.value)}
+                          >
+                            {opt.label}
+                          </button>
+                        ))}
+                      </div>
+                    </div>
+                    <div className="aa-form-field">
+                      <div className="aa-field-label-row">
+                        <label className="aa-label">画中画大小</label>
+                        <span style={{ fontSize: 12, color: "#8c8ca1" }}>
+                          {Math.round(pipScale * 100)}%
+                        </span>
+                      </div>
+                      <input
+                        type="range"
+                        min={0.1}
+                        max={0.6}
+                        step={0.05}
+                        value={pipScale}
+                        onChange={(e) => setPipScale(Number(e.target.value))}
+                        style={{ width: "100%" }}
+                      />
+                    </div>
+                  </>
+                )}
+
+                {/* 当前选择提示（⑥ 自动估算时间在这里展示） */}
+                <div className="aa-broll-hint">
+                  {selectedAsset && selectedSentence ? (
+                    <>
+                      <div>已选素材：{selectedAsset.name}</div>
+                      <div>
+                        对应第 {selectedSentence.index + 1} 句 · 时间段{" "}
+                        {selectedSentence.startTime.toFixed(1)}s -{" "}
+                        {Math.max(
+                          selectedSentence.endTime,
+                          selectedSentence.startTime + 0.5,
+                        ).toFixed(1)}
+                        s （按字数自动估算）
+                      </div>
+                    </>
+                  ) : (
+                    <div style={{ color: "#8c8ca1" }}>
+                      {!selectedAsset ? "请从左侧选择一段素材" : "请在上方点选对应的文案句子"}
+                    </div>
+                  )}
+                </div>
+              </div>
+            </div>
+          </div>
+
+          {/* 底部：已配置的画面插入列表 */}
+          <div className="aa-broll-list">
+            <div className="aa-broll-list__title">已配置画面插入（{existingSegments.length}）</div>
+            {existingSegments.length === 0 ? (
+              <div className="aa-empty" style={{ padding: 12 }}>
+                尚未配置画面插入
+              </div>
+            ) : (
+              existingSegments.map((seg) => (
+                <div key={seg.id} className="aa-broll-item">
+                  {seg.asset.thumbnail_url ? (
+                    <img className="aa-broll-item__thumb" src={seg.asset.thumbnail_url} alt="" />
+                  ) : (
+                    <div className="aa-broll-item__thumb" />
+                  )}
+                  <div className="aa-broll-item__info">
+                    <div style={{ fontWeight: 500, color: "#1a1a2e" }}>{seg.asset.name}</div>
+                    <div style={{ color: "#8c8ca1", fontSize: 11 }}>
+                      第 {seg.script_segment_index + 1} 句 · {MODE_LABEL[seg.mode]}
+                      {seg.mode === "pip" ? ` · ${seg.pip_position}` : ""} ·{" "}
+                      {seg.start_time.toFixed(1)}s - {seg.end_time.toFixed(1)}s
+                    </div>
+                  </div>
+                  <button
+                    type="button"
+                    className="aa-broll-item__remove"
+                    title="删除"
+                    onClick={() => onRemove(seg.id)}
+                  >
+                    🗑
+                  </button>
+                </div>
+              ))
+            )}
+          </div>
+        </div>
+
+        {/* 底部按钮 */}
+        <div className="aa-modal__footer">
+          <button type="button" className="aa-btn" onClick={onClose}>
+            关闭
+          </button>
+          <button
+            type="button"
+            className="aa-btn aa-btn--primary"
+            disabled={!canConfirm}
+            onClick={handleConfirm}
+          >
+            ✅ 添加画面插入
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default ModalBRollEditor

apps/web/src/pages/ai-avatar/components/PanelCoverAndGenerate.tsx

@@ -0,0 +1,220 @@
+/**
+ * AI数字人 — 面板5：封面 & 生成
+ * - 竖屏 9:16 封面预览（从视频截取 / 自定义上传）
+ * - 分辨率选择（720p / 1080p / 4K）
+ * - 配置汇总卡片（出镜视频/音色/文案/对口型/B-roll/标题/封面）
+ * - 渐变紫色生成按钮
+ *
+ * 注意：v3 已删除"画面插入模式"，本面板不包含该选项。
+ */
+import React, { useRef } from "react"
+import type { AiAvatarCoverConfig } from "../types"
+
+interface PanelCoverAndGenerateProps {
+  coverConfig: AiAvatarCoverConfig
+  onCoverConfigChange: (partial: Partial<AiAvatarCoverConfig>) => void
+  resolution: string
+  onResolutionChange: (r: string) => void
+  isGenerating: boolean
+  onGenerate: () => void
+  /** 智能获取封面（MediaKit 选帧） */
+  onSmartCover: () => void
+  smartCoverLoading: boolean
+  canSmartCover: boolean
+  /** 配置汇总信息 */
+  summary: {
+    videoName: string | null
+    voiceName: string | null
+    scriptLength: number
+    lipsyncStatus: string | null
+    brollCount: number
+    hasTitle: boolean
+    hasCover: boolean
+  }
+}
+
+const RESOLUTION_OPTIONS = [
+  { value: "720p", label: "720p（高清）" },
+  { value: "1080p", label: "1080p（全高清）" },
+  { value: "4k", label: "4K（超清）" },
+]
+
+const LIPSYNC_STATUS_LABEL: Record<string, { text: string; cls: string }> = {
+  idle: { text: "未开始", cls: "aa-status-badge--idle" },
+  pending: { text: "排队中", cls: "aa-status-badge--pending" },
+  processing: { text: "生成中", cls: "aa-status-badge--processing" },
+  completed: { text: "已完成", cls: "aa-status-badge--completed" },
+  failed: { text: "失败", cls: "aa-status-badge--failed" },
+}
+
+const PanelCoverAndGenerate: React.FC<PanelCoverAndGenerateProps> = ({
+  coverConfig,
+  onCoverConfigChange,
+  resolution,
+  onResolutionChange,
+  isGenerating,
+  onGenerate,
+  onSmartCover,
+  smartCoverLoading,
+  canSmartCover,
+  summary,
+}) => {
+  const uploadInputRef = useRef<HTMLInputElement>(null)
+
+  /** 自定义上传封面 */
+  const handleUploadClick = () => {
+    uploadInputRef.current?.click()
+  }
+
+  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0]
+    if (!file) return
+    // 本地预览：生成 object URL（实际上传由父级/后端链路处理）
+    const url = URL.createObjectURL(file)
+    onCoverConfigChange({ mode: "upload", upload_url: url, thumbnail_url: url })
+    // 允许重复选择同一文件
+    e.target.value = ""
+  }
+
+  /** 智能获取封面（调后端 MediaKit 抽帧评分选最佳帧，#1822） */
+  const handleSmartCover = () => {
+    onCoverConfigChange({ mode: "auto_frame" })
+    onSmartCover()
+  }
+
+  const lipsync = summary.lipsyncStatus ? LIPSYNC_STATUS_LABEL[summary.lipsyncStatus] : null
+
+  const canGenerate = summary.lipsyncStatus === "completed" && !isGenerating
+
+  return (
+    <div className="aa-cover-generate">
+      {/* 封面预览（竖屏 9:16） */}
+      <div className="aa-cover-preview">
+        {coverConfig.thumbnail_url ? (
+          <img src={coverConfig.thumbnail_url} alt="封面预览" />
+        ) : (
+          <span className="aa-cover-preview__placeholder">暂无封面</span>
+        )}
+      </div>
+
+      <div className="aa-cover-actions">
+        <button
+          type="button"
+          className={`aa-btn aa-btn--ghost${coverConfig.mode === "auto_frame" ? " active" : ""}`}
+          onClick={handleSmartCover}
+          disabled={smartCoverLoading || !canSmartCover}
+          title={canSmartCover ? "基于对口型成片智能选帧" : "请先完成对口型生成"}
+        >
+          {smartCoverLoading ? "⏳ 智能选帧中…" : "🎬 智能获取封面"}
+        </button>
+        <button
+          type="button"
+          className={`aa-btn aa-btn--ghost${coverConfig.mode === "upload" ? " active" : ""}`}
+          onClick={handleUploadClick}
+        >
+          📷 自定义上传
+        </button>
+        <input
+          ref={uploadInputRef}
+          type="file"
+          accept="image/*"
+          style={{ display: "none" }}
+          onChange={handleFileChange}
+        />
+      </div>
+
+      {/* 分辨率选择 */}
+      <div className="aa-form-field">
+        <label className="aa-label">分辨率</label>
+        <select
+          className="aa-select"
+          value={resolution}
+          onChange={(e) => onResolutionChange(e.target.value)}
+        >
+          {RESOLUTION_OPTIONS.map((opt) => (
+            <option key={opt.value} value={opt.value}>
+              {opt.label}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      {/* 配置汇总 */}
+      <div className="aa-generate-section">
+        <div className="aa-config-summary">
+          <div className="aa-config-summary__row">
+            <span>出镜视频</span>
+            {summary.videoName ? (
+              <span className="aa-config-summary__value">{summary.videoName}</span>
+            ) : (
+              <span className="aa-config-summary__empty">未配置</span>
+            )}
+          </div>
+          <div className="aa-config-summary__row">
+            <span>音色</span>
+            {summary.voiceName ? (
+              <span className="aa-config-summary__value">{summary.voiceName}</span>
+            ) : (
+              <span className="aa-config-summary__empty">未配置</span>
+            )}
+          </div>
+          <div className="aa-config-summary__row">
+            <span>文案</span>
+            {summary.scriptLength > 0 ? (
+              <span className="aa-config-summary__value">{summary.scriptLength} 字</span>
+            ) : (
+              <span className="aa-config-summary__empty">未配置</span>
+            )}
+          </div>
+          <div className="aa-config-summary__row">
+            <span>对口型</span>
+            {lipsync ? (
+              <span className={`aa-status-badge ${lipsync.cls}`}>{lipsync.text}</span>
+            ) : (
+              <span className="aa-config-summary__empty">未配置</span>
+            )}
+          </div>
+          <div className="aa-config-summary__row">
+            <span>B-roll 画面插入</span>
+            <span className="aa-config-summary__value">
+              {summary.brollCount > 0 ? `${summary.brollCount} 段` : "无"}
+            </span>
+          </div>
+          <div className="aa-config-summary__row">
+            <span>标题</span>
+            {summary.hasTitle ? (
+              <span className="aa-config-summary__value">已设置</span>
+            ) : (
+              <span className="aa-config-summary__empty">未配置</span>
+            )}
+          </div>
+          <div className="aa-config-summary__row">
+            <span>封面</span>
+            {summary.hasCover ? (
+              <span className="aa-config-summary__value">已开启</span>
+            ) : (
+              <span className="aa-config-summary__empty">未配置</span>
+            )}
+          </div>
+        </div>
+
+        {/* 生成按钮 */}
+        <button
+          type="button"
+          className="aa-btn aa-btn--generate aa-btn--full"
+          disabled={!canGenerate}
+          onClick={onGenerate}
+        >
+          {isGenerating ? "⏳ 生成中..." : "🚀 开始生成视频"}
+        </button>
+        {summary.lipsyncStatus !== "completed" && !isGenerating && (
+          <div style={{ marginTop: 8, fontSize: 11, color: "#8c8ca1", textAlign: "center" }}>
+            请先完成对口型生成
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export default PanelCoverAndGenerate

apps/web/src/pages/ai-avatar/components/PanelScriptAndLipsync.tsx

@@ -0,0 +1,222 @@
+/**
+ * AI数字人 — 文案 & 对口型面板（面板4）
+ * 上半区：文案（文案库选择 / 手动输入）；下半区：对口型视频预览（9:16）+ B-roll 画面
+ */
+import { useState } from "react"
+import type { LipsyncJob, BRollSegment } from "../types"
+
+interface PanelScriptAndLipsyncProps {
+  scriptText: string
+  onScriptTextChange: (text: string) => void
+  onOpenScriptModal: () => void
+  lipsyncJob: LipsyncJob | null
+  onGenerateLipsync: () => void
+  bRollSegments: BRollSegment[]
+  onOpenBRollModal: () => void
+  onRemoveBRoll: (id: string) => void
+}
+
+type ScriptTab = "library" | "manual"
+
+const BROLL_MODE_LABEL: Record<BRollSegment["mode"], string> = {
+  fullscreen: "全屏",
+  pip: "画中画",
+}
+
+function formatTime(seconds: number): string {
+  const m = Math.floor(seconds / 60)
+  const s = Math.round(seconds % 60)
+  return `${m}:${s.toString().padStart(2, "0")}`
+}
+
+export function PanelScriptAndLipsync({
+  scriptText,
+  onScriptTextChange,
+  onOpenScriptModal,
+  lipsyncJob,
+  onGenerateLipsync,
+  bRollSegments,
+  onOpenBRollModal,
+  onRemoveBRoll,
+}: PanelScriptAndLipsyncProps) {
+  const [scriptTab, setScriptTab] = useState<ScriptTab>("library")
+
+  /* 对口型状态判断 */
+  const isGenerating = lipsyncJob?.status === "pending" || lipsyncJob?.status === "processing"
+  const isDone = lipsyncJob?.status === "completed"
+  const isFailed = lipsyncJob?.status === "failed"
+
+  const statusText =
+    lipsyncJob?.status === "processing"
+      ? "对口型生成中…"
+      : lipsyncJob?.status === "pending"
+        ? "排队中…"
+        : "对口型生成中…"
+
+  return (
+    <div className="aa-script-lipsync">
+      {/* ── 上半区：文案 ── */}
+      <div className="aa-script-tabs">
+        <button
+          type="button"
+          className={`aa-script-tab${scriptTab === "library" ? " active" : ""}`}
+          onClick={() => setScriptTab("library")}
+        >
+          从文案库选择
+        </button>
+        <button
+          type="button"
+          className={`aa-script-tab${scriptTab === "manual" ? " active" : ""}`}
+          onClick={() => setScriptTab("manual")}
+        >
+          手动输入
+        </button>
+      </div>
+
+      {scriptTab === "library" && (
+        <button
+          type="button"
+          className="aa-btn aa-btn--ghost aa-btn--full"
+          style={{ marginBottom: 8 }}
+          onClick={onOpenScriptModal}
+        >
+          📚 从文案库选择文案
+        </button>
+      )}
+
+      <textarea
+        className="aa-textarea"
+        value={scriptText}
+        readOnly={scriptTab === "library"}
+        placeholder={
+          scriptTab === "library" ? "点击上方按钮，从文案库选择文案…" : "请输入数字人口播文案…"
+        }
+        onChange={(e) => onScriptTextChange(e.target.value)}
+      />
+      <div className="aa-char-count">{scriptText.length} 字</div>
+
+      {/* ── B-roll 画面 ── */}
+      <div className="aa-lipsync-section">
+        <div className="aa-lipsync-section__title">
+          <span style={{ marginRight: 8 }}>🎞️ 插入画面</span>
+          {bRollSegments.length > 0 && (
+            <span className="aa-broll-badge">🎬 {bRollSegments.length} 个画面</span>
+          )}
+        </div>
+        <div className="aa-lipsync-actions">
+          <button
+            type="button"
+            className="aa-btn aa-btn--primary aa-btn--full"
+            onClick={onOpenBRollModal}
+          >
+            🎬 插入画面
+          </button>
+        </div>
+
+        {bRollSegments.length > 0 && (
+          <div className="aa-broll-list">
+            {bRollSegments.map((seg) => (
+              <div key={seg.id} className="aa-broll-item">
+                {seg.asset.thumbnail_url || seg.asset.file_url ? (
+                  <img
+                    className="aa-broll-item__thumb"
+                    src={seg.asset.thumbnail_url || seg.asset.file_url}
+                    alt={seg.asset.name}
+                  />
+                ) : (
+                  <span className="aa-broll-item__thumb" style={{ padding: "6px 4px" }}>
+                    🎬
+                  </span>
+                )}
+                <div className="aa-broll-item__info">
+                  <div
+                    style={{
+                      overflow: "hidden",
+                      textOverflow: "ellipsis",
+                      whiteSpace: "nowrap",
+                    }}
+                  >
+                    {seg.asset.name}
+                  </div>
+                  <div style={{ fontSize: 11, color: "#8c8ca1", marginTop: 2 }}>
+                    {BROLL_MODE_LABEL[seg.mode]} · {formatTime(seg.start_time)}-
+                    {formatTime(seg.end_time)}
+                  </div>
+                </div>
+                <button
+                  type="button"
+                  className="aa-broll-item__remove"
+                  title="删除"
+                  onClick={() => onRemoveBRoll(seg.id)}
+                >
+                  ✕
+                </button>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* ── 下半区：对口型预览（竖屏 9:16） ── */}
+      <div className="aa-lipsync-section">
+        <div className="aa-lipsync-section__title">对口型预览</div>
+
+        <div className="aa-lipsync-preview">
+          {isDone && lipsyncJob?.output_video_url ? (
+            <video src={lipsyncJob.output_video_url} controls />
+          ) : isGenerating ? (
+            <div style={{ width: "80%", textAlign: "center", color: "#fff" }}>
+              <div style={{ fontSize: 13, marginBottom: 8 }}>
+                {statusText} {Math.round(lipsyncJob?.progress ?? 0)}%
+              </div>
+              <div className="aa-progress">
+                <div
+                  className="aa-progress__bar"
+                  style={{ width: `${lipsyncJob?.progress ?? 0}%` }}
+                />
+              </div>
+            </div>
+          ) : (
+            <div className="aa-video-preview__placeholder">
+              {isFailed ? (
+                <>
+                  <div style={{ fontSize: 28, marginBottom: 8 }}>❌</div>
+                  <div>对口型生成失败</div>
+                  {lipsyncJob?.error_message && (
+                    <div style={{ fontSize: 11, marginTop: 4, color: "#fca5a5" }}>
+                      {lipsyncJob.error_message}
+                    </div>
+                  )}
+                </>
+              ) : (
+                "生成对口型视频后在此预览"
+              )}
+            </div>
+          )}
+        </div>
+
+        <div className="aa-lipsync-actions">
+          {isDone ? (
+            <button type="button" className="aa-btn aa-btn--full" onClick={onGenerateLipsync}>
+              🔄 重新生成对口型
+            </button>
+          ) : isGenerating ? (
+            <button type="button" className="aa-btn aa-btn--full" disabled>
+              对口型生成中…
+            </button>
+          ) : (
+            <button
+              type="button"
+              className="aa-btn aa-btn--primary aa-btn--full"
+              onClick={onGenerateLipsync}
+            >
+              🎬 生成对口型视频
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default PanelScriptAndLipsync

apps/web/src/pages/ai-avatar/components/PanelTitleConfig.tsx

@@ -0,0 +1,134 @@
+/**
+ * AI数字人 — 面板4：标题配置
+ *
+ * 关键：直接复用智能剪辑（generate）模块的 TitleStylePanel 标题样式面板，
+ * 不重新开发标题预设/字体/位置等样式能力。本组件只负责：
+ * - 主标题文字输入
+ * - AiAvatarTitleConfig ↔ TitleSettings 的双向适配
+ * - 自动生成字幕开关
+ */
+import React, { useMemo, useState, useEffect } from "react"
+import { Input } from "antd"
+import TitleStylePanel from "@/pages/generate/components/title/TitleStylePanel"
+import TitleLibraryAutoComplete from "@/pages/generate/components/title/TitleLibraryAutoComplete"
+import type { TitleOption } from "@/pages/generate/components/title/TitleLibraryAutoComplete"
+import type { TitleSettings } from "@/pages/generate/types"
+import { POSITION_OPTIONS, FONT_OPTIONS, TITLE_PRESETS } from "@/pages/generate/constants"
+import type { AiAvatarTitleConfig } from "../types"
+import { getTitles } from "@/api/titles"
+
+const { TextArea } = Input
+
+interface PanelTitleConfigProps {
+  titleConfig: AiAvatarTitleConfig
+  onUpdate: (partial: Partial<AiAvatarTitleConfig>) => void
+}
+
+const PanelTitleConfig: React.FC<PanelTitleConfigProps> = ({ titleConfig, onUpdate }) => {
+  /** TitleStylePanel 内部高亮的预设 key（面板本地状态） */
+  const [activePreset, setActivePreset] = useState<string | null>(null)
+
+  /** 标题库选项（复用智能剪辑的标题库） */
+  const [titleOptions, setTitleOptions] = useState<TitleOption[]>([])
+  useEffect(() => {
+    getTitles()
+      .then((items) => setTitleOptions(items.map((t) => ({ label: t.content, value: t.content }))))
+      .catch(() => setTitleOptions([]))
+  }, [])
+
+  /** AiAvatarTitleConfig → TitleSettings（补齐 aiAutoSelect / 自由坐标字段） */
+  const titleSettings: TitleSettings = useMemo(
+    () => ({
+      aiAutoSelect: false,
+      title: titleConfig.title,
+      position: titleConfig.position,
+      font: titleConfig.font,
+      size: titleConfig.size,
+      bold: titleConfig.bold,
+      italic: titleConfig.italic,
+      stroke: titleConfig.stroke,
+      shadow: titleConfig.shadow,
+      color: titleConfig.color,
+      posX: null,
+      posY: null,
+    }),
+    [titleConfig],
+  )
+
+  /** 应用预设：与智能剪辑一致，只覆盖 color/bold/italic/stroke/shadow，不改变字号 */
+  const handleApplyPreset = (presetKey: string) => {
+    const preset = TITLE_PRESETS.find((p) => p.key === presetKey)
+    if (!preset) return
+    setActivePreset(presetKey)
+    onUpdate({
+      color: preset.style.color,
+      bold: preset.style.bold,
+      italic: preset.style.italic,
+      stroke: preset.style.stroke,
+      shadow: preset.style.shadow,
+    })
+  }
+
+  return (
+    <div className="aa-title-config">
+      {/* 主标题输入 — TextArea 多行 + 标题库选择 */}
+      <div className="aa-form-field">
+        <label className="aa-label">主标题</label>
+        <TextArea
+          className="aa-title-input"
+          placeholder="输入视频标题（支持 / 分行）"
+          value={titleConfig.title}
+          autoSize={{ minRows: 2, maxRows: 4 }}
+          maxLength={200}
+          onChange={(e) => onUpdate({ title: e.target.value })}
+          style={{ fontSize: 15 }}
+        />
+        <div style={{ marginTop: 8, display: "flex", alignItems: "center", gap: 8 }}>
+          <span style={{ fontSize: 12, color: "#8c8ca1", whiteSpace: "nowrap" }}>📚 标题库</span>
+          <TitleLibraryAutoComplete
+            key={titleConfig.title}
+            placeholder="选择标题填入上方"
+            value=""
+            onChange={(val) => {
+              if (val) onUpdate({ title: val })
+            }}
+            options={titleOptions}
+            maxLength={200}
+            style={{ flex: 1 }}
+          />
+        </div>
+      </div>
+
+      {/* 标题样式：直接复用智能剪辑 TitleStylePanel（位置/字体/字号/样式/预设） */}
+      <TitleStylePanel
+        settings={titleSettings}
+        onUpdatePosition={(position) => onUpdate({ position })}
+        onUpdateFont={(font) => onUpdate({ font })}
+        onUpdateSize={(size) => onUpdate({ size: Math.min(128, Math.max(16, size)) })}
+        onToggleBold={() => onUpdate({ bold: !titleConfig.bold })}
+        onToggleItalic={() => onUpdate({ italic: !titleConfig.italic })}
+        onToggleStroke={() => onUpdate({ stroke: !titleConfig.stroke })}
+        onToggleShadow={() => onUpdate({ shadow: !titleConfig.shadow })}
+        onApplyPreset={handleApplyPreset}
+        activePreset={activePreset}
+        titlePresets={TITLE_PRESETS}
+        POSITION_OPTIONS={POSITION_OPTIONS}
+        FONT_OPTIONS={FONT_OPTIONS}
+      />
+
+      {/* 自动生成字幕 */}
+      <div className="aa-subtitle-toggle">
+        <label className="aa-checkbox-row">
+          <input
+            type="checkbox"
+            checked={titleConfig.auto_subtitle}
+            onChange={(e) => onUpdate({ auto_subtitle: e.target.checked })}
+          />
+          自动生成字幕
+        </label>
+      </div>
+    </div>
+  )
+}
+
+export default PanelTitleConfig

apps/web/src/pages/ai-avatar/components/PanelVideoSelector.tsx

@@ -0,0 +1,124 @@
+/**
+ * AI数字人 — 出镜视频选择面板
+ * - 未选视频：虚线上传区，点击打开素材库弹窗
+ * - 已选视频：竖屏 9:16 预览播放器 + 视频信息卡片 + 移除按钮
+ */
+import type { AssetItem } from "@/api/assets"
+import type { AiAvatarTitleConfig } from "../types"
+import { getFontFamily } from "@/pages/generate/constants"
+
+export interface PanelVideoSelectorProps {
+  selectedVideo: AssetItem | null
+  /** 触发打开素材库弹窗 */
+  onSelectVideo: () => void
+  onRemoveVideo: () => void
+  titleConfig?: AiAvatarTitleConfig
+}
+
+/** 格式化时长（秒 → mm:ss） */
+function formatDuration(seconds?: number): string {
+  if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds <= 0) {
+    return "00:00"
+  }
+  return `${Math.floor(seconds / 60)}:${String(Math.floor(seconds % 60)).padStart(2, "0")}`
+}
+
+export function PanelVideoSelector({
+  selectedVideo,
+  onSelectVideo,
+  onRemoveVideo,
+  titleConfig,
+}: PanelVideoSelectorProps) {
+  /* 未选视频：虚线上传区，点击打开素材库弹窗 */
+  if (!selectedVideo) {
+    return (
+      <div
+        className="aa-upload-zone"
+        role="button"
+        tabIndex={0}
+        onClick={onSelectVideo}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault()
+            onSelectVideo()
+          }
+        }}
+      >
+        <div className="aa-upload-zone__icon">🎬</div>
+        <div className="aa-upload-zone__text">从素材库选择视频</div>
+      </div>
+    )
+  }
+
+  const width = selectedVideo.metadata?.width
+  const height = selectedVideo.metadata?.height
+  const duration = selectedVideo.duration ?? selectedVideo.metadata?.duration
+  const fileUrl = selectedVideo.file_url ?? ""
+
+  return (
+    <div>
+      {/* 竖屏 9:16 视频预览播放器 + 标题实时预览 */}
+      <div className="aa-video-preview" style={{ position: "relative" }}>
+        {fileUrl ? (
+          <video src={fileUrl} poster={selectedVideo.thumbnail_url} controls playsInline />
+        ) : (
+          <div className="aa-video-preview__placeholder">视频暂不可预览</div>
+        )}
+        {titleConfig?.title && (
+          <div
+            style={{
+              position: "absolute",
+              left: "50%",
+              transform: "translateX(-50%)",
+              ...(titleConfig.position === "top"
+                ? { top: "10%" }
+                : titleConfig.position === "bottom"
+                  ? { bottom: "10%" }
+                  : { top: "50%", transform: "translate(-50%, -50%)" }),
+              fontSize: Math.max(titleConfig.size, 32),
+              fontFamily: getFontFamily(titleConfig.font),
+              color: titleConfig.color,
+              fontWeight: titleConfig.bold ? 700 : 400,
+              fontStyle: titleConfig.italic ? "italic" : "normal",
+              textShadow: "0 2px 4px rgba(0,0,0,0.5)",
+              WebkitTextStroke: "2px #000",
+              pointerEvents: "none",
+              zIndex: 10,
+              maxWidth: "90%",
+              textAlign: "center",
+              whiteSpace: "pre-wrap",
+              lineHeight: 1.3,
+            }}
+          >
+            {titleConfig.title}
+          </div>
+        )}
+      </div>
+
+      {/* 视频信息卡片：文件名 / 时长 / 分辨率 */}
+      <div className="aa-video-info">
+        <div className="aa-video-info__row">
+          <span>文件名</span>
+          <span title={selectedVideo.name}>{selectedVideo.name}</span>
+        </div>
+        <div className="aa-video-info__row">
+          <span>时长</span>
+          <span>{formatDuration(duration)}</span>
+        </div>
+        <div className="aa-video-info__row">
+          <span>分辨率</span>
+          <span>{width && height ? `${width}×${height}` : "—"}</span>
+        </div>
+      </div>
+
+      <button
+        type="button"
+        className="aa-btn aa-btn--danger aa-btn--full"
+        style={{ marginTop: 10 }}
+        onClick={onRemoveVideo}
+      >
+        移除视频
+      </button>
+    </div>
+  )
+}

apps/web/src/pages/ai-avatar/components/PanelVoiceSelector.tsx

@@ -0,0 +1,334 @@
+/**
+ * AI数字人 — 配音库面板（面板3）
+ * 音色来源切换（系统预设 / 我的音色）、音色选择与试听、情绪/语速/语言参数
+ */
+import { useEffect, useRef, useState } from "react"
+import { message } from "antd"
+import { fetchVoices } from "@/api/voices/voices"
+import { previewTts } from "@/api/tts"
+import { normalizeEmotion } from "../utils/contract"
+import type { UnifiedVoiceItem } from "@/api/voices/types"
+import {
+  type VoiceSource,
+  type VoiceEmotion,
+  type VoiceLanguage,
+  VOICE_EMOTION_OPTIONS,
+  VOICE_LANGUAGE_OPTIONS,
+} from "../types"
+
+interface PanelVoiceSelectorProps {
+  voiceSource: VoiceSource
+  onVoiceSourceChange: (source: VoiceSource) => void
+  selectedVoice: UnifiedVoiceItem | null
+  onSelectVoice: (voice: UnifiedVoiceItem) => void
+  emotion: VoiceEmotion
+  onEmotionChange: (e: VoiceEmotion) => void
+  speed: number
+  onSpeedChange: (s: number) => void
+  language: VoiceLanguage
+  onLanguageChange: (l: VoiceLanguage) => void
+}
+
+export function PanelVoiceSelector({
+  voiceSource,
+  onVoiceSourceChange,
+  selectedVoice,
+  onSelectVoice,
+  emotion,
+  onEmotionChange,
+  speed,
+  onSpeedChange,
+  language,
+  onLanguageChange,
+}: PanelVoiceSelectorProps) {
+  const [voices, setVoices] = useState<UnifiedVoiceItem[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [previewingId, setPreviewingId] = useState<string | null>(null)
+  const audioRef = useRef<HTMLAudioElement | null>(null)
+  /** 克隆音色试听合成缓存：voiceId -> url，对齐配音库 useAudioPlayer */
+  const previewCacheRef = useRef<Map<string, string>>(new Map())
+  const VOICE_PREVIEW_TEXT = "你好呀，欢迎使用小虾智剪，这是我的配音效果，希望你喜欢。"
+
+  /* 切换来源时重新获取音色列表 */
+  useEffect(() => {
+    let cancelled = false
+    const loadVoices = async () => {
+      setLoading(true)
+      setError(null)
+      try {
+        const res = await fetchVoices({ type: voiceSource })
+        if (!cancelled) setVoices(Array.isArray(res?.items) ? res.items : [])
+      } catch (err) {
+        if (!cancelled) setError(err instanceof Error ? err.message : "音色加载失败")
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    }
+    loadVoices()
+    return () => {
+      cancelled = true
+    }
+  }, [voiceSource])
+
+  /* 卸载时停止试听 */
+  useEffect(() => {
+    return () => {
+      if (audioRef.current) {
+        audioRef.current.pause()
+        audioRef.current = null
+      }
+    }
+  }, [])
+
+  const stopPreview = () => {
+    if (audioRef.current) {
+      audioRef.current.pause()
+      audioRef.current = null
+    }
+    setPreviewingId(null)
+  }
+
+  const NO_PREVIEW_TIP = "该音色暂无试听音频，请先用此音色生成一段配音后再试听"
+
+  /** 用指定 URL 真实播放（抽取公共） */
+  const playAudioUrl = (voiceId: string, url: string) => {
+    // 临时兼容：后端 /tts/preview 返回 HTTP URL，staging 是 HTTPS，Mixed Content 会阻止加载
+    // OSS 同时支持 HTTP/HTTPS，直接替换协议即可
+    const safeUrl = url.startsWith("http://") ? url.replace("http://", "https://") : url
+    if (audioRef.current) {
+      audioRef.current.pause()
+      audioRef.current = null
+    }
+    const audio = new Audio(safeUrl)
+    audioRef.current = audio
+    setPreviewingId(voiceId)
+    audio.onended = () => {
+      if (audioRef.current === audio) {
+        audioRef.current = null
+        setPreviewingId(null)
+      }
+    }
+    audio.onerror = () => {
+      if (audioRef.current === audio) {
+        audioRef.current = null
+        setPreviewingId(null)
+        message.error("试听音频加载失败")
+      }
+    }
+    void audio.play().catch(() => {
+      setPreviewingId(null)
+      message.error("试听播放失败")
+    })
+  }
+
+  const handlePreview = async (voice: UnifiedVoiceItem) => {
+    /* 再次点击当前试听音色 → 停止 */
+    if (previewingId === voice.id) {
+      stopPreview()
+      return
+    }
+
+    /* 克隆音色：preview_url/audio_url 通常为空，需走 POST /tts/preview
+     * 现合成示例文案再播放，对齐配音库 useAudioPlayer 行为 */
+    if (voice.type === "clone") {
+      const cached = previewCacheRef.current.get(voice.voice_clone_profile_id || voice.id)
+      if (cached) {
+        playAudioUrl(voice.id, cached)
+        return
+      }
+      const targetId = voice.voice_clone_profile_id || voice.id
+      // DEBUG: 打印请求参数，帮助定位 /tts/preview 失败原因
+      console.log("[AI数字人-克隆试听] previewTts 请求:", {
+        voice_id: targetId,
+        voice_name: voice.name,
+        voice_type: voice.type,
+        voice_clone_profile_id: voice.voice_clone_profile_id,
+        voice_id_field: voice.voice_id,
+      })
+      setPreviewingId(voice.id)
+      try {
+        const res = await previewTts({
+          text: VOICE_PREVIEW_TEXT,
+          voice_id: targetId,
+          speed: speed, // 透传用户选择的语速（#1822）
+          emotion: normalizeEmotion(emotion), // 情绪中文→英文枚举
+        })
+        console.log("[AI数字人-克隆试听] previewTts 响应:", {
+          audio_url: res.audio_url?.substring(0, 80),
+          duration: res.duration,
+        })
+        if (!res.audio_url) {
+          setPreviewingId(null)
+          message.error("合成试听失败：未返回音频")
+          return
+        }
+        previewCacheRef.current.set(targetId, res.audio_url)
+        playAudioUrl(voice.id, res.audio_url)
+      } catch (err) {
+        setPreviewingId(null)
+        // DEBUG: 打印详细错误信息
+        console.error("[AI数字人-克隆试听] previewTts 失败:", {
+          status: (err as { response?: { status?: number } })?.response?.status,
+          data: (err as { response?: { data?: unknown } })?.response?.data,
+          message: err instanceof Error ? err.message : String(err),
+        })
+        // apiClient 拦截器已统一 toast
+      }
+      return
+    }
+
+    /* 系统预设音色：沿用 preview_url/audio_url 直链播放 */
+    const url = voice.preview_url || voice.audio_url
+    if (!url) {
+      message.warning(NO_PREVIEW_TIP)
+      return
+    }
+    playAudioUrl(voice.id, url)
+  }
+
+  const handleSpeedChange = (value: string) => {
+    const parsed = parseFloat(value)
+    if (Number.isNaN(parsed)) return
+    const clamped = Math.min(2.0, Math.max(0.5, parsed))
+    onSpeedChange(clamped)
+  }
+
+  return (
+    <div className="aa-voice-selector">
+      {/* 音色来源切换 */}
+      <div className="aa-voice-source-toggle">
+        <button
+          type="button"
+          className={`aa-voice-source-btn${voiceSource === "preset" ? " active" : ""}`}
+          onClick={() => onVoiceSourceChange("preset")}
+        >
+          系统预设
+        </button>
+        <button
+          type="button"
+          className={`aa-voice-source-btn${voiceSource === "clone" ? " active" : ""}`}
+          onClick={() => onVoiceSourceChange("clone")}
+        >
+          我的音色
+        </button>
+      </div>
+
+      {/* 音色列表 */}
+      {loading ? (
+        <div className="aa-empty">
+          <div className="aa-empty__icon">⏳</div>
+          <div>音色加载中…</div>
+        </div>
+      ) : error ? (
+        <div className="aa-empty">
+          <div className="aa-empty__icon">⚠️</div>
+          <div>{error}</div>
+        </div>
+      ) : voices.length === 0 ? (
+        <div className="aa-empty">
+          <div className="aa-empty__icon">🎙️</div>
+          <div>{voiceSource === "clone" ? "还没有克隆音色" : "暂无预置音色"}</div>
+        </div>
+      ) : (
+        <div className="aa-voice-list">
+          {voices.map((voice) => {
+            const selected = selectedVoice?.id === voice.id
+            const previewUrl = voice.preview_url || voice.audio_url
+            return (
+              <div
+                key={voice.id}
+                className={`aa-voice-card${selected ? " selected" : ""}`}
+                onClick={() => onSelectVoice(voice)}
+              >
+                <span className="aa-voice-card__radio" />
+                <div className="aa-voice-card__info">
+                  <div className="aa-voice-card__name">{voice.name}</div>
+                  {voice.description && (
+                    <div className="aa-voice-card__desc">{voice.description}</div>
+                  )}
+                </div>
+                <button
+                  type="button"
+                  className="aa-voice-card__preview"
+                  title={previewingId === voice.id ? "停止试听" : "试听"}
+                  disabled={voice.type === "preset" && !previewUrl}
+                  onClick={(e) => {
+                    e.stopPropagation()
+                    handlePreview(voice)
+                  }}
+                >
+                  {previewingId === voice.id ? "⏸" : "▶"}
+                </button>
+              </div>
+            )
+          })}
+        </div>
+      )}
+
+      {/* 我的音色：克隆入口 */}
+      {voiceSource === "clone" && (
+        <div className="aa-clone-entry">
+          <a href="/app/voice-clone">+ 克隆新音色</a>
+        </div>
+      )}
+
+      {/* 配音参数 */}
+      <div className="aa-voice-params">
+        <div className="aa-voice-params__row">
+          <div className="aa-voice-params__field">
+            <label className="aa-label" htmlFor="aa-voice-emotion">
+              情绪
+            </label>
+            <select
+              id="aa-voice-emotion"
+              className="aa-select"
+              value={emotion}
+              onChange={(e) => onEmotionChange(e.target.value as VoiceEmotion)}
+            >
+              {VOICE_EMOTION_OPTIONS.map((opt) => (
+                <option key={opt.value} value={opt.value}>
+                  {opt.label}
+                </option>
+              ))}
+            </select>
+          </div>
+          <div className="aa-voice-params__field">
+            <label className="aa-label" htmlFor="aa-voice-language">
+              语言
+            </label>
+            <select
+              id="aa-voice-language"
+              className="aa-select"
+              value={language}
+              onChange={(e) => onLanguageChange(e.target.value as VoiceLanguage)}
+            >
+              {VOICE_LANGUAGE_OPTIONS.map((opt) => (
+                <option key={opt.value} value={opt.value}>
+                  {opt.label}
+                </option>
+              ))}
+            </select>
+          </div>
+        </div>
+        <div className="aa-voice-params__field">
+          <label className="aa-label" htmlFor="aa-voice-speed">
+            语速（{speed.toFixed(1)}x）
+          </label>
+          <input
+            id="aa-voice-speed"
+            type="number"
+            className="aa-input"
+            min={0.5}
+            max={2.0}
+            step={0.1}
+            value={speed}
+            onChange={(e) => handleSpeedChange(e.target.value)}
+          />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default PanelVoiceSelector

apps/web/src/pages/ai-avatar/components/TitleLibraryModal.tsx

@@ -0,0 +1,97 @@
+/**
+ * AI数字人 — 标题库选择弹窗
+ * 复用智能剪辑的标题库 API，选择标题后填入输入框
+ */
+import React, { useEffect, useState } from "react"
+import { getTitles } from "@/api/titles"
+import type { TitleItem } from "@/api/titles/types"
+
+interface TitleLibraryModalProps {
+  open: boolean
+  onClose: () => void
+  onSelect: (title: string) => void
+}
+
+const TitleLibraryModal: React.FC<TitleLibraryModalProps> = ({ open, onClose, onSelect }) => {
+  const [titles, setTitles] = useState<TitleItem[]>([])
+  const [loading, setLoading] = useState(false)
+  const [search, setSearch] = useState("")
+
+  useEffect(() => {
+    if (!open) return
+    setLoading(true)
+    getTitles()
+      .then((items) => setTitles(items))
+      .catch(() => setTitles([]))
+      .finally(() => setLoading(false))
+  }, [open])
+
+  const filtered = titles.filter(
+    (t) => !search || t.content.toLowerCase().includes(search.toLowerCase()),
+  )
+
+  if (!open) return null
+
+  return (
+    <div className="aa-modal-overlay" onClick={onClose}>
+      <div className="aa-modal" onClick={(e) => e.stopPropagation()} style={{ maxWidth: 600 }}>
+        <div className="aa-modal__header">
+          <span className="aa-modal__title">从标题库选择</span>
+          <button className="aa-modal__close" onClick={onClose}></button>
+        </div>
+        <div className="aa-modal__body">
+          <div style={{ marginBottom: 12 }}>
+            <input
+              className="aa-input"
+              placeholder="搜索标题..."
+              value={search}
+              onChange={(e) => setSearch(e.target.value)}
+            />
+          </div>
+          {loading ? (
+            <div style={{ textAlign: "center", padding: 40, color: "#8c8ca1" }}>加载中...</div>
+          ) : filtered.length === 0 ? (
+            <div style={{ textAlign: "center", padding: 40, color: "#8c8ca1" }}>
+              暂无标题，请先在标题库创建
+            </div>
+          ) : (
+            <div style={{ maxHeight: 400, overflowY: "auto" }}>
+              {filtered.map((t) => (
+                <div
+                  key={t.id}
+                  style={{
+                    padding: "12px 16px",
+                    marginBottom: 8,
+                    background: "#f8f8fc",
+                    borderRadius: 8,
+                    cursor: "pointer",
+                    transition: "background 0.2s",
+                  }}
+                  onMouseEnter={(e) => (e.currentTarget.style.background = "#eef0ff")}
+                  onMouseLeave={(e) => (e.currentTarget.style.background = "#f8f8fc")}
+                  onClick={() => {
+                    onSelect(t.content)
+                    onClose()
+                  }}
+                >
+                  <div style={{ fontSize: 14, color: "#1a1a2e", marginBottom: 4 }}>{t.content}</div>
+                  <div style={{ fontSize: 12, color: "#8c8ca1" }}>
+                    {t.word_count ?? t.content.length}字 ·{" "}
+                    {t.created_at ? new Date(t.created_at).toLocaleDateString() : ""}
+                  </div>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+        <div className="aa-modal__footer">
+          <button className="aa-btn" onClick={onClose}>
+            取消
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default TitleLibraryModal

apps/web/src/pages/ai-avatar/hooks/useAiAvatar.ts

@@ -0,0 +1,141 @@
+/**
+ * AI数字人 — 页面全局状态管理 hook（v3）
+ */
+import { useState, useCallback } from "react"
+import type { AssetItem } from "@/api/assets"
+import type { UnifiedVoiceItem } from "@/api/voices/types"
+import {
+  type VoiceSource,
+  type VoiceEmotion,
+  type VoiceLanguage,
+  type Script,
+  type LipsyncJob,
+  type BRollSegment,
+  type AiAvatarTitleConfig,
+  type AiAvatarCoverConfig,
+  DEFAULT_TITLE_CONFIG,
+  DEFAULT_COVER_CONFIG,
+} from "../types"
+
+export function useAiAvatar() {
+  /* ── 面板1：出镜视频 ── */
+  const [selectedVideo, setSelectedVideo] = useState<AssetItem | null>(null)
+  const [showAssetPicker, setShowAssetPicker] = useState(false)
+
+  /* ── 面板2：配音库 ── */
+  const [voiceSource, setVoiceSource] = useState<VoiceSource>("preset")
+  const [selectedVoice, setSelectedVoice] = useState<UnifiedVoiceItem | null>(null)
+  const [emotion, setEmotion] = useState<VoiceEmotion>("natural")
+  const [speed, setSpeed] = useState(1.0)
+  const [language, setLanguage] = useState<VoiceLanguage>("mandarin")
+
+  /* ── 面板3：文案 & 对口型 ── */
+  const [script, setScript] = useState<Script | null>(null)
+  const [scriptText, setScriptText] = useState("")
+  const [lipsyncJob, setLipsyncJob] = useState<LipsyncJob | null>(null)
+  const [showScriptModal, setShowScriptModal] = useState(false)
+  const [showBRollModal, setShowBRollModal] = useState(false)
+
+  /* ── 面板3.5：B-roll ── */
+  const [bRollSegments, setBRollSegments] = useState<BRollSegment[]>([])
+
+  /* ── 面板4：标题配置 ── */
+  const [titleConfig, setTitleConfig] = useState<AiAvatarTitleConfig>(DEFAULT_TITLE_CONFIG)
+
+  /* ── 面板5：封面 & 生成 ── */
+  const [coverConfig, setCoverConfig] = useState<AiAvatarCoverConfig>(DEFAULT_COVER_CONFIG)
+  const [resolution, setResolution] = useState("1080p")
+  const [isGenerating, setIsGenerating] = useState(false)
+
+  /* ── Actions ── */
+  const selectVideo = useCallback((asset: AssetItem) => {
+    setSelectedVideo(asset)
+    setShowAssetPicker(false)
+  }, [])
+
+  const removeVideo = useCallback(() => {
+    setSelectedVideo(null)
+  }, [])
+
+  const selectScript = useCallback((s: Script) => {
+    setScript(s)
+    setScriptText(s.content)
+    setShowScriptModal(false)
+  }, [])
+
+  const addBRollSegment = useCallback((segment: BRollSegment) => {
+    setBRollSegments((prev) => [...prev, segment])
+  }, [])
+
+  const removeBRollSegment = useCallback((id: string) => {
+    setBRollSegments((prev) => prev.filter((s) => s.id !== id))
+  }, [])
+
+  const updateTitleConfig = useCallback((partial: Partial<AiAvatarTitleConfig>) => {
+    setTitleConfig((prev) => ({ ...prev, ...partial }))
+  }, [])
+
+  const reset = useCallback(() => {
+    setSelectedVideo(null)
+    setSelectedVoice(null)
+    setScript(null)
+    setScriptText("")
+    setLipsyncJob(null)
+    setBRollSegments([])
+    setTitleConfig(DEFAULT_TITLE_CONFIG)
+    setCoverConfig(DEFAULT_COVER_CONFIG)
+    setResolution("1080p")
+    setIsGenerating(false)
+  }, [])
+
+  return {
+    // 面板1
+    selectedVideo,
+    showAssetPicker,
+    setShowAssetPicker,
+    selectVideo,
+    removeVideo,
+    // 面板2
+    voiceSource,
+    setVoiceSource,
+    selectedVoice,
+    setSelectedVoice,
+    emotion,
+    setEmotion,
+    speed,
+    setSpeed,
+    language,
+    setLanguage,
+    // 面板3
+    script,
+    setScript,
+    scriptText,
+    setScriptText,
+    lipsyncJob,
+    setLipsyncJob,
+    showScriptModal,
+    setShowScriptModal,
+    showBRollModal,
+    setShowBRollModal,
+    selectScript,
+    // B-roll
+    bRollSegments,
+    addBRollSegment,
+    removeBRollSegment,
+    // 面板4
+    titleConfig,
+    updateTitleConfig,
+    setTitleConfig,
+    // 面板5
+    coverConfig,
+    setCoverConfig,
+    resolution,
+    setResolution,
+    isGenerating,
+    setIsGenerating,
+    // 全局
+    reset,
+  }
+}
+
+export type UseAiAvatarReturn = ReturnType<typeof useAiAvatar>

apps/web/src/pages/ai-avatar/types.ts

@@ -0,0 +1,131 @@
+/**
+ * AI数字人 — TypeScript 类型定义（v3）
+ */
+import type { AssetItem } from "@/api/assets"
+
+/* ── 音色来源切换 ── */
+export type VoiceSource = "preset" | "clone"
+
+/* ── 情绪 ── */
+export type VoiceEmotion = "natural" | "excited" | "calm" | "friendly"
+
+export const VOICE_EMOTION_OPTIONS: { value: VoiceEmotion; label: string }[] = [
+  { value: "natural", label: "自然" },
+  { value: "excited", label: "兴奋" },
+  { value: "calm", label: "沉稳" },
+  { value: "friendly", label: "亲切" },
+]
+
+/* ── 语言 ── */
+export type VoiceLanguage = "mandarin" | "english" | "cantonese"
+
+export const VOICE_LANGUAGE_OPTIONS: { value: VoiceLanguage; label: string }[] = [
+  { value: "mandarin", label: "普通话" },
+  { value: "english", label: "English" },
+  { value: "cantonese", label: "粤语" },
+]
+
+/* ── 对口型任务状态 ── */
+export type LipsyncStatus = "idle" | "pending" | "processing" | "completed" | "failed"
+
+/* ── 文案 ── */
+export interface Script {
+  id: string
+  title: string
+  content: string
+  char_count: number
+  created_at: string
+  updated_at?: string
+}
+
+/* ── 对口型任务 ── */
+export interface LipsyncJob {
+  id: string
+  status: LipsyncStatus
+  progress: number
+  output_video_url: string | null
+  /** 对口型成片总时长（秒），后端返回；用于 B-roll 时间自动估算（#1809 ⑥） */
+  output_duration?: number
+  error_message: string | null
+  created_at: string
+}
+
+/* ── B-roll 画面插入 ── */
+export type BRollInsertMode = "fullscreen" | "pip"
+export type PipPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right"
+
+export interface BRollSegment {
+  id: string
+  asset: AssetItem
+  script_segment_index: number
+  start_time: number
+  end_time: number
+  mode: BRollInsertMode
+  pip_position: PipPosition
+  pip_scale: number
+}
+
+/* ── 标题配置 ── */
+export interface AiAvatarTitleConfig {
+  title: string
+  position: string
+  font: string
+  size: number
+  bold: boolean
+  italic: boolean
+  stroke: boolean
+  shadow: boolean
+  color: string
+  auto_subtitle: boolean
+  /** 自定义位置坐标（position=custom 时生效，像素） */
+  pos_x?: number
+  pos_y?: number
+}
+
+/* ── 封面配置 ── */
+export interface AiAvatarCoverConfig {
+  enabled: boolean
+  mode: "auto_frame" | "upload"
+  frame_time: number
+  upload_url: string | null
+  thumbnail_url: string | null
+  /** 智能封面（MediaKit 选帧）返回的 OSS 非临时 URL（#1822） */
+  smart_cover_url: string | null
+}
+
+/* ── 渲染任务 ── */
+export type RenderStatus = "pending" | "processing" | "completed" | "failed" | "cancelled"
+
+export interface RenderJob {
+  id: string
+  status: RenderStatus
+  progress: number
+  output_video_url: string | null
+  error_message: string | null
+  created_at: string
+}
+
+/* ── 默认值 ── */
+export const DEFAULT_TITLE_CONFIG: AiAvatarTitleConfig = {
+  title: "",
+  position: "bottom",
+  font: "思源黑体",
+  size: 28,
+  bold: true,
+  italic: false,
+  stroke: false,
+  shadow: false,
+  color: "#ffffff",
+  auto_subtitle: true,
+  pos_x: undefined,
+  pos_y: undefined,
+}
+
+export const DEFAULT_COVER_CONFIG: AiAvatarCoverConfig = {
+  enabled: true,
+  mode: "auto_frame",
+  frame_time: 0,
+  upload_url: null,
+  thumbnail_url: null,
+  smart_cover_url: null,
+}

apps/web/src/pages/ai-avatar/utils/contract.ts

@@ -0,0 +1,76 @@
+/**
+ * AI数字人 — 前后端接口契约转换工具（#1822）
+ *
+ * 以 packages/domain/video_filter_builder.py 的 build_title_drawtext_filter() 为唯一口径
+ * （契约文档第 5 节的 titles[]/fontSize/frame/start/end 为误写，后端不认，禁止使用）。
+ */
+import type { AiAvatarTitleConfig, AiAvatarCoverConfig, VoiceEmotion } from "../types"
+
+/* ── 情绪：中文 → 英文（防御性映射；state 默认已是英文） ── */
+const EMOTION_ZH_TO_EN: Record<string, VoiceEmotion> = {
+  自然: "natural",
+  兴奋: "excited",
+  沉稳: "calm",
+  亲切: "friendly",
+}
+const VALID_EMOTIONS: VoiceEmotion[] = ["natural", "excited", "calm", "friendly"]
+
+/** 归一化为后端英文枚举 natural/excited/calm/friendly；非法/空值回退 natural。 */
+export function normalizeEmotion(raw: string | undefined | null): VoiceEmotion {
+  if (!raw) return "natural"
+  const v = raw.trim()
+  if ((VALID_EMOTIONS as string[]).includes(v)) return v as VoiceEmotion
+  return EMOTION_ZH_TO_EN[v] ?? "natural"
+}
+
+/* ── 标题：前端 state → 后端 build_title_drawtext_filter 字段（单个 title_config dict） ── */
+/**
+ * 后端真实字段：text(或content)、font(或font_preset)、font_size(或size)、
+ * font_color(或color，可传 #RRGGBB)、position(top/center/bottom/custom)、
+ * enabled、bold、stroke{enabled,width,color}、shadow{enabled,color,offset_x,offset_y}、
+ * pos_x/pos_y(custom 时)。
+ * 口播标题默认 position=bottom（不传后端会默认 top 跑到画面顶部）。
+ */
+export function buildTitleConfigPayload(cfg: AiAvatarTitleConfig): Record<string, unknown> {
+  const text = (cfg.title || "").trim()
+  if (!text) return {}
+  const position = cfg.position || "bottom"
+  const payload: Record<string, unknown> = {
+    text,
+    enabled: true,
+    font: cfg.font || "思源黑体",
+    font_size: Math.round(cfg.size) || 36,
+    font_color: cfg.color || "#ffffff",
+    position,
+    bold: !!cfg.bold,
+    stroke: cfg.stroke ? { enabled: true, width: 2, color: "#000000" } : { enabled: false },
+    shadow: cfg.shadow
+      ? { enabled: true, color: "#000000", offset_x: 2, offset_y: 2 }
+      : { enabled: false },
+  }
+  // 自定义坐标（custom 位置）
+  if (position === "custom" && typeof cfg.pos_x === "number" && typeof cfg.pos_y === "number") {
+    payload.pos_x = cfg.pos_x
+    payload.pos_y = cfg.pos_y
+  }
+  return payload
+}
+
+/* ── 封面：前端 state → 后端 render cover_config ── */
+export function buildCoverConfigPayload(
+  cfg: AiAvatarCoverConfig,
+  smartCoverUrl: string | null,
+): Record<string, unknown> {
+  const payload: Record<string, unknown> = {
+    enabled: !!cfg.enabled,
+    mode: cfg.mode,
+    // build_cover_extract_command 读取 timestamp（截帧秒数）
+    timestamp: cfg.frame_time || 0,
+  }
+  if (smartCoverUrl) payload.cover_url = smartCoverUrl
+  // 自定义上传：blob: 本地预览地址无法给后端，仅 OSS URL 可用
+  if (cfg.mode === "upload" && cfg.upload_url && !cfg.upload_url.startsWith("blob:")) {
+    payload.upload_url = cfg.upload_url
+  }
+  return payload
+}

apps/web/src/pages/ai-avatar/utils/sentences.ts

@@ -0,0 +1,62 @@
+/**
+ * AI数字人 — 文案分句 & B-roll 时间自动估算（#1809 ⑤⑥）
+ */
+
+export interface ScriptSentence {
+  /** 句子序号（从 0 开始，对应提交给后端的 script_segment_index） */
+  index: number
+  /** 句子文本（去掉首尾空白） */
+  text: string
+  /** 句子字数（按中文/字符计，去除空白） */
+  charCount: number
+  /** 累计起始字数（用于时间估算） */
+  startChar: number
+  /** 估算的对口型视频内起始时间（秒） */
+  startTime: number
+  /** 估算的对口型视频内结束时间（秒） */
+  endTime: number
+}
+
+/**
+ * 按句号/问号/感叹号/分号/换行分句（兼容中英文标点）。
+ * 空文案返回空数组。时间按「该句字数 ÷ 全文总字数 × 口播总时长」线性估算。
+ */
+export function splitScriptIntoSentences(
+  scriptText: string,
+  outputDuration: number,
+): ScriptSentence[] {
+  const text = (scriptText || "").trim()
+  if (!text) return []
+
+  const rawParts = text
+    .split(/[。！？!?；;\n\r]+/)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0)
+
+  const totalChars = rawParts.reduce((sum, part) => sum + part.replace(/\s/g, "").length, 0)
+  const duration = outputDuration > 0 ? outputDuration : 0
+
+  const sentences: ScriptSentence[] = []
+  let accChar = 0
+  rawParts.forEach((part, i) => {
+    const charCount = part.replace(/\s/g, "").length
+    const startTime = duration > 0 && totalChars > 0 ? (accChar / totalChars) * duration : 0
+    const endTime =
+      duration > 0 && totalChars > 0 ? ((accChar + charCount) / totalChars) * duration : 0
+    sentences.push({
+      index: i,
+      text: part,
+      charCount,
+      startChar: accChar,
+      startTime: round1(startTime),
+      endTime: round1(endTime),
+    })
+    accChar += charCount
+  })
+
+  return sentences
+}
+
+function round1(n: number): number {
+  return Math.round(n * 10) / 10
+}

apps/web/src/pages/duplication/duplication.css

@@ -10,7 +10,7 @@
    ============================================================ */
 .dup-page {
   padding: var(--space-2xl) var(--space-lg);
-  max-width: 1100px;
+  max-width: 1400px;
   margin: 0 auto;
 }
 

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

@@ -6440,3 +6440,49 @@
   opacity: 0.6;
   cursor: not-allowed;
 }
+
+/* ═══ 标题设置 — 颜色预设 ═══ */
+.ep-color-presets {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-wrap: wrap;
+}
+
+.ep-color-swatch {
+  width: 24px;
+  height: 24px;
+  border-radius: 4px;
+  border: 2px solid transparent;
+  cursor: pointer;
+  transition:
+    border-color 0.15s,
+    transform 0.1s;
+}
+
+.ep-color-swatch:hover {
+  transform: scale(1.1);
+}
+
+.ep-color-swatch.active {
+  border-color: var(--ep-primary, #4f8cff);
+}
+
+.ep-color-picker {
+  width: 28px;
+  height: 28px;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  padding: 0;
+  background: none;
+}
+
+.ep-color-picker::-webkit-color-swatch-wrapper {
+  padding: 0;
+}
+
+.ep-color-picker::-webkit-color-swatch {
+  border: 1px solid rgba(255, 255, 255, 0.2);
+  border-radius: 4px;
+}

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

@@ -196,6 +196,8 @@ const EditingPlanner: React.FC = () => {
 
         {/* 右栏 260px：设置面板 */}
         <RightPanel
+          titleConfig={titleConfig}
+          onTitleConfigChange={setTitleConfig}
           rightTab={rightTab}
           onTabChange={setRightTab}
           selectedClip={clipOps.selectedClip}

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

@@ -5,12 +5,15 @@
 import React from "react"
 import type { ClipPropertiesPanelProps } from "@/pages/editing-planner/types/clipProperties"
 import SubtitleSettingsSection from "./clip-properties/SubtitleSettingsSection"
+import TitleSettingsSection from "./clip-properties/TitleSettingsSection"
 import BgmSettingsSection from "./clip-properties/BgmSettingsSection"
 import ClipDetailSection from "./clip-properties/ClipDetailSection"
 import StatsSection from "./clip-properties/StatsSection"
 import { useVoicePreview } from "@/pages/editing-planner/hooks/useVoicePreview"
 
 const ClipPropertiesPanel: React.FC<ClipPropertiesPanelProps> = ({
+  titleConfig,
+  onTitleConfigChange,
   selectedClip,
   subtitleSettings,
   bgmSettings,
@@ -40,6 +43,11 @@ const ClipPropertiesPanel: React.FC<ClipPropertiesPanelProps> = ({
 
   return (
     <div className="ep-right-panel">
+      {/* ═══ 标题设置 — #1789 ═══ */}
+      {titleConfig && onTitleConfigChange && (
+        <TitleSettingsSection config={titleConfig} onChange={onTitleConfigChange} />
+      )}
+
       {/* ═══ 字幕设置 ═══ */}
       <SubtitleSettingsSection
         settings={subtitleSettings}

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

@@ -5,9 +5,12 @@ import type { ClipData } from "../types"
 import type { SubtitleStyleConfig } from "../types/subtitle"
 import type { BgmMixConfig } from "@/api/bgm"
 import type { TemplateMode } from "@/api/editing-planner"
+import type { TitleConfig } from "@/api/template-editor"
 import type { AssetItem } from "@/api/assets"
 
 interface RightPanelProps {
+  titleConfig?: TitleConfig
+  onTitleConfigChange?: (config: TitleConfig | ((prev: TitleConfig) => TitleConfig)) => void
   rightTab: "properties" | "clips"
   onTabChange: (tab: "properties" | "clips") => void
   // 属性 tab
@@ -46,6 +49,8 @@ interface RightPanelProps {
 }
 
 const RightPanel: React.FC<RightPanelProps> = ({
+  titleConfig,
+  onTitleConfigChange,
   rightTab,
   onTabChange,
   selectedClip,
@@ -118,6 +123,8 @@ const RightPanel: React.FC<RightPanelProps> = ({
             >["onBgmSettingsChange"]
             return (
               <ClipPropertiesPanel
+                titleConfig={titleConfig}
+                onTitleConfigChange={onTitleConfigChange}
                 selectedClip={selectedClip}
                 subtitleSettings={sub}
                 bgmSettings={bgm}

apps/web/src/pages/editing-planner/components/clip-properties/TitleSettingsSection.tsx

@@ -0,0 +1,136 @@
+/**
+ * 标题设置区块 — #1789
+ * 提供字号滑块、字体预设、位置、颜色等控制入口
+ */
+import React from "react"
+import type { TitleConfig } from "@/api/template-editor"
+import { POSITION_OPTIONS, FONT_OPTIONS } from "@/pages/editing-planner/constants/clipProperties"
+
+interface TitleSettingsSectionProps {
+  config: TitleConfig
+  onChange: (config: TitleConfig | ((prev: TitleConfig) => TitleConfig)) => void
+}
+
+const TITLE_COLOR_PRESETS = [
+  "#ffffff",
+  "#000000",
+  "#ff4444",
+  "#ffaa00",
+  "#44ff44",
+  "#4488ff",
+  "#ff44ff",
+  "#ffff44",
+]
+
+const TitleSettingsSection: React.FC<TitleSettingsSectionProps> = ({ config, onChange }) => {
+  const update = (partial: Partial<TitleConfig>) => {
+    onChange((prev: TitleConfig) => ({ ...prev, ...partial }))
+  }
+
+  return (
+    <div className="ep-settings-section">
+      <div className="ep-section-title">
+        <span className="ep-section-icon">📝</span>
+        标题设置
+      </div>
+
+      {/* AI 自动选择开关 */}
+      <div className="ep-toggle-row">
+        <span className="ep-toggle-label">AI 自动选择</span>
+        <div
+          className={`ep-toggle ${config.ai_auto_select ? "active" : ""}`}
+          onClick={() => update({ ai_auto_select: !config.ai_auto_select })}
+        >
+          <div className="ep-toggle-knob" />
+        </div>
+      </div>
+
+      {!config.ai_auto_select && (
+        <>
+          {/* 标题文本 */}
+          <div className="ep-field">
+            <label className="ep-field-label">标题文本</label>
+            <input
+              className="ep-form-select"
+              type="text"
+              placeholder="输入标题内容"
+              value={config.content}
+              onChange={(e) => update({ content: e.target.value })}
+            />
+          </div>
+
+          {/* 位置 */}
+          <div className="ep-field">
+            <label className="ep-field-label">位置</label>
+            <select
+              className="ep-form-select"
+              value={config.position}
+              onChange={(e) => update({ position: e.target.value })}
+            >
+              {POSITION_OPTIONS.map((opt) => (
+                <option key={opt.value} value={opt.value}>
+                  {opt.label}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          {/* 字体预设 */}
+          <div className="ep-field">
+            <label className="ep-field-label">字体</label>
+            <select
+              className="ep-form-select"
+              value={config.font_preset}
+              onChange={(e) => update({ font_preset: e.target.value })}
+            >
+              {FONT_OPTIONS.map((f) => (
+                <option key={f} value={f}>
+                  {f}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          {/* 字号滑块 */}
+          <div className="ep-field">
+            <label className="ep-field-label">字号</label>
+            <div className="ep-slider-row">
+              <input
+                className="ep-slider"
+                type="range"
+                min={12}
+                max={72}
+                value={config.font_size}
+                onChange={(e) => update({ font_size: Number(e.target.value) })}
+              />
+              <span className="ep-slider-value">{config.font_size}px</span>
+            </div>
+          </div>
+
+          {/* 颜色 */}
+          <div className="ep-field">
+            <label className="ep-field-label">颜色</label>
+            <div className="ep-color-presets">
+              {TITLE_COLOR_PRESETS.map((color) => (
+                <div
+                  key={color}
+                  className={`ep-color-swatch${config.font_color === color ? " active" : ""}`}
+                  style={{ backgroundColor: color }}
+                  onClick={() => update({ font_color: color })}
+                />
+              ))}
+              <input
+                type="color"
+                className="ep-color-picker"
+                value={config.font_color}
+                onChange={(e) => update({ font_color: e.target.value })}
+              />
+            </div>
+          </div>
+        </>
+      )}
+    </div>
+  )
+}
+
+export default TitleSettingsSection

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

@@ -4,6 +4,7 @@
 import type { ClipData } from "./clip"
 import type { TemplateMode } from "@/api/editing-planner"
 import type { AssetItem } from "@/api/assets"
+import type { TitleConfig } from "@/api/template-editor"
 
 export interface SubtitleSettings {
   enabled: boolean
@@ -28,6 +29,10 @@ export interface BgmSettings {
 }
 
 export interface ClipPropertiesPanelProps {
+  /** 标题配置 — #1789 */
+  titleConfig?: TitleConfig
+  /** 标题配置变更 */
+  onTitleConfigChange?: (config: TitleConfig | ((prev: TitleConfig) => TitleConfig)) => void
   selectedClip: ClipData | null
   subtitleSettings: SubtitleSettings
   bgmSettings: BgmSettings

apps/web/src/pages/editing-planner/utils/timeline.ts

@@ -13,6 +13,8 @@ export const formatTrimTime = (sec: number): string => {
 /** 生成时间标尺刻度 */
 export const generateRulerMarks = (totalDuration: number, step: number): number[] => {
   const marks: number[] = []
+  // #1790: 无片段时不显示时间刻度
+  if (totalDuration <= 0) return marks
   for (let t = 0; t <= totalDuration + step; t += step) {
     marks.push(t)
   }

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

@@ -45,6 +45,7 @@ const GeneratePage: React.FC = () => {
     selectedTemplate,
     setSelectedTemplate,
     userTemplates,
+    handleInvalidTemplate,
     selectedMaterials,
     setSelectedMaterials,
     materialMode,
@@ -416,15 +417,11 @@ const GeneratePage: React.FC = () => {
   /* ── 最终成片（单视频右侧播放） ── */
   const finalVideo = generatedVideos[0]
 
-  /* ── 布局 class：步骤4标题页=预览+标题侧栏；步骤5/6批量=整行宽；步骤1~3=整行宽 ── */
+  /* ── 布局 class：步骤4标题页=预览+标题侧栏两栏；其余步骤（含步骤5确认生成、步骤6封面）=整行宽 ── */
   const layoutClassName = useMemo(() => {
-    if (currentStep < 4) return "xx-generate-layout full-width"
     if (currentStep === 4) return "xx-generate-layout step4-layout"
-    // 步骤5：全宽+内容居中（单视频视频播放器居中，批量网格居中）
-    if (currentStep === 5) return "xx-generate-layout full-width"
-    // 步骤6：封面选择保持两栏布局
-    return isBatch ? "xx-generate-layout full-width" : "xx-generate-layout"
-  }, [currentStep, isBatch])
+    return "xx-generate-layout full-width"
+  }, [currentStep])
 
   /* ================================================================
      渲染
@@ -524,6 +521,7 @@ const GeneratePage: React.FC = () => {
             selectedVoice={selectedVoice}
             onSelectedVoiceChange={setSelectedVoice}
             onServerClipsChange={setServerClips}
+            onTemplateInvalid={handleInvalidTemplate}
             generating={generating}
             generated={generated}
             generateError={generateError}
@@ -545,26 +543,26 @@ const GeneratePage: React.FC = () => {
             selectedVariantIds={selectedVariantIds}
           />
 
-          <GenerateStepActions
-            currentStep={currentStep}
-            onPrev={goPrev}
-            onNext={goNext}
-            onConfirmGenerate={handleConfirmGenerate}
-            generating={generating}
-            generated={generated}
-            generateError={generateError}
-            selectedCount={isBatch ? selectedVariantIds.length : 1}
-          />
-
-          {/* ════ 步骤5（单视频）：成片播放器内联居中（#1761） ════ */}
+          {/* ════ 步骤5（单视频）：成片播放器置于按钮上方、居中展示 ════ */}
           {currentStep === 5 && !isBatch && generated && finalVideo && (
             <div
               style={{
                 display: "flex",
-                justifyContent: "center",
+                flexDirection: "column",
+                alignItems: "center",
                 marginTop: 16,
               }}
             >
+              <h2
+                style={{
+                  textAlign: "center",
+                  marginBottom: 12,
+                  fontSize: "1.5rem",
+                  fontWeight: 600,
+                }}
+              >
+                🎬 确认生成
+              </h2>
               <div
                 style={{
                   display: "flex",
@@ -580,6 +578,7 @@ const GeneratePage: React.FC = () => {
                 <video
                   src={finalVideo.download_url || finalVideo.file_url}
                   controls
+                  autoPlay
                   style={{
                     width: "auto",
                     maxWidth: "100%",
@@ -607,55 +606,18 @@ const GeneratePage: React.FC = () => {
               </div>
             </div>
           )}
-        </div>
 
-        {/* ════ 步骤6（单视频）：右侧成片播放器 ════ */}
-        {currentStep >= 6 && !isBatch && generated && finalVideo && (
-          <div className="xx-generate-right-col">
-            <div
-              className="xx-inline-video-player"
-              style={{
-                display: "flex",
-                justifyContent: "center",
-                alignItems: "center",
-                background: "#000",
-                borderRadius: 12,
-                padding: 8,
-              }}
-            >
-              <video
-                src={finalVideo.download_url || finalVideo.file_url}
-                controls
-                autoPlay={currentStep === 5}
-                // 竖屏自适应（#1750）：成片固定 1080×1920（9:16），元数据到达前按 9:16 占位，
-                // 到达后浏览器按真实宽高比 contain；黑底居中杜绝左右大黑边
-                style={{
-                  width: "auto",
-                  maxWidth: "100%",
-                  maxHeight: "70vh",
-                  aspectRatio: "9 / 16",
-                  objectFit: "contain",
-                  borderRadius: 8,
-                }}
-                poster={finalVideo.thumbnail_url || undefined}
-              />
-              <div style={{ display: "flex", gap: 8, marginTop: 12, justifyContent: "center" }}>
-                <button className="xx-btn xx-btn-ghost xx-btn-sm" onClick={handleDownload}>
-                  ⬇️ 下载
-                </button>
-                <button className="xx-btn xx-btn-ghost xx-btn-sm" onClick={handleShare}>
-                  🔗 分享
-                </button>
-                <button
-                  className="xx-btn xx-btn-ghost xx-btn-sm"
-                  onClick={() => navigate("/app/products")}
-                >
-                  📁 前往成片库
-                </button>
-              </div>
-            </div>
-          </div>
-        )}
+          <GenerateStepActions
+            currentStep={currentStep}
+            onPrev={goPrev}
+            onNext={goNext}
+            onConfirmGenerate={handleConfirmGenerate}
+            generating={generating}
+            generated={generated}
+            generateError={generateError}
+            selectedCount={isBatch ? selectedVariantIds.length : 1}
+          />
+        </div>
       </div>
 
       {/* 数量选择弹窗 */}

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

@@ -38,7 +38,7 @@ const BatchGenerationGrid: React.FC<BatchGenerationGridProps> = ({
         className="xx-batch-gen-grid"
         style={{
           display: "grid",
-          gridTemplateColumns: "repeat(auto-fill, minmax(160px, 180px))",
+          gridTemplateColumns: "repeat(auto-fill, minmax(280px, 320px))",
           justifyContent: "center",
           justifyItems: "center",
           gap: 14,
@@ -52,7 +52,7 @@ const BatchGenerationGrid: React.FC<BatchGenerationGridProps> = ({
             <div
               key={task.taskId}
               className={`xx-batch-gen-card status-${task.status}`}
-              style={{ maxWidth: 240 }}
+              style={{ maxWidth: 320 }}
             >
               <div className="xx-batch-gen-card-head">
                 <span className="xx-batch-gen-card-title" title={title}>

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

@@ -50,6 +50,8 @@ export interface GenerateStepContentProps {
   selectedVoice: string
   onSelectedVoiceChange: (id: string) => void
   onServerClipsChange: (clips: EditPlanClip[]) => void
+  /** 当前模板创建片段被判失效（404/400/422）时的自动回退回调（#1777） */
+  onTemplateInvalid?: () => boolean
   /* 生成 */
   generating: boolean
   generated: boolean
@@ -108,6 +110,7 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
     selectedVoice,
     onSelectedVoiceChange,
     onServerClipsChange,
+    onTemplateInvalid,
     generating,
     generated,
     generateError,
@@ -153,6 +156,7 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
           selectedTemplate={selectedTemplate}
           templateSegments={templateSegments}
           onServerClipsChange={onServerClipsChange}
+          onTemplateInvalid={onTemplateInvalid}
         />
       )
     case 3:
@@ -189,7 +193,7 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
         />
       )
     case 5:
-      /* 确认生成页：批量=逐任务进度网格；单视频=进度状态卡（成片播放器在左侧大区域） */
+      /* 确认生成页：批量=逐任务进度网格；单视频=仅渲染进度/失败状态（完成后只显示成片播放器，播放器在按钮上方） */
       if (previewCount > 1) {
         return (
           <BatchGenerationGrid
@@ -199,10 +203,10 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
           />
         )
       }
-      /* 单视频：渲染进度 / 失败重试 / 完成提示（成片播放器在右侧栏） */
+      /* 单视频：生成中显示进度卡、失败显示重试卡；生成完成后不再渲染提示卡，页面只保留成片播放器+操作按钮 */
+      if (generated && !generating && !generateError) return null
       return (
         <div className="xx-form-section">
-          <h3>🎬 确认生成</h3>
           {generating && (
             <div className="xx-gen-progress-card">
               <div className="xx-gen-progress-header">
@@ -234,14 +238,6 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
               </button>
             </div>
           )}
-          {generated && !generating && (
-            <div className="xx-gen-success-card">
-              <div className="xx-gen-success-info">
-                <div className="xx-gen-success-title">✅ 视频生成完成！</div>
-                <div className="xx-gen-success-sub">右侧可预览成片，点击「下一步」选择封面</div>
-              </div>
-            </div>
-          )}
         </div>
       )
     case 6:

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

@@ -23,6 +23,8 @@ interface Step2MaterialSelectProps {
   templateSegments?: TemplateSegment[]
   /** 服务端 clips 创建成功后的回调 */
   onServerClipsChange?: (clips: EditPlanClip[]) => void
+  /** 当前模板创建片段返回 404/400/422（模板失效）时的自动回退回调（#1777） */
+  onTemplateInvalid?: () => boolean
 }
 
 const Step2MaterialSelect: React.FC<Step2MaterialSelectProps> = (props) => {
@@ -36,16 +38,25 @@ const Step2MaterialSelect: React.FC<Step2MaterialSelectProps> = (props) => {
 
       <div className="xx-form-field" style={{ marginTop: 12 }}>
         <label>选择视频库</label>
-        <select
-          value={m.selectedLibraryId}
-          onChange={(e) => m.setSelectedLibraryId(e.target.value)}
-        >
-          {m.libraries.map((lib) => (
-            <option key={lib.id} value={lib.id}>
-              {lib.name}
-            </option>
-          ))}
-        </select>
+        {m.libraries.length === 0 && !m.materialsLoading ? (
+          <div className="xx-empty-state">
+            <p>暂无视频素材库</p>
+            <p style={{ fontSize: 13, color: "var(--text-tertiary)" }}>
+              请先在「素材库」中创建视频素材库并上传视频
+            </p>
+          </div>
+        ) : (
+          <select
+            value={m.selectedLibraryId}
+            onChange={(e) => m.setSelectedLibraryId(e.target.value)}
+          >
+            {m.libraries.map((lib) => (
+              <option key={lib.id} value={lib.id}>
+                {lib.name}
+              </option>
+            ))}
+          </select>
+        )}
       </div>
 
       {m.materialMode === "manual" && (

apps/web/src/pages/generate/components/step7-confirm/GenerationStatus.tsx

@@ -1,117 +0,0 @@
-import React from "react"
-import { LoadingOutlined, CheckCircleFilled, CloseCircleOutlined } from "@ant-design/icons"
-import type { GeneratedVideo } from "@/api/template-editor"
-
-interface GenerationStatusProps {
-  generating: boolean
-  generated: boolean
-  generateError: string | null
-  progress: number
-  generatedVideos: GeneratedVideo[]
-  getGenerationPhase: (progress: number) => { icon: string; label: string }
-  onScrollToPreview: () => void
-  onRetry: () => void
-  onDismissError: () => void
-}
-
-const GenerationStatus: React.FC<GenerationStatusProps> = ({
-  generating,
-  generated,
-  generateError,
-  progress,
-  generatedVideos,
-  getGenerationPhase,
-  onScrollToPreview,
-  onRetry,
-  onDismissError,
-}) => {
-  return (
-    <div style={{ marginTop: 16 }}>
-      {!generating && !generated && !generateError && (
-        <div className="xx-gen-progress-card" style={{ opacity: 0.85 }}>
-          <div className="xx-gen-progress-header">
-            <div className="xx-gen-progress-icon">🎬</div>
-            <div className="xx-gen-progress-info">
-              <div className="xx-gen-progress-phase">尚未开始生成视频</div>
-              <div className="xx-gen-progress-sub">
-                请返回「选择标题」步骤，点击「确认生成视频」开始渲染最终视频
-              </div>
-            </div>
-          </div>
-        </div>
-      )}
-      {generating && (
-        <div className="xx-gen-progress-card">
-          <div className="xx-gen-progress-header">
-            <div className="xx-gen-progress-icon">
-              <LoadingOutlined />
-            </div>
-            <div className="xx-gen-progress-info">
-              <div className="xx-gen-progress-phase">
-                {getGenerationPhase(progress).icon} {getGenerationPhase(progress).label}
-              </div>
-              <div className="xx-gen-progress-sub">预计还需 1-2 分钟，请稍候…</div>
-            </div>
-            <div className="xx-gen-progress-percent">{Math.round(progress)}%</div>
-          </div>
-          <div className="xx-gen-progress-bar">
-            <div
-              className="xx-gen-progress-bar-fill"
-              style={{ width: `${Math.min(Math.round(progress), 100)}%` }}
-            />
-          </div>
-          <div className="xx-gen-progress-tip">
-            💡 生成过程中可以切换到其他页面操作，完成后会自动通知
-          </div>
-        </div>
-      )}
-      {generated && !generating && (
-        <div className="xx-gen-success-card">
-          <div className="xx-gen-success-icon">
-            <CheckCircleFilled style={{ fontSize: 32, color: "#52c41a" }} />
-          </div>
-          <div className="xx-gen-success-info">
-            <div className="xx-gen-success-title">视频生成完成！</div>
-            <div className="xx-gen-success-sub">
-              共生成 {generatedVideos.length} 条视频，可在右侧预览或前往成片库查看
-            </div>
-          </div>
-          <button
-            type="button"
-            className="xx-btn xx-btn-primary xx-btn-sm"
-            onClick={onScrollToPreview}
-          >
-            查看结果
-          </button>
-        </div>
-      )}
-      {generateError && !generating && (
-        <div className="xx-gen-error-card">
-          <div className="xx-gen-error-icon">
-            <CloseCircleOutlined style={{ fontSize: 28, color: "#ef4444" }} />
-          </div>
-          <div className="xx-gen-error-info">
-            <div className="xx-gen-error-title">生成失败</div>
-            <div className="xx-gen-error-msg">
-              {typeof generateError === "string" ? generateError : JSON.stringify(generateError)}
-            </div>
-          </div>
-          <div style={{ display: "flex", gap: 8 }}>
-            <button type="button" className="xx-btn xx-btn-primary xx-btn-sm" onClick={onRetry}>
-              🔄 重试
-            </button>
-            <button
-              type="button"
-              className="xx-btn xx-btn-ghost xx-btn-sm"
-              onClick={onDismissError}
-            >
-              知道了
-            </button>
-          </div>
-        </div>
-      )}
-    </div>
-  )
-}
-
-export default GenerationStatus

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

@@ -0,0 +1,192 @@
+/* ============================================================
+   TitleStylePanel 标题样式面板 — 独立共用样式（#1809 ⑦）
+
+   从 generate.css 抽取的标题样式区块，供「智能剪辑」与「AI数字人」
+   两个页面共用。AI数字人页面不引入 generate.css，直接由
+   TitleStylePanel.tsx import 本文件，保证 24 个 T 预设格子的网格布局、
+   配色描边、选中态与智能剪辑页面完全一致。
+
+   注意：本文件规则与 generate.css 中同名规则一一对应、取值相同；
+   智能剪辑页面两处同时存在时同优先级同值，不改变其原有呈现。
+   ============================================================ */
+
+/* ── 区块容器 ── */
+.xx-title-style-section {
+  margin-top: 22px;
+  padding-top: 20px;
+  border-top: 1px solid var(--border-light);
+}
+
+.xx-section-subtitle {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary);
+  margin: 0 0 16px;
+}
+
+.xx-title-style-row {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 14px;
+  margin-bottom: 14px;
+}
+
+.xx-half-field {
+  margin-bottom: 0;
+}
+
+.xx-field-label-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+}
+
+.xx-field-label-row label {
+  margin-bottom: 0;
+}
+
+.xx-field-value {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--primary-color);
+}
+
+/* ── 共用表单字段（位置/字体下拉） ── */
+.xx-title-style-section .xx-form-field {
+  margin-bottom: 14px;
+}
+
+.xx-title-style-section .xx-form-field:last-child {
+  margin-bottom: 0;
+}
+
+.xx-title-style-section .xx-form-field label {
+  display: block;
+  font-weight: 600;
+  margin-bottom: 8px;
+  font-size: 13px;
+  color: var(--text-primary);
+}
+
+.xx-title-style-section .xx-form-field select,
+.xx-title-style-section .xx-form-field input {
+  width: 100%;
+  height: 44px;
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+  background: var(--bg-primary);
+  padding: 0 14px;
+  font-size: 14px;
+  outline: 0;
+  transition: 0.15s ease;
+  color: var(--text-primary);
+}
+
+.xx-title-style-section .xx-form-field select:focus,
+.xx-title-style-section .xx-form-field input:focus {
+  border-color: var(--primary-color);
+  box-shadow: 0 0 0 3px rgba(79, 70, 229, 0.1);
+}
+
+/* ── 字号滑块 ── */
+.xx-slider {
+  width: 100%;
+  height: 6px;
+  -webkit-appearance: none;
+  appearance: none;
+  background: var(--border-color);
+  border-radius: 3px;
+  outline: none;
+  cursor: pointer;
+}
+
+.xx-slider::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 18px;
+  height: 18px;
+  background: var(--primary-color);
+  border-radius: 50%;
+  cursor: pointer;
+  box-shadow: 0 2px 6px rgba(79, 70, 229, 0.3);
+}
+
+.xx-slider::-moz-range-thumb {
+  width: 18px;
+  height: 18px;
+  background: var(--primary-color);
+  border-radius: 50%;
+  cursor: pointer;
+  border: none;
+  box-shadow: 0 2px 6px rgba(79, 70, 229, 0.3);
+}
+
+/* ── 标题预设卡片网格（24 个 T 格子） ── */
+.xx-title-presets-grid {
+  display: grid;
+  grid-template-columns: repeat(6, 52px);
+  gap: 1px;
+}
+
+.xx-title-preset-card {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 52px;
+  height: 52px;
+  padding: 0;
+  background: #404040;
+  border: 2px solid transparent;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: all 0.15s;
+}
+
+.xx-title-preset-card:hover {
+  border-color: #666;
+  background: #4d4d4d;
+}
+
+.xx-title-preset-card.active {
+  border-color: #409eff;
+  background: #4d4d4d;
+}
+
+.xx-title-preset-preview-text {
+  font-size: 32px;
+  line-height: 1;
+  user-select: none;
+}
+
+/* ── 样式按钮组（加粗/斜体/描边/阴影） ── */
+.xx-style-btns {
+  display: flex;
+  gap: 8px;
+}
+
+.xx-style-btn {
+  width: 40px;
+  height: 40px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+  background: var(--bg-primary);
+  cursor: pointer;
+  font-size: 15px;
+  color: var(--text-secondary);
+  transition: all 0.15s;
+}
+
+.xx-style-btn:hover {
+  border-color: var(--primary-300);
+  color: var(--primary-color);
+}
+
+.xx-style-btn.active {
+  background: var(--primary-color);
+  border-color: var(--primary-color);
+  color: #fff;
+}

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

@@ -5,6 +5,9 @@
 import React from "react"
 import type { TitleSettings } from "../../types"
 import TitlePresetsGrid from "./TitlePresetsGrid"
+// 标题样式面板共用样式（#1809 ⑦）：智能剪辑与 AI数字人复用同一组件，
+// 由组件自带样式，避免 AI数字人页面重复引入整个 generate.css
+import "./TitleStylePanel.css"
 
 interface PositionOption {
   value: string

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

@@ -10,7 +10,7 @@
 .xx-generate-page {
   min-height: 100%;
   padding: var(--space-xl);
-  max-width: 1400px;
+  max-width: 1680px;
   margin: 0 auto;
 }
 
@@ -117,10 +117,6 @@
   grid-template-columns: 1fr;
 }
 
-.xx-generate-layout.full-width .xx-generate-right-col {
-  display: none;
-}
-
 /* ============================================================
    左侧表单区 generate-form
    ============================================================ */
@@ -2323,28 +2319,6 @@
    生成结果（右侧）
    ================================================================ */
 
-.xx-generate-right-col {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: 16px;
-}
-
-/* ── 内联视频播放器（右侧） ── */
-.xx-inline-video-player {
-  width: 100%;
-  max-width: 320px;
-  background: var(--bg-surface, #fff);
-  border: 1px solid var(--border-primary, #e2e8f0);
-  border-radius: 16px;
-  padding: 16px;
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04);
-}
-
-.xx-inline-video-player video {
-  background: #000;
-}
-
 .xx-preview-header {
   display: flex;
   align-items: center;
@@ -2710,11 +2684,12 @@
 
 /* ── 封面设置区域改造样式 ── */
 
-/* 封面操作按钮区 */
+/* 封面操作按钮区（单视频全宽页居中） */
 .xx-cover-actions {
   display: flex;
   gap: 12px;
   margin-bottom: 12px;
+  justify-content: center;
 }
 
 /* 已选模板文字 */
@@ -3202,10 +3177,11 @@
   margin: 0;
 }
 
-/* ── 批量封面网格 ── */
+/* ── 批量封面网格（单卡/少卡时居中排列，卡片限宽不拉伸） ── */
 .xx-cover-grid {
   display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
+  grid-template-columns: repeat(auto-fill, minmax(180px, 220px));
+  justify-content: center;
   gap: 16px;
 }
 

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

@@ -8,11 +8,22 @@ import type { AssetItem } from "@/api/assets"
  * 管理素材库列表、当前选中库、素材列表加载
  */
 export function useMaterialLibrary() {
-  /* ── 素材库数据 API ── */
-  const { data: libraries = [] } = useQuery({
-    queryKey: ["asset-libraries"],
-    queryFn: getAssetLibraries,
+  /* ── 素材库数据 API ──
+   * Step2 是视频选片，只拉取 kind=video 的素材库（#1777）：
+   * 后端按 kind 查询参数过滤，前端 getAssetLibraries("video") 再兜底过滤一次，
+   * 避免配音库(voice)/图片库(image) 混进「选择视频库」下拉。
+   * queryKey 带 kind，与素材管理页/配音页的 ["asset-libraries"] 全量缓存隔离。
+   */
+  const { data: allLibraries = [] } = useQuery({
+    queryKey: ["asset-libraries", "video"],
+    queryFn: () => getAssetLibraries("video"),
+    staleTime: 60_000,
   })
+  // 前端兜底过滤：仅保留 kind=video 的素材库（后端按 kind 查询参数过滤）
+  const libraries = useMemo(
+    () => allLibraries.filter((lib) => lib.kind === "video"),
+    [allLibraries],
+  )
   const [selectedLibraryId, setSelectedLibraryId] = useState<string>("")
 
   // 自动选中第一个视频库

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

@@ -40,6 +40,8 @@ export interface GenerateFormState {
   selectedTemplate: string
   setSelectedTemplate: (id: string) => void
   userTemplates: EditingTemplate[]
+  /** 当前选中模板在创建片段时被判失效（404/400/422）后的运行时自动回退 */
+  handleInvalidTemplate: () => boolean
 
   /* 素材 */
   selectedMaterials: string[]
@@ -131,7 +133,8 @@ export const useGenerateFormState = (): GenerateFormState => {
   const [currentStep, setCurrentStep] = useState(1)
 
   /* ── 模板选择 ── */
-  const { selectedTemplate, setSelectedTemplate, userTemplates } = useTemplateSelection()
+  const { selectedTemplate, setSelectedTemplate, userTemplates, handleInvalidTemplate } =
+    useTemplateSelection()
 
   /* ── source_edit_plan_id：仅取 URL 参数，无则 null 让后端兜底 ── */
   // selectedTemplate 是模板 ID 而非 edit_plan_id，不能混淆；
@@ -228,6 +231,7 @@ export const useGenerateFormState = (): GenerateFormState => {
     selectedTemplate,
     setSelectedTemplate,
     userTemplates,
+    handleInvalidTemplate,
     selectedMaterials,
     setSelectedMaterials,
     materialMode,

apps/web/src/pages/generate/hooks/useGenerateFormState/templateFallback.ts

@@ -0,0 +1,81 @@
+/**
+ * 失效模板判定与自动回退工具（#1777）
+ *
+ * 背景：用户进入生成页后，之前选中的模板可能已被删除、或从未配置片段。
+ * 调用片段相关接口（PUT/POST /templates/{id}/editor/clips[...]/from-assets）时：
+ *   - 模板不存在 → 后端返回 404（并行工单 #1774 把「模板不存在」统一为该状态码）
+ *   - 模板无片段配置 → 当前部分场景返回 400（detail 含「片段配置」），
+ *     参数校验类错误返回 422
+ * 这三类响应都说明「当前选中的模板不可用于生成」，应清除失效选择并自动切换到
+ * 第一个有效模板，同时提示用户，而不是让页面卡死、无任何反馈。
+ */
+import type { EditingTemplate } from "@/api/editing-planner"
+
+/** 失效模板相关的 HTTP 状态码 */
+const INVALID_TEMPLATE_STATUSES = new Set([404, 400, 422])
+
+/**
+ * 从任意抛出值（axios 错误）提取 HTTP 状态码。
+ * 非 axios 错误 / 无响应时返回 null。
+ */
+export function getHttpStatus(err: unknown): number | null {
+  if (!err || typeof err !== "object") return null
+  const status = (err as { response?: { status?: number }; status?: number })?.response?.status
+  return typeof status === "number" ? status : null
+}
+
+/** 安全提取后端错误文本（detail/message/msg，422 数组也兜底拼一下） */
+function extractErrorText(err: unknown): string {
+  if (!err || typeof err !== "object") return ""
+  const data = (err as { response?: { data?: unknown } })?.response?.data
+  if (!data) return ""
+  try {
+    const text = JSON.stringify(data)
+    return typeof text === "string" ? text : ""
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * 判断一次 clips/from-assets 请求失败是否因为「模板失效」。
+ *
+ * 严格判定，避免把无关的 400/422（例如素材参数问题）误判为模板失效：
+ *   - 404：模板/编辑计划不存在，一定是模板失效
+ *   - 400：仅当后端文本明确提到「片段配置」（无片段配置无法创建片段）才判定
+ *   - 422：参数校验类，from-assets 场景下命中「片段/segments」相关字段才判定
+ */
+export function isInvalidTemplateError(err: unknown): boolean {
+  const status = getHttpStatus(err)
+  if (status === null || !INVALID_TEMPLATE_STATUSES.has(status)) return false
+  if (status === 404) return true
+
+  const text = extractErrorText(err)
+  if (status === 400) {
+    // 后端当前返回：「模板没有片段配置，无法创建片段」
+    return /片段配置|没有片段|无片段|segments?|clip.*config/i.test(text)
+  }
+  // 422：FastAPI 校验错误，命中模板片段相关字段
+  return /segment|clip|片段|模板/i.test(text)
+}
+
+/**
+ * 判断模板是否可用于生成（有效模板）。
+ *
+ * 有效 = 处于激活态（is_active !== false，字段缺失视为 true 兼容旧后端）
+ *        且至少配置了一个片段。
+ * 与后端 valid_only 过滤口径保持一致（#1769/#1772），这里是前端双保险。
+ */
+export function isValidTemplate(template: EditingTemplate | null | undefined): boolean {
+  if (!template) return false
+  if (template.is_active === false) return false
+  return (template.segments?.length ?? 0) > 0
+}
+
+/** 从模板列表中取出第一个有效模板，没有则返回 null */
+export function findFirstValidTemplate(
+  templates: EditingTemplate[] | null | undefined,
+): EditingTemplate | null {
+  if (!Array.isArray(templates)) return null
+  return templates.find(isValidTemplate) ?? null
+}

apps/web/src/pages/generate/hooks/useGenerateFormState/useTemplateSelection.ts

@@ -1,22 +1,89 @@
-import { useState, useEffect } from "react"
+import { useState, useEffect, useRef, useCallback, useMemo } from "react"
 import { useQuery } from "@tanstack/react-query"
+import { message } from "antd"
 import { getEditingTemplates } from "@/api/editing-planner"
 import type { EditingTemplate } from "@/api/editing-planner"
+import { findFirstValidTemplate, isValidTemplate } from "./templateFallback"
+
+/** 失效模板自动切换的提示文案 */
+export const INVALID_TEMPLATE_FALLBACK_TOAST = "原模板已失效，已自动切换"
 
 export function useTemplateSelection() {
+  // selectedTemplate 纯内存状态，绝不写入 localStorage/sessionStorage/URL，
+  // 因此失效模板 ID 不会被持久化、刷新后也不会恢复（#1777 要求 4）
   const [selectedTemplate, setSelectedTemplate] = useState("")
-  const { data: userTemplates = [] } = useQuery<EditingTemplate[]>({
+
+  const { data: allTemplates = [] } = useQuery<EditingTemplate[]>({
     queryKey: ["generate-templates"],
-    queryFn: () => getEditingTemplates(),
+    // valid_only：后端过滤掉没有片段配置的无效模板（#1769/#1772）。
+    // 旧后端忽略该 query 参数时，下方 isValidTemplate 前端兜底再过滤一次。
+    queryFn: () => getEditingTemplates({ validOnly: true }),
     staleTime: 60_000,
   })
 
-  /* 模板加载完成后自动选中第一个 */
-  useEffect(() => {
-    if (userTemplates.length > 0 && !selectedTemplate) {
-      setSelectedTemplate(userTemplates[0].id)
-    }
-  }, [userTemplates, selectedTemplate])
+  // 双保险：后端 valid_only 已过滤，前端再按 is_active + segments 兜底，
+  // 保证下拉/自动选择只包含可用于生成的有效模板。
+  // 用 useMemo 缓存引用，避免每次渲染都 .filter 创建新数组，
+  // 导致下游 useTitleCoverSync effect 无限触发、覆盖用户手动修改（#1789）
+  const validTemplates = useMemo(() => allTemplates.filter(isValidTemplate), [allTemplates])
+  const userTemplates = validTemplates
 
-  return { selectedTemplate, setSelectedTemplate, userTemplates }
+  // 用 ref 持有最新值，供稳定回调 handleInvalidTemplate 使用（避免闭包拿到旧值）
+  const templatesRef = useRef(validTemplates)
+  templatesRef.current = validTemplates
+  const selectedRef = useRef(selectedTemplate)
+  selectedRef.current = selectedTemplate
+  // 已提示过失效的模板 ID，避免用户停留在失效模板上时 clips 防抖请求反复弹 toast；
+  // 用户手动切换/成功切换后重置，保证下一个失效模板仍能提示
+  const fallbackNotifiedRef = useRef<string>("")
+
+  /* 自动选择：模板加载完成且当前未选中时，自动选中第一个有效模板。
+   * 用户手动选择（setSelectedTemplate 被显式调用）后 selectedTemplate 非空，
+   * 本 effect 直接 return，绝不覆盖用户的手动选择（#1777 要求 4：手动优先）。 */
+  useEffect(() => {
+    if (selectedTemplate) return
+    const firstValid = validTemplates[0]
+    if (firstValid) {
+      setSelectedTemplate(firstValid.id)
+    }
+  }, [validTemplates, selectedTemplate])
+
+  /** 用户手动选择模板：优先级最高，重置失效提示标记 */
+  const handleSelectTemplate = useCallback((id: string) => {
+    fallbackNotifiedRef.current = ""
+    setSelectedTemplate(id)
+  }, [])
+
+  /**
+   * 运行时失效回退（#1777 要求 3）：
+   * 创建片段接口返回 404（模板不存在）/ 400/422（模板无片段配置）时调用。
+   *  - 清除失效选择，自动切换到第一个有效模板，并 toast 提示；
+   *  - 没有有效模板时清空选择，Step1 展示明确的「暂无可用模板」空状态引导，
+   *    不让用户卡在失效模板上。
+   * 返回 true 表示已按「模板失效」处理（调用方可据此静默原始错误提示）。
+   */
+  const handleInvalidTemplate = useCallback((): boolean => {
+    const current = selectedRef.current
+    // 同一个失效模板只提示一次（clips 防抖 effect 在素材/模板变化时会反复触发）
+    if (current && fallbackNotifiedRef.current === current) return true
+
+    const fallback = findFirstValidTemplate(templatesRef.current)
+    fallbackNotifiedRef.current = current || "__empty__"
+    if (fallback) {
+      setSelectedTemplate(fallback.id)
+      message.warning(INVALID_TEMPLATE_FALLBACK_TOAST)
+    } else {
+      // 没有任何有效模板：清空选择，交由 Step1 空状态引导用户去模板编辑器创建
+      setSelectedTemplate("")
+      message.warning("当前没有可用模板，请先在「模板编辑器」中创建并配置片段")
+    }
+    return true
+  }, [])
+
+  return {
+    selectedTemplate,
+    setSelectedTemplate: handleSelectTemplate,
+    userTemplates,
+    handleInvalidTemplate,
+  }
 }

apps/web/src/pages/generate/hooks/useGenerateFormState/useTitleCoverSync.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react"
+import { useEffect, useRef } from "react"
 import type { TitleSettings } from "../../types"
 import type { CoverConfig } from "../../types/cover"
 import type { EditingTemplate } from "@/api/editing-planner"
@@ -11,7 +11,11 @@ interface UseTitleCoverSyncOptions {
 }
 
 /**
- * 当选中模板变化时，自动同步标题和封面配置
+ * 当选中模板变化时，自动同步标题和封面配置。
+ *
+ * #1789 修复：userTemplates 用 ref 持有最新值，不放入依赖数组。
+ * 否则每次渲染 .filter() 创建的新数组引用都会触发 effect，
+ * 从模板 title_config 覆盖用户手动修改（如字号滑块拖动），导致回弹。
  */
 export function useTitleCoverSync({
   selectedTemplate,
@@ -19,8 +23,12 @@ export function useTitleCoverSync({
   setTitleSettings,
   setCoverSettings,
 }: UseTitleCoverSyncOptions) {
+  // 用 ref 持有最新 userTemplates，避免数组引用变化导致 effect 反复触发
+  const templatesRef = useRef(userTemplates)
+  templatesRef.current = userTemplates
+
   useEffect(() => {
-    const tpl = userTemplates.find((t) => t.id === selectedTemplate)
+    const tpl = templatesRef.current.find((t) => t.id === selectedTemplate)
     if (tpl?.title_config) {
       setTitleSettings((prev: TitleSettings) => ({
         ...prev,
@@ -43,5 +51,7 @@ export function useTitleCoverSync({
         thumbnail_url: tpl.cover_config!.thumbnail_url || prev.thumbnail_url,
       }))
     }
-  }, [selectedTemplate, userTemplates, setTitleSettings, setCoverSettings])
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [selectedTemplate, setTitleSettings, setCoverSettings])
+  // ↑ 移除 userTemplates，只在 selectedTemplate 真正变化时触发
 }

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

@@ -10,6 +10,7 @@ import { updateEditPlanClips, createClipsFromAssets, getEditPlanClips } from "@/
 import { useMaterialLibrary } from "./step2-materials/useMaterialLibrary"
 import { useSmartMatch } from "./step2-materials/useSmartMatch"
 import { useDraftAutoSave } from "./useDraftAutoSave"
+import { isInvalidTemplateError } from "./useGenerateFormState/templateFallback"
 
 interface UseStep2MaterialsProps {
   materialMode: "manual" | "auto"
@@ -24,6 +25,8 @@ interface UseStep2MaterialsProps {
   templateSegments?: TemplateSegment[]
   /** 服务端 clips 创建成功后的回调，用于通知预览播放器 */
   onServerClipsChange?: (clips: EditPlanClip[]) => void
+  /** 当前模板创建片段返回 404/400/422（模板失效）时的自动回退回调（#1777） */
+  onTemplateInvalid?: () => boolean
 }
 
 export function useStep2Materials({
@@ -36,6 +39,7 @@ export function useStep2Materials({
   selectedTemplate,
   templateSegments,
   onServerClipsChange,
+  onTemplateInvalid,
 }: UseStep2MaterialsProps) {
   const {
     libraries,
@@ -102,6 +106,8 @@ export function useStep2Materials({
   selectedTemplateRef.current = selectedTemplate
   const onServerClipsChangeRef = useRef(onServerClipsChange)
   onServerClipsChangeRef.current = onServerClipsChange
+  const onTemplateInvalidRef = useRef(onTemplateInvalid)
+  onTemplateInvalidRef.current = onTemplateInvalid
 
   useEffect(() => {
     const tid = selectedTemplateRef.current
@@ -123,11 +129,12 @@ export function useStep2Materials({
       const requiredClipsCount = segs.length > 0 ? segs.length : undefined
 
       try {
-        // 1. 清空旧片段
-        await updateEditPlanClips(tid, [], controller.signal)
+        // 1. 清空旧片段（静默全局 toast：模板失效时由下方回退统一提示）
+        await updateEditPlanClips(tid, [], controller.signal, true)
         // 2. 调用后端 from-assets 接口创建片段（异步秒级返回，60s 超时仅为兜底）
         await createClipsFromAssets(tid, ids, "main", requiredClipsCount, {
           signal: controller.signal,
+          silentErrorToast: true,
         })
         // 3. 获取服务端生成的 clips（含 start_time/duration），供预览播放器使用
         const clipList = await getEditPlanClips(tid, { limit: 500 })
@@ -146,6 +153,14 @@ export function useStep2Materials({
           message.error("智能选片失败，请重试")
           return
         }
+        // 模板失效（404 模板不存在 / 400/422 无片段配置）：
+        // 清空失效选择并自动切到第一个有效模板 + toast，避免页面卡死无提示（#1777）
+        if (isInvalidTemplateError(err)) {
+          console.warn("[useStep2Materials] 当前模板已失效，触发自动回退:", err)
+          onServerClipsChangeRef.current?.([])
+          onTemplateInvalidRef.current?.()
+          return
+        }
         console.warn("[useStep2Materials] 写入 clips 失败:", err)
       }
     }, 800)

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

@@ -5,7 +5,7 @@
 
 .mt-page {
   padding: var(--space-xl);
-  max-width: 1400px;
+  max-width: 1680px;
   margin: 0 auto;
 }
 

apps/web/src/pages/scripts/ScriptLibrary.tsx

@@ -0,0 +1,273 @@
+/**
+ * 文案库页面 — Issue #1811
+ * 风格对齐标题库（同类资源管理页面统一风格），单列卡片列表
+ * 功能：列表 / 新建 / 编辑 / 删除 / 按标题搜索 / 空状态
+ * 对接后端 /api/v1/scripts CRUD
+ */
+import React, { useEffect, useMemo, useState } from "react"
+import { Modal, message, Empty, Button, Input, Popconfirm } from "antd"
+import { PlusOutlined, EditOutlined, DeleteOutlined, SearchOutlined } from "@ant-design/icons"
+import {
+  getScripts,
+  createScript,
+  updateScript,
+  deleteScript,
+  type ScriptItem,
+} from "@/api/scripts"
+import "./scripts.css"
+
+const { TextArea } = Input
+
+const ScriptLibrary: React.FC = () => {
+  const [scripts, setScripts] = useState<ScriptItem[]>([])
+  const [loading, setLoading] = useState(false)
+  const [searchText, setSearchText] = useState("")
+
+  // 弹窗状态
+  const [createOpen, setCreateOpen] = useState(false)
+  const [editing, setEditing] = useState<ScriptItem | null>(null)
+  const [formTitle, setFormTitle] = useState("")
+  const [formContent, setFormContent] = useState("")
+  const [submitting, setSubmitting] = useState(false)
+
+  const load = async () => {
+    setLoading(true)
+    try {
+      const items = await getScripts()
+      setScripts(items)
+    } catch (err) {
+      message.error(err instanceof Error ? err.message : "加载文案列表失败")
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    load()
+  }, [])
+
+  const filtered = useMemo(() => {
+    const kw = searchText.trim().toLowerCase()
+    if (!kw) return scripts
+    return scripts.filter((s) => s.title.toLowerCase().includes(kw))
+  }, [scripts, searchText])
+
+  const openCreate = () => {
+    setFormTitle("")
+    setFormContent("")
+    setCreateOpen(true)
+  }
+
+  const openEdit = (item: ScriptItem) => {
+    setEditing(item)
+    setFormTitle(item.title)
+    setFormContent(item.content)
+  }
+
+  const handleCloseCreate = () => {
+    setCreateOpen(false)
+    setFormTitle("")
+    setFormContent("")
+  }
+
+  const handleCloseEdit = () => {
+    setEditing(null)
+    setFormTitle("")
+    setFormContent("")
+  }
+
+  const handleCreate = async () => {
+    const title = formTitle.trim()
+    const content = formContent.trim()
+    if (!title || !content) {
+      message.warning("请填写标题和正文")
+      return
+    }
+    setSubmitting(true)
+    try {
+      await createScript({ title, content })
+      message.success("文案已创建")
+      handleCloseCreate()
+      await load()
+    } catch (err) {
+      message.error(err instanceof Error ? err.message : "创建文案失败")
+    } finally {
+      setSubmitting(false)
+    }
+  }
+
+  const handleUpdate = async () => {
+    if (!editing) return
+    const title = formTitle.trim()
+    const content = formContent.trim()
+    if (!title || !content) {
+      message.warning("请填写标题和正文")
+      return
+    }
+    setSubmitting(true)
+    try {
+      await updateScript(editing.id, { title, content })
+      message.success("文案已更新")
+      handleCloseEdit()
+      await load()
+    } catch (err) {
+      message.error(err instanceof Error ? err.message : "更新文案失败")
+    } finally {
+      setSubmitting(false)
+    }
+  }
+
+  const handleDelete = async (id: string) => {
+    try {
+      await deleteScript(id)
+      message.success("文案已删除")
+      await load()
+    } catch (err) {
+      message.error(err instanceof Error ? err.message : "删除文案失败")
+    }
+  }
+
+  const preview = (content: string) => {
+    const text = content.replace(/\s+/g, " ").trim()
+    return text.length > 120 ? `${text.slice(0, 120)}…` : text || "（空）"
+  }
+
+  const formatTime = (iso: string) => {
+    const d = new Date(iso)
+    if (Number.isNaN(d.getTime())) return iso
+    const pad = (n: number) => String(n).padStart(2, "0")
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(
+      d.getHours(),
+    )}:${pad(d.getMinutes())}`
+  }
+
+  return (
+    <div className="xx-scripts-page">
+      <div className="xx-scripts-layout">
+        {/* 顶部操作栏 */}
+        <div className="xx-scripts-filters">
+          <div className="xx-scripts-filters-left">
+            <Input
+              prefix={<SearchOutlined />}
+              placeholder="按标题搜索"
+              value={searchText}
+              onChange={(e) => setSearchText(e.target.value)}
+              allowClear
+              style={{ width: 260 }}
+            />
+          </div>
+          <div className="xx-scripts-filters-right">
+            <Button type="primary" icon={<PlusOutlined />} onClick={openCreate}>
+              新建文案
+            </Button>
+          </div>
+        </div>
+
+        {/* 列表 / 空状态 */}
+        {loading ? (
+          <div className="xx-scripts-loading">加载中…</div>
+        ) : filtered.length === 0 ? (
+          <Empty
+            description={searchText ? "没有匹配的文案" : "暂无文案，点击右上角「新建文案」开始创作"}
+          />
+        ) : (
+          <div className="xx-scripts-list">
+            {filtered.map((s) => (
+              <div key={s.id} className="xx-script-card">
+                <div className="xx-script-card-header">
+                  <div className="xx-script-title">{s.title}</div>
+                  <div className="xx-script-actions">
+                    <Button
+                      size="small"
+                      type="text"
+                      icon={<EditOutlined />}
+                      onClick={() => openEdit(s)}
+                    >
+                      编辑
+                    </Button>
+                    <Popconfirm
+                      title="确认删除此文案？"
+                      description="删除后不可恢复"
+                      okText="删除"
+                      cancelText="取消"
+                      okButtonProps={{ danger: true }}
+                      onConfirm={() => handleDelete(s.id)}
+                    >
+                      <Button size="small" type="text" danger icon={<DeleteOutlined />}>
+                        删除
+                      </Button>
+                    </Popconfirm>
+                  </div>
+                </div>
+                <div className="xx-script-preview">{preview(s.content)}</div>
+                <div className="xx-script-meta">
+                  <span>{s.char_count ?? s.content.length} 字</span>
+                  <span>·</span>
+                  <span>{formatTime(s.created_at)}</span>
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* 新建弹窗 */}
+      <Modal
+        title="新建文案"
+        open={createOpen}
+        onCancel={handleCloseCreate}
+        onOk={handleCreate}
+        confirmLoading={submitting}
+        destroyOnClose
+        okText="创建"
+        cancelText="取消"
+      >
+        <div className="xx-script-form">
+          <Input
+            placeholder="标题"
+            value={formTitle}
+            onChange={(e) => setFormTitle(e.target.value)}
+            maxLength={200}
+          />
+          <TextArea
+            placeholder="正文"
+            value={formContent}
+            onChange={(e) => setFormContent(e.target.value)}
+            rows={8}
+            maxLength={5000}
+          />
+        </div>
+      </Modal>
+
+      {/* 编辑弹窗 */}
+      <Modal
+        title="编辑文案"
+        open={!!editing}
+        onCancel={handleCloseEdit}
+        onOk={handleUpdate}
+        confirmLoading={submitting}
+        destroyOnClose
+        okText="保存"
+        cancelText="取消"
+      >
+        <div className="xx-script-form">
+          <Input
+            placeholder="标题"
+            value={formTitle}
+            onChange={(e) => setFormTitle(e.target.value)}
+            maxLength={200}
+          />
+          <TextArea
+            placeholder="正文"
+            value={formContent}
+            onChange={(e) => setFormContent(e.target.value)}
+            rows={8}
+            maxLength={5000}
+          />
+        </div>
+      </Modal>
+    </div>
+  )
+}
+
+export default ScriptLibrary

apps/web/src/pages/scripts/scripts.css

@@ -0,0 +1,137 @@
+/**
+ * 文案库页面 - V21 设计系统样式
+ * 单列卡片列表，风格对齐标题库（xx-titles-page）
+ */
+@import "../../styles/global.css";
+
+/* ============================================================
+   页面容器
+   ============================================================ */
+.xx-scripts-page {
+  min-height: 100%;
+  padding: var(--space-xl);
+}
+
+.xx-scripts-layout {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-lg);
+  max-width: 960px;
+  margin: 0 auto;
+}
+
+/* ============================================================
+   顶部筛选栏
+   ============================================================ */
+.xx-scripts-filters {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-md);
+  flex-wrap: wrap;
+}
+
+.xx-scripts-filters-left {
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm);
+}
+
+.xx-scripts-filters-right {
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm);
+}
+
+/* ============================================================
+   列表
+   ============================================================ */
+.xx-scripts-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-sm);
+}
+
+.xx-scripts-loading {
+  text-align: center;
+  color: var(--text-secondary);
+  padding: var(--space-xl);
+  font-size: var(--font-size-sm);
+}
+
+/* ============================================================
+   文案卡片（对齐标题卡片风格，单列）
+   ============================================================ */
+.xx-script-card {
+  border: 1px solid var(--border-color);
+  background: var(--bg-primary);
+  border-radius: var(--radius-md);
+  padding: var(--space-md);
+  transition: var(--transition-all);
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.xx-script-card:hover {
+  border-color: var(--primary-color);
+  background: var(--bg-secondary);
+  box-shadow: var(--shadow-sm);
+}
+
+.xx-script-card-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--space-md);
+}
+
+.xx-script-title {
+  font-size: var(--font-size-base);
+  font-weight: var(--font-weight-semibold);
+  color: var(--text-primary);
+  line-height: 1.5;
+  word-break: break-word;
+  flex: 1;
+}
+
+.xx-script-actions {
+  display: flex;
+  align-items: center;
+  gap: var(--space-xxs);
+  flex-shrink: 0;
+  opacity: 0;
+  transition: var(--transition-opacity, opacity 0.2s);
+}
+
+.xx-script-card:hover .xx-script-actions {
+  opacity: 1;
+}
+
+.xx-script-preview {
+  font-size: var(--font-size-sm);
+  color: var(--text-secondary);
+  line-height: 1.6;
+  word-break: break-word;
+}
+
+.xx-script-meta {
+  display: flex;
+  align-items: center;
+  gap: var(--space-xs);
+  font-size: var(--font-size-xs, 12px);
+  color: var(--text-tertiary);
+}
+
+/* ============================================================
+   弹窗表单
+   ============================================================ */
+.xx-script-form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-md);
+}
+
+.xx-script-form textarea.ant-input {
+  resize: vertical;
+}

apps/web/src/pages/tasks/tasks.css

@@ -2,7 +2,7 @@
 
 .task-center {
   padding: var(--space-lg);
-  max-width: 1400px;
+  max-width: 1680px;
   margin: 0 auto;
 }
 

apps/web/src/pages/voice-materials/hooks/useVoiceMaterials/actions/useVoiceUpload.ts

@@ -41,7 +41,7 @@ export function useVoiceUpload({ voiceLibrary, createLibMutation }: UseVoiceUplo
           }
           const libs = await queryClient.fetchQuery({
             queryKey: ["asset-libraries"],
-            queryFn: getAssetLibraries,
+            queryFn: () => getAssetLibraries(),
           })
           lib = libs.find((l: AssetLibraryItem) => l.kind === "voice")
           if (!lib) throw new Error("无法创建配音库")

apps/web/src/pages/voice-materials/hooks/useVoiceMaterials/useVoiceMaterialData.ts

@@ -24,7 +24,7 @@ export function useVoiceMaterialData({ keyword, gender, tagIds }: UseVoiceMateri
   // ── 获取 voice 类型素材库 ─────────────────────────────────
   const { data: libraries = [] } = useQuery({
     queryKey: ["asset-libraries"],
-    queryFn: getAssetLibraries,
+    queryFn: () => getAssetLibraries(),
     staleTime: 60_000,
   })
 

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

@@ -26,7 +26,7 @@ export function useVoiceUpload({ showToast }: UseVoiceUploadProps) {
         /* 获取或创建默认配音库 */
         const libs = await queryClient.fetchQuery({
           queryKey: ["asset-libraries"],
-          queryFn: getAssetLibraries,
+          queryFn: () => getAssetLibraries(),
         })
         const lib = libs.find((l) => l.kind === "voice")
         if (!lib) throw new Error("配音库不存在，请先在配音库页面创建")

apps/web/src/router/appRoutes.tsx

@@ -24,6 +24,10 @@ const appChildren: RouteObject[] = [
     path: "titles",
     lazy: lazyRoute(() => import("@/pages/titles/TitleLibrary")),
   },
+  {
+    path: "scripts",
+    lazy: lazyRoute(() => import("@/pages/scripts/ScriptLibrary")),
+  },
   {
     path: "voices",
     lazy: lazyRoute(() => import("@/pages/voices/VoiceLibrary")),
@@ -56,6 +60,10 @@ const appChildren: RouteObject[] = [
     path: "editing-planner",
     lazy: lazyRoute(() => import("@/pages/editing-planner/EditingPlanner")),
   },
+  {
+    path: "ai-avatar",
+    lazy: lazyRoute(() => import("@/pages/ai-avatar/AiAvatarPage")),
+  },
   {
     path: "my-templates",
     lazy: lazyRoute(() => import("@/pages/my-templates/MyTemplates")),

apps/web/src/test/pages/generate/templateFallback.test.ts

@@ -0,0 +1,140 @@
+/**
+ * 失效模板判定/回退纯函数单测（#1777）
+ */
+import { describe, it, expect } from "vitest"
+import type { EditingTemplate } from "@/api/editing-planner"
+import {
+  getHttpStatus,
+  isInvalidTemplateError,
+  isValidTemplate,
+  findFirstValidTemplate,
+} from "@/pages/generate/hooks/useGenerateFormState/templateFallback"
+
+function makeTemplate(partial: Partial<EditingTemplate> & { id: string }): EditingTemplate {
+  return {
+    name: partial.id,
+    mode: "pip",
+    category: "默认",
+    tags: [],
+    title_config: {
+      ai_auto_select: false,
+      content: "",
+      font_preset: "",
+      font_color: "",
+      font_size: 28,
+      position: "top",
+    },
+    subtitle_config: {
+      enabled: true,
+      position: "bottom",
+      font: "",
+      color: "",
+      size: 20,
+      animation: "",
+    },
+    bgm_config: { enabled: false, music_id: "" },
+    segments: [{ segment_order: 0, material_type: null }],
+    is_active: true,
+    created_at: "",
+    updated_at: "",
+    ...partial,
+  } as EditingTemplate
+}
+
+function axiosError(status: number, data?: unknown) {
+  return { isAxiosError: true, response: { status, data } }
+}
+
+describe("getHttpStatus", () => {
+  it("提取 axios 错误的 HTTP 状态码", () => {
+    expect(getHttpStatus(axiosError(404))).toBe(404)
+    expect(getHttpStatus(axiosError(400))).toBe(400)
+  })
+  it("非 axios/无响应错误返回 null", () => {
+    expect(getHttpStatus(new Error("network"))).toBeNull()
+    expect(getHttpStatus(null)).toBeNull()
+    expect(getHttpStatus(undefined)).toBeNull()
+    expect(getHttpStatus({ isAxiosError: true })).toBeNull()
+  })
+})
+
+describe("isInvalidTemplateError", () => {
+  it("404 始终判定为模板失效（模板不存在）", () => {
+    expect(isInvalidTemplateError(axiosError(404))).toBe(true)
+    expect(isInvalidTemplateError(axiosError(404, { detail: "Not Found" }))).toBe(true)
+  })
+
+  it("400 且后端文案提到「片段配置」判定为模板无片段配置", () => {
+    expect(
+      isInvalidTemplateError(axiosError(400, { detail: "模板没有片段配置，无法创建片段" })),
+    ).toBe(true)
+  })
+
+  it("400 但文案与片段配置无关 → 不误判", () => {
+    expect(isInvalidTemplateError(axiosError(400, { detail: "素材参数错误" }))).toBe(false)
+  })
+
+  it("422 命中片段/模板字段判定为失效", () => {
+    expect(
+      isInvalidTemplateError(
+        axiosError(422, { detail: [{ loc: ["body", "segments"], msg: "field required" }] }),
+      ),
+    ).toBe(true)
+  })
+
+  it("其他状态码（401/403/500/超时/网络）不判定为模板失效", () => {
+    expect(isInvalidTemplateError(axiosError(401))).toBe(false)
+    expect(isInvalidTemplateError(axiosError(403))).toBe(false)
+    expect(isInvalidTemplateError(axiosError(500))).toBe(false)
+    expect(isInvalidTemplateError({ code: "ECONNABORTED", message: "timeout of 60000ms" })).toBe(
+      false,
+    )
+    expect(isInvalidTemplateError(new Error("Network Error"))).toBe(false)
+  })
+})
+
+describe("isValidTemplate", () => {
+  it("有片段且未被标记 inactive → 有效", () => {
+    expect(isValidTemplate(makeTemplate({ id: "t1" }))).toBe(true)
+  })
+  it("segments 为空 → 无效（无片段配置）", () => {
+    expect(isValidTemplate(makeTemplate({ id: "t2", segments: [] }))).toBe(false)
+  })
+  it("is_active=false → 无效（已停用/删除）", () => {
+    expect(isValidTemplate(makeTemplate({ id: "t3", is_active: false }))).toBe(false)
+  })
+  it("is_active 字段缺失时视为有效（兼容旧后端）", () => {
+    const t = makeTemplate({ id: "t4" })
+    delete (t as Partial<EditingTemplate>).is_active
+    expect(isValidTemplate(t)).toBe(true)
+  })
+  it("null/undefined → 无效", () => {
+    expect(isValidTemplate(null)).toBe(false)
+    expect(isValidTemplate(undefined)).toBe(false)
+  })
+})
+
+describe("findFirstValidTemplate", () => {
+  it("跳过无效模板，返回第一个有效模板", () => {
+    const list = [
+      makeTemplate({ id: "empty", segments: [] }),
+      makeTemplate({ id: "inactive", is_active: false }),
+      makeTemplate({ id: "valid1" }),
+      makeTemplate({ id: "valid2" }),
+    ]
+    expect(findFirstValidTemplate(list)?.id).toBe("valid1")
+  })
+  it("全部无效 → null（用于空状态引导）", () => {
+    expect(
+      findFirstValidTemplate([
+        makeTemplate({ id: "a", segments: [] }),
+        makeTemplate({ id: "b", is_active: false }),
+      ]),
+    ).toBeNull()
+  })
+  it("空数组/null → null", () => {
+    expect(findFirstValidTemplate([])).toBeNull()
+    expect(findFirstValidTemplate(null)).toBeNull()
+    expect(findFirstValidTemplate(undefined)).toBeNull()
+  })
+})

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

@@ -0,0 +1,74 @@
+/**
+ * useMaterialLibrary Hook 单测（#1777）
+ * - Step2 视频库选择器只拉取 kind=video 的素材库，配音库(voice)/图片库(image) 不混入
+ * - 自动选中第一个视频库
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest"
+import { renderHook, waitFor } from "@testing-library/react"
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
+import type { ReactNode } from "react"
+import type { AssetItem, AssetLibraryItem } from "@/api/assets"
+
+vi.mock("@/api/assets", () => ({
+  getAssetLibraries: vi.fn(),
+  getAssets: vi.fn(),
+  isAssetUsable: vi.fn(() => true),
+}))
+
+import { getAssetLibraries, getAssets } from "@/api/assets"
+import { useMaterialLibrary } from "@/pages/generate/hooks/step2-materials/useMaterialLibrary"
+
+const mockGetLibraries = vi.mocked(getAssetLibraries)
+const mockGetAssets = vi.mocked(getAssets)
+
+function lib(id: string, kind: AssetLibraryItem["kind"], name = id): AssetLibraryItem {
+  return { id, name, kind }
+}
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false, gcTime: 0 } },
+  })
+  return ({ children }: { children: ReactNode }) =>
+    (<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>) as ReactNode
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mockGetAssets.mockResolvedValue({ items: [] as AssetItem[], total: 0 })
+})
+
+describe("useMaterialLibrary (#1777 kind=video 过滤)", () => {
+  it("按 kind=video 拉取素材库（后端参数过滤）", async () => {
+    mockGetLibraries.mockResolvedValueOnce([lib("v1", "video")])
+    renderHook(() => useMaterialLibrary(), { wrapper: createWrapper() })
+
+    await waitFor(() => expect(mockGetLibraries).toHaveBeenCalledTimes(1))
+    expect(mockGetLibraries).toHaveBeenCalledWith("video")
+  })
+
+  it("下拉库列表只包含视频库（自动选中第一个视频库）", async () => {
+    mockGetLibraries.mockResolvedValueOnce([
+      lib("voice-1", "voice"),
+      lib("img-1", "image"),
+      lib("video-1", "video"),
+      lib("video-2", "video"),
+    ])
+    const { result } = renderHook(() => useMaterialLibrary(), { wrapper: createWrapper() })
+
+    await waitFor(() => expect(result.current.libraries).toHaveLength(2))
+    expect(result.current.libraries.map((l) => l.id)).toEqual(["video-1", "video-2"])
+    expect(result.current.libraries.every((l) => l.kind === "video")).toBe(true)
+    // 自动选中第一个视频库
+    expect(result.current.selectedLibraryId).toBe("video-1")
+  })
+
+  it("没有视频库时库列表为空且不自动选中（UI 展示空状态）", async () => {
+    mockGetLibraries.mockResolvedValueOnce([lib("voice-1", "voice"), lib("img-1", "image")])
+    const { result } = renderHook(() => useMaterialLibrary(), { wrapper: createWrapper() })
+
+    await waitFor(() => expect(mockGetLibraries).toHaveBeenCalled())
+    expect(result.current.libraries).toEqual([])
+    expect(result.current.selectedLibraryId).toBe("")
+  })
+})

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

@@ -0,0 +1,174 @@
+/**
+ * useTemplateSelection Hook 单测（#1777）
+ * - 自动选择跳过无片段/inactive 模板，只选第一个有效模板
+ * - 传 validOnly=true 给后端
+ * - 用户手动选择优先，自动逻辑不覆盖
+ * - handleInvalidTemplate：失效时自动切到第一个有效模板 + toast；无有效模板时清空
+ * - selectedTemplate 仅内存态，不写入 localStorage/sessionStorage
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"
+import { renderHook, waitFor, act } from "@testing-library/react"
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
+import type { ReactNode } from "react"
+
+// antd message mock（拦截 toast）——vi.hoisted 保证 mock 工厂可引用
+const { messageMock } = vi.hoisted(() => ({
+  messageMock: {
+    warning: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+    info: vi.fn(),
+    loading: vi.fn(() => vi.fn()),
+  },
+}))
+vi.mock("antd", () => ({ message: messageMock }))
+
+vi.mock("@/api/editing-planner", () => ({
+  getEditingTemplates: vi.fn(),
+}))
+
+import { getEditingTemplates } from "@/api/editing-planner"
+import type { EditingTemplate } from "@/api/editing-planner"
+import { useTemplateSelection } from "@/pages/generate/hooks/useGenerateFormState/useTemplateSelection"
+
+const mockGetTemplates = vi.mocked(getEditingTemplates)
+
+function tpl(id: string, partial: Partial<EditingTemplate> = {}): EditingTemplate {
+  return {
+    id,
+    name: id,
+    mode: "pip",
+    category: "默认",
+    tags: [],
+    title_config: {
+      ai_auto_select: false,
+      content: "",
+      font_preset: "",
+      font_color: "",
+      font_size: 28,
+      position: "top",
+    },
+    subtitle_config: {
+      enabled: true,
+      position: "bottom",
+      font: "",
+      color: "",
+      size: 20,
+      animation: "",
+    },
+    bgm_config: { enabled: false, music_id: "" },
+    segments: [{ segment_order: 0, material_type: null }],
+    is_active: true,
+    created_at: "",
+    updated_at: "",
+    ...partial,
+  } as EditingTemplate
+}
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false, gcTime: 0 } },
+  })
+  return ({ children }: { children: ReactNode }) =>
+    (<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>) as ReactNode
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  localStorage.clear()
+  sessionStorage.clear()
+})
+
+afterEach(() => {
+  localStorage.clear()
+  sessionStorage.clear()
+})
+
+describe("useTemplateSelection (#1777)", () => {
+  it("请求模板时传 validOnly=true，并自动选中第一个有片段的有效模板", async () => {
+    mockGetTemplates.mockResolvedValueOnce([
+      tpl("empty", { segments: [] }),
+      tpl("inactive", { is_active: false }),
+      tpl("valid-a"),
+      tpl("valid-b"),
+    ])
+    const { result } = renderHook(() => useTemplateSelection(), { wrapper: createWrapper() })
+
+    await waitFor(() => expect(result.current.selectedTemplate).toBe("valid-a"))
+    expect(mockGetTemplates).toHaveBeenCalledWith({ validOnly: true })
+    // 暴露给 UI 的 userTemplates 已过滤掉无效模板
+    expect(result.current.userTemplates.map((t) => t.id)).toEqual(["valid-a", "valid-b"])
+  })
+
+  it("列表全部无效时 selectedTemplate 为空（交空状态引导），不选中失效模板", async () => {
+    mockGetTemplates.mockResolvedValueOnce([
+      tpl("empty", { segments: [] }),
+      tpl("inactive", { is_active: false }),
+    ])
+    const { result } = renderHook(() => useTemplateSelection(), { wrapper: createWrapper() })
+    await waitFor(() => expect(mockGetTemplates).toHaveBeenCalled())
+    // 给 effect 一个 tick
+    await waitFor(() => expect(result.current.selectedTemplate).toBe(""))
+    expect(result.current.userTemplates).toHaveLength(0)
+  })
+
+  it("用户手动选择优先：自动逻辑不会覆盖手动选择", async () => {
+    mockGetTemplates.mockResolvedValueOnce([tpl("a"), tpl("b")])
+    const { result } = renderHook(() => useTemplateSelection(), { wrapper: createWrapper() })
+    await waitFor(() => expect(result.current.selectedTemplate).toBe("a"))
+
+    act(() => result.current.setSelectedTemplate("b"))
+    expect(result.current.selectedTemplate).toBe("b")
+
+    // 重新渲染 / refetch 后仍保持用户的手动选择
+    await waitFor(() => expect(result.current.selectedTemplate).toBe("b"))
+  })
+
+  it("handleInvalidTemplate：当前模板失效时自动切到第一个有效模板并 toast", async () => {
+    mockGetTemplates.mockResolvedValueOnce([tpl("bad", { segments: [] }), tpl("good")])
+    const { result } = renderHook(() => useTemplateSelection(), { wrapper: createWrapper() })
+    // 自动选中有效模板 good（bad 无片段不会被自动选中）
+    await waitFor(() => expect(result.current.selectedTemplate).toBe("good"))
+    messageMock.warning.mockClear()
+
+    // 模拟运行时用户停留在一个已失效的模板 id（外部/草稿态），触发回退
+    act(() => result.current.setSelectedTemplate("stale-id"))
+    expect(result.current.selectedTemplate).toBe("stale-id")
+
+    act(() => {
+      const handled = result.current.handleInvalidTemplate()
+      expect(handled).toBe(true)
+    })
+    await waitFor(() => expect(result.current.selectedTemplate).toBe("good"))
+    expect(messageMock.warning).toHaveBeenCalledWith("原模板已失效，已自动切换")
+  })
+
+  it("handleInvalidTemplate：无有效模板时清空选择并提示去创建", async () => {
+    mockGetTemplates.mockResolvedValueOnce([tpl("bad", { segments: [] })])
+    const { result } = renderHook(() => useTemplateSelection(), { wrapper: createWrapper() })
+    await waitFor(() => expect(result.current.userTemplates).toHaveLength(0))
+
+    act(() => result.current.setSelectedTemplate("stale-id"))
+    act(() => {
+      result.current.handleInvalidTemplate()
+    })
+    await waitFor(() => expect(result.current.selectedTemplate).toBe(""))
+    expect(messageMock.warning).toHaveBeenCalledWith(expect.stringContaining("没有可用模板"))
+  })
+
+  it("失效模板 ID 不写入任何持久化存储", async () => {
+    mockGetTemplates.mockResolvedValueOnce([tpl("good")])
+    const { result } = renderHook(() => useTemplateSelection(), { wrapper: createWrapper() })
+    await waitFor(() => expect(result.current.selectedTemplate).toBe("good"))
+
+    act(() => result.current.setSelectedTemplate("stale-invalid-id"))
+    act(() => result.current.handleInvalidTemplate())
+
+    const ls = JSON.stringify(localStorage)
+    const ss = JSON.stringify(sessionStorage)
+    expect(ls).not.toContain("stale-invalid-id")
+    expect(ss).not.toContain("stale-invalid-id")
+    // URL 也不含
+    expect(window.location.href).not.toContain("stale-invalid-id")
+  })
+})

apps/worker/video_processing/bgm_mixer.py

@@ -39,6 +39,8 @@ class BGMConfig:
     sidechain_attack: float = 0.02  # 攻击时间
     sidechain_release: float = 0.5  # 释放时间
     sidechain_threshold: float = -25.0  # 触发阈值（dB）
+    audio_offset: float = 0.0  # BGM 段落起始偏移（秒），#1767 策略二
+    volume_adjust_db: float = 0.0  # 音量微调 dB（-3~+3），#1767 策略三
 
     @classmethod
     def from_config_dict(cls, bgm_path: str, config: dict) -> "BGMConfig":
@@ -54,6 +56,8 @@ class BGMConfig:
             sidechain_attack=float(config.get("sidechain_attack", 0.02)),
             sidechain_release=float(config.get("sidechain_release", 0.5)),
             sidechain_threshold=float(config.get("sidechain_threshold", -25.0)),
+            audio_offset=float(config.get("audio_offset", 0.0)),
+            volume_adjust_db=float(config.get("volume_adjust_db", 0.0)),
         )
 
 
@@ -84,14 +88,18 @@ def prepare_bgm_track(
         target_duration = 5.0  # 兜底
 
     bgm_dur = probe_duration(bgm.bgm_path)
-    needs_loop = bgm.loop_enabled and bgm_dur > 0 and bgm_dur < target_duration * 0.9
+    # #1767：seek 后有效时长 = 总时长 - 偏移
+    effective_dur = (
+        max(1.0, bgm_dur - bgm.audio_offset) if bgm.audio_offset > 0 and bgm_dur > bgm.audio_offset else bgm_dur
+    )
+    needs_loop = bgm.loop_enabled and effective_dur > 0 and effective_dur < target_duration * 0.9
 
     # 构建滤镜链
     filter_parts: list[str] = []
 
     if needs_loop:
-        # 计算需要循环多少次才能铺满
-        loop_count = max(1, int(target_duration / bgm_dur) + 2)
+        # 计算需要循环多少次才能铺满（基于 seek 后有效时长）
+        loop_count = max(1, int(target_duration / effective_dur) + 2)
         # aloop 滤镜：循环指定次数
         filter_parts.append(f"aloop=loop={loop_count}:size=0")
 
@@ -113,11 +121,30 @@ def prepare_bgm_track(
     filter_parts.append(f"atrim=0:{target_duration:.3f}")
     filter_parts.append("asetpts=N/SR/TB")  # 重置时间戳
 
-    filter_str = ",".join(filter_parts)
+    # #1767：BGM 段落差异化 — 使用 -ss 从偏移位置开始（seek 效率高，不读跳过部分）
+    seek_args: list[str] = []
+    if bgm.audio_offset > 0 and bgm_dur > bgm.audio_offset:
+        seek_args = ["-ss", f"{bgm.audio_offset:.3f}"]
+        logger.info("[bgm] #1767 audio_offset=%.1fs（段落差异化）", bgm.audio_offset)
+
+    # #1767：音量微调 — dB 转线性系数（10^(dB/20)）
+    db_adjust_filter = ""
+    if abs(bgm.volume_adjust_db) > 0.01:
+        linear_factor = 10.0 ** (bgm.volume_adjust_db / 20.0)
+        db_adjust_filter = f",volume={linear_factor:.4f}"
+        logger.info("[bgm] #1767 volume_adjust=%.0fdB → linear=%.4f", bgm.volume_adjust_db, linear_factor)
+
+    # #1767：追加 dB 微调到滤镜链末尾
+    if db_adjust_filter:
+        filter_str_base = ",".join(filter_parts)
+        filter_str = filter_str_base + db_adjust_filter
+    else:
+        filter_str = ",".join(filter_parts)
 
     command = [
         FFMPEG_BIN,
         "-y",
+        *seek_args,
         "-i",
         bgm.bgm_path,
         "-filter:a",

apps/worker/video_processing/ffmpeg_utils.py

@@ -59,13 +59,18 @@ def build_xfade_filter_chain(
     transitions: list[str],
     *,
     transition_duration: float = DEFAULT_TRANSITION_DURATION,
+    transition_durations: list[float] | None = None,
+    jitters: list[float] | None = None,
     output_label: str = "outv",
 ) -> tuple[str, float]:
+    """构建 xfade 转场滤镜链（re-export，#1766 增加逐转场时长与 jitter 支持）."""
     return _build_xfade_filter_chain_base(
         clip_durations,
         clip_video_labels,
         transitions,
         transition_duration=transition_duration,
+        transition_durations=transition_durations,
+        jitters=jitters,
         output_label=output_label,
     )
 

apps/worker/video_processing/transition_engine.py

@@ -105,17 +105,24 @@ class TransitionEngine:
         transitions: list[str],
         *,
         transition_duration: float | None = None,
+        transition_durations: list[float] | None = None,
+        jitters: list[float] | None = None,
         output_label: str = "outv",
     ) -> tuple[str, float]:
         """构建 xfade 转场滤镜链.
 
         对每步转场应用验证和降级，然后调用底层 ffmpeg_utils 构建。
 
+        #1766 增强：支持逐转场独立时长（transition_durations）和位置微调（jitters）。
+
         Args:
             clip_durations: 每个片段的时长
             clip_video_labels: 每个片段的视频流标签
             transitions: 每个片段对应的转场效果
-            transition_duration: 统一转场时长，None 则使用引擎默认值
+            transition_duration: 全局默认转场时长，None 则使用引擎默认值
+            transition_durations: #1766 逐转场时长列表，与 transitions 等长；
+                None 时使用各 resolved config 的 duration
+            jitters: #1766 逐转场位置偏移列表（秒）
             output_label: 最终输出标签
 
         Returns:
@@ -127,6 +134,8 @@ class TransitionEngine:
                 clip_video_labels=clip_video_labels,
                 transitions=transitions,
                 transition_duration=transition_duration or self._default_duration,
+                transition_durations=transition_durations,
+                jitters=jitters,
                 output_label=output_label,
             )
 
@@ -134,17 +143,20 @@ class TransitionEngine:
         resolved = self.resolve_clip_transitions(transitions, clip_durations)
         resolved_effects = [c.effect for c in resolved]
 
-        # 使用统一的时长（取各转场中最大的时长作为基准，底层会做每步钳制）
-        dur = transition_duration or self._default_duration
-        if not dur:
-            dur = max(c.duration for c in resolved) if resolved else DEFAULT_TRANSITION_DURATION
+        # #1766: 逐转场时长（优先使用传入的 transition_durations，否则用 resolved config）
+        if transition_durations is not None:
+            resolved_durations = list(transition_durations)
+        else:
+            resolved_durations = [c.duration for c in resolved]
 
         # 调用底层构建
         return build_xfade_filter_chain(
             clip_durations=clip_durations,
             clip_video_labels=clip_video_labels,
             transitions=resolved_effects,
-            transition_duration=dur,
+            transition_duration=transition_duration or self._default_duration,
+            transition_durations=resolved_durations,
+            jitters=jitters,
             output_label=output_label,
         )
 

apps/worker/video_processing/unified_render_service.py

@@ -1870,16 +1870,27 @@ class UnifiedRenderService:
                     )
                 else:
                     # 有转场效果：用 TransitionEngine 构建 xfade 链
-                    layer_dur = 0.0
-                    for d in layer_transition_durations:
-                        if d > 0:
-                            layer_dur = d
-                            break
+                    # #1766: 提取逐转场时长（每个 clip 的 transition_duration，跳过第一个）
+                    # layer_transition_durations[i] 对应 clip i 的转场，第 0 个忽略
+                    per_transition_durations = [d for idx, d in enumerate(layer_transition_durations) if idx > 0]
+                    # #1766: 提取每个 clip 的 jitter（存在 config 中），跳过第一个
+                    layer_jitters = [
+                        (
+                            all_clips[layer_clip_indices[idx]].config.get("transition_jitter", 0.0)
+                            if isinstance(all_clips[layer_clip_indices[idx]].config, dict)
+                            else 0.0
+                        )
+                        for idx in range(len(layer_clip_indices))
+                    ]
+                    per_transition_jitters = [j for idx, j in enumerate(layer_jitters) if idx > 0]
                     xfade_filter, xfade_estimated_dur = self._transition_engine.build_xfade_chain(
                         clip_durations=layer_durations,
                         clip_video_labels=layer_labels,
                         transitions=layer_transitions,
-                        transition_duration=layer_dur if layer_dur > 0 else None,
+                        transition_durations=(
+                            per_transition_durations if any(d > 0 for d in per_transition_durations) else None
+                        ),
+                        jitters=per_transition_jitters if any(j != 0.0 for j in per_transition_jitters) else None,
                         output_label=out_label,
                     )
                     if xfade_filter:

docs/ai-avatar-api-contract-1822.md

@@ -0,0 +1,169 @@
+# AI 数字人前后端接口契约（#1797 / #1822）
+
+> 分支：`fix/ai-avatar-v3-1797`
+> 范围：TTS→对口型链路打通、语速/情绪透传、封面智能选帧、标题字段对齐
+> 本文档为前后端联调的唯一字段口径。
+
+---
+
+## 1. 对口型创建接口 `POST /api/v1/lipsync/jobs`
+
+支持两种输入模式，**二选一**：
+
+### 模式 A（推荐）：TTS 直生 —— 传音色 + 文案，后端内部合成音频
+
+前端无需先调 TTS。后端收到请求后：先调 CosyVoice 合成音频 → 转存 OSS → 再提交 MediaKit 对口型。
+
+```jsonc
+{
+  "video_url": "https://oss.../person.mp4",   // 必填，人物视频（MP4）
+  "voice_id": "cosyvoice-v3-flash-99-xxxx",    // 必填，音色 ID（预置音色 或 克隆 profile UUID）
+  "script_text": "省是浙江省，市是永康市……",     // 必填，要合成的文案
+  "speed": 1.0,                                 // 可选，语速 0.5~2.0，默认 1.0
+  "emotion": "excited",                         // 可选，情绪，见 §3
+  "enable_video_loop": false,                   // 可选，音频长于视频时是否循环画面
+  "project_id": ""                              // 可选
+}
+```
+
+### 模式 B：直接音频 —— 前端已准备好音频
+
+```jsonc
+{
+  "video_url": "https://oss.../person.mp4",     // 必填
+  "audio_url": "https://oss.../voice.mp3",      // 必填，mp3/aac/wav/m4a/flac
+  "enable_video_loop": false
+}
+```
+
+### 校验与错误码
+
+| 场景 | HTTP | detail.code |
+|------|------|-------------|
+| 既无 audio_url 又无 voice_id+script_text | 422 | （schema 校验） |
+| video_url 非 MP4 / audio_url 格式不支持 | 422 | （schema 校验） |
+| 克隆音色不属于当前用户 | 403 | `VoiceForbidden` |
+| 克隆音色尚未合成完成 | 400 | `VoiceNotReady` |
+| TTS 合成失败（如 CosyVoice 欠费） | 502 | `TTSSynthesisFailed` |
+| MediaKit 提交失败 | 502 | `*`（透传 MediaKit code） |
+
+### 轮询
+
+- `GET /api/v1/lipsync/jobs/{id}`：非终态任务先返回 DB 缓存，**后台异步刷新 MediaKit**（不会阻塞轮询）。
+- `status` 流转：`pending` → `submitted` → `running`/`processing`（MediaKit 中间态同步）→ `completed` / `failed`。
+- `completed` 时 `output_video_url` 为**已转存自家 OSS 的非临时 URL**（不会过期）。
+- 前端每 3s 轮询，命中 `completed`/`failed` 即停。
+
+---
+
+## 2. TTS 合成接口语速/情绪透传
+
+- `POST /api/v1/tts/synthesize`（异步任务）与 `POST /api/v1/tts/preview`（即时试听）均新增：
+  - `speed`：float，0.5~2.0，默认 1.0 → 透传 CosyVoice payload 的 `rate`
+  - `emotion`：string，见 §3 映射 → 透传 `emotion`
+- 透传链路：`route → CreateTTSJobUseCase(metadata) → TTSJobWorkflow.start_synthesis / 分段合成 → CosyVoiceService.submit_synthesize_task(rate/emotion)`。
+- 分段合成（长文案）与失败重合成路径同样透传 speed/emotion。
+
+---
+
+## 3. 情绪枚举（前后端统一）
+
+前端把中文选项映射成英文后传后端；后端同时接受中文/英文，非法值忽略（走默认自然）。
+
+| 前端选项 | 传参值 | CosyVoice 枚举 |
+|---------|--------|---------------|
+| 自然 | `natural` | natural |
+| 兴奋 | `excited` | excited |
+| 沉稳 | `calm` | calm |
+| 亲切 | `friendly` | friendly |
+
+后端 `normalize_emotion()` 也接受中文（自然/兴奋/沉稳/亲切）做兜底映射。
+
+---
+
+## 4. 智能封面接口 `POST /api/v1/ai-avatar/render/smart-cover`
+
+独立接口，**不依赖渲染任务**，前端「智能获取封面」按钮直接调用。
+
+**请求**
+```jsonc
+{
+  "video_url": "https://oss.../avatar_output.mp4",  // 必填，数字人视频
+  "max_frames": 5                                    // 可选，抽帧数量 1~10，默认 5
+}
+```
+
+**响应**
+```jsonc
+{
+  "cover_url": "https://oss.../ai-avatar/covers/xxx/cover_yy.jpg", // OSS 非临时 URL
+  "status": "completed",       // completed / fallback_failed
+  "message": ""                // 失败原因
+}
+```
+
+**实现**：复用智能剪辑同款能力 —— MediaKit `extract_frames(SpecifiedFrames)` 抽 5 帧 → `cover_frame_scorer.score_frames`（清晰度+亮度+色彩）评分选最佳 → 转存 OSS。
+**不再使用 FFmpeg 简单首帧**。渲染管线最终封面也优先走该智能选帧，MediaKit 不可用时才回退 FFmpeg。
+
+---
+
+## 5. 渲染接口 `POST /api/v1/ai-avatar/render`
+
+```jsonc
+{
+  "lipsync_job_id": "7c29a3b2-...",     // 必填，已 completed 的对口型任务
+  "script_id": "",                       // 可选！见下方说明
+  "b_roll_segments": [],                 // 可选，B-roll 片段
+  "title_config": { ... },               // 可选，单个标题配置 dict（见 §6）
+  "cover_config": { ... },               // 可选，封面配置（建议改用 smart-cover）
+  "project_id": ""
+}
+```
+
+**`script_id` 是否必填：可选。**
+- 从文案库选了文案时传对应文案 ID（后端做归属校验）。
+- **手动输入文案、走 TTS 直生模式时不传（留空）即可**——渲染管线不依赖文案内容，`script_id` 仅用于归属校验。留空不会卡手动文案用户。
+
+---
+
+## 6. 标题配置 `title_config` 字段清单（以 build_title_drawtext_filter 为准）
+
+渲染请求收的是**单个 `title_config` dict**（不是 `titles[]` 数组），字段与 `packages/domain/video_filter_builder.py` 的 `build_title_drawtext_filter()` 完全对齐：
+
+| 字段 | 别名 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|------|
+| `text` | `content` | string | ✅ | — | 标题文字；为空或 `enabled=false` 时不渲染标题 |
+| `enabled` | — | bool | ❌ | `true` | 是否启用标题；false 跳过 |
+| `font` | `font_preset` | string | ❌ | 思源黑体 | 字体名（后端按名字解析字体文件） |
+| `font_size` | `size` | int | ❌ | 36 | 字号（像素） |
+| `font_color` | `color` | string | ❌ | `#ffffff` | 文字颜色，`#RRGGBB`；后端自动去掉 `#`，也可传 `RRGGBB` 或颜色名 |
+| `position` | — | string | ❌ | `top` | 预设位置：`top`(y=50) / `center`(垂直居中) / `bottom`(底部上移50px) / `custom` |
+| `pos_x` | — | int/float | ❌ | — | 自定义 X 坐标（像素），仅 `position=custom` 生效 |
+| `pos_y` | — | int/float | ❌ | — | 自定义 Y 坐标（像素），仅 `position=custom` 生效 |
+| `bold` | — | bool | ❌ | `true` | 粗体（Bold 字体变体，回退 borderw 模拟） |
+| `stroke` | — | bool/object | ❌ | — | 描边。`true`=黑描边宽2；object 见下 |
+| `stroke.enabled` | — | bool | ❌ | true | 是否描边 |
+| `stroke.width` | — | int | ❌ | 2 | 描边宽度 |
+| `stroke.color` | — | string | ❌ | `#000000` | 描边颜色 |
+| `shadow` | — | bool/object | ❌ | — | 阴影。`true`=黑色阴影偏移2px；object 见下 |
+| `shadow.enabled` | — | bool | ❌ | true | 是否阴影 |
+| `shadow.color` | — | string | ❌ | `#000000` | 阴影颜色 |
+| `shadow.offset_x` | — | int | ❌ | 2 | 阴影 X 偏移 |
+| `shadow.offset_y` | — | int | ❌ | 2 | 阴影 Y 偏移 |
+
+**前端注意事项**
+- 标题是**整条成片一个标题**（单个 dict），不是按时间段的标题数组；没有 `start`/`end`/`frame`/`fontSize` 这些字段。
+- 位置用 `position` 四档枚举；自由摆放用 `position="custom"` + `pos_x`/`pos_y`（像素坐标，非比例）。
+- 颜色统一传 `#RRGGBB` 即可，后端会处理 `#`；三档预设位置下标题始终水平居中。
+- `stroke`/`shadow` 传 `true` 用默认样式，或传 object 精细控制颜色/宽度/偏移。
+
+---
+
+## 7. 前端对接清单
+
+1. 对口型：改用**模式 A**（voice_id + script_text + speed + emotion），不要再先调 TTS 拿 audio_url。
+2. 音色 ID：`voice_id` 可直接传克隆音色的 profile UUID，后端会解析为 CosyVoice voice_id（与 /tts 一致）。
+3. 情绪下拉：自然/兴奋/沉稳/亲切 → natural/excited/calm/friendly。
+4. 封面：点「智能获取封面」→ POST `/ai-avatar/render/smart-cover`，用返回的 `cover_url`。
+5. 渲染：手动文案直生场景 `script_id` 留空；标题传**单个** `title_config` dict（字段见 §6）。
+6. 轮询：识别 `running` 等中间态，不要只认 `submitted`。