feat(scripts): #1893 文案库对接三个AI能力（抖音提取/AI改写/AI生成标题） (#1935)

feat(scripts): #1893 AI能力对接（抖音提取/AI改写/AI生成标题）

apps/api/app/api/router.py

@@ -21,6 +21,7 @@ from app.api.routes.lipsync import router as lipsync_router
 from app.api.routes.points import points_router, usage_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.scripts_ai import router as scripts_ai_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
@@ -190,6 +191,11 @@ api_router.include_router(
     prefix="/scripts",
     tags=["ScriptLibrary"],
 )
+api_router.include_router(
+    scripts_ai_router,
+    prefix="/scripts",
+    tags=["ScriptLibrary AI"],
+)
 api_router.include_router(
     ai_avatar_render_router,
     prefix="/ai-avatar/render",

apps/api/app/api/routes/scripts_ai.py

@@ -0,0 +1,234 @@
+"""Scripts AI 能力路由 — Issue #1893.
+
+三个 AI 工具接口（均挂载在 /api/v1/scripts 前缀下）：
+- POST /extract-from-douyin  从抖音视频提取文案（yt-dlp 下载 + ASR 转写）
+- POST /ai-rewrite           AI 文案改写（复用豆包 LLM）
+- POST /ai-generate-titles   AI 标题生成（复用 generate_smart_titles）
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import tempfile
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.schemas.scripts_ai import (
+    AiGenerateTitlesRequest,
+    AiGenerateTitlesResponse,
+    AiRewriteRequest,
+    AiRewriteResponse,
+    ExtractFromDouyinRequest,
+    ExtractFromDouyinResponse,
+)
+from app.services.script_asr_service import (
+    ASRNotConfiguredError,
+    ASRTranscriptionError,
+    transcribe_to_text,
+)
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from packages.shared.ai_client import get_doubao_client
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+# 抖音 URL 校验：支持短链 v.douyin.com 和长链 www.douyin.com/video/
+_DOUYIN_URL_RE = re.compile(
+    r"^(https?://)?(v\.douyin\.com/\S+|www\.douyin\.com/video/\S+)$",
+    re.IGNORECASE,
+)
+
+
+def _validate_douyin_url(url: str) -> None:
+    """校验抖音 URL 格式，不合法时抛 HTTPException(400)."""
+    if not url or not url.strip():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="链接不能为空",
+        )
+    if not _DOUYIN_URL_RE.match(url.strip()):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="无效的抖音链接，仅支持 v.douyin.com 短链或 www.douyin.com/video/ 长链",
+        )
+
+
+# ── 1. 从抖音视频提取文案 ─────────────────────────────────────────────────────
+
+
+@router.post(
+    "/extract-from-douyin",
+    response_model=ExtractFromDouyinResponse,
+)
+def extract_from_douyin(
+    request: ExtractFromDouyinRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+) -> ExtractFromDouyinResponse:
+    """从抖音视频下载无水印视频并通过 ASR 提取文案."""
+    source_url = request.url.strip()
+    _validate_douyin_url(source_url)
+
+    # 确保 URL 有 scheme（yt-dlp 需要完整 URL）
+    url_for_download = source_url
+    if not re.match(r"^https?://", url_for_download, re.IGNORECASE):
+        url_for_download = "https://" + url_for_download
+
+    # 使用临时目录下载视频，退出时自动清理
+    try:
+        with tempfile.TemporaryDirectory(prefix="douyin_extract_") as temp_dir:
+            import yt_dlp
+
+            ydl_opts = {
+                "format": "best[ext=mp4]/best",
+                "outtmpl": f"{temp_dir}/%(id)s.%(ext)s",
+                "quiet": True,
+                "no_warnings": True,
+                "noplaylist": True,
+            }
+
+            try:
+                ydl = yt_dlp.YoutubeDL(ydl_opts)
+                info = ydl.extract_info(url_for_download, download=True)
+            except Exception as exc:
+                logger.error("抖音视频下载失败: url=%s error=%s", source_url, exc)
+                raise HTTPException(
+                    status_code=status.HTTP_502_BAD_GATEWAY,
+                    detail=f"视频下载失败: {exc}",
+                ) from exc
+
+            if info is None:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="无法解析该抖音链接",
+                )
+
+            video_path = ydl.prepare_filename(info)
+            duration = float(info.get("duration") or 0)
+
+            # ASR 转写
+            try:
+                text = transcribe_to_text(video_path)
+            except ASRNotConfiguredError as exc:
+                raise HTTPException(
+                    status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                    detail=str(exc),
+                ) from exc
+            except ASRTranscriptionError as exc:
+                raise HTTPException(
+                    status_code=status.HTTP_502_BAD_GATEWAY,
+                    detail=str(exc),
+                ) from exc
+
+    except HTTPException:
+        raise
+
+    return ExtractFromDouyinResponse(
+        text=text,
+        duration_seconds=duration,
+        source_url=source_url,
+    )
+
+
+# ── 2. AI 文案改写 ───────────────────────────────────────────────────────────
+
+
+@router.post(
+    "/ai-rewrite",
+    response_model=AiRewriteResponse,
+)
+def ai_rewrite(
+    request: AiRewriteRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+) -> AiRewriteResponse:
+    """使用豆包大模型改写文案."""
+    content = (request.content or "").strip()
+    if not content:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="文案内容不能为空",
+        )
+
+    style = request.style or "口语化"
+
+    client = get_doubao_client()
+    if not client.is_available:
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail="AI 服务不可用，请联系管理员配置豆包大模型 API Key",
+        )
+
+    system_prompt = (
+        "你是一个专业的短视频文案改写专家。请对以下文案进行改写，"
+        "要求：保留原意、口语化、适合短视频口播、调整语序避免查重。"
+    )
+    if style:
+        system_prompt += f"\n风格要求：{style}"
+
+    user_prompt = f"请改写以下文案：\n\n{content}"
+
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_prompt},
+    ]
+
+    try:
+        rewritten = client.chat_completion(
+            messages=messages,
+            temperature=0.8,
+            max_tokens=2048,
+        )
+    except Exception as exc:
+        logger.error("AI 改写调用失败: %s", exc)
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"AI 改写失败: {exc}",
+        ) from exc
+
+    if not rewritten:
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail="AI 改写未返回有效结果",
+        )
+
+    return AiRewriteResponse(
+        original=content,
+        rewritten=rewritten.strip(),
+        style=style,
+    )
+
+
+# ── 3. AI 标题生成 ───────────────────────────────────────────────────────────
+
+
+@router.post(
+    "/ai-generate-titles",
+    response_model=AiGenerateTitlesResponse,
+)
+def ai_generate_titles(
+    request: AiGenerateTitlesRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+) -> AiGenerateTitlesResponse:
+    """使用现有 generate_smart_titles 生成标题."""
+    content = (request.content or "").strip()
+    if not content:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="文案内容不能为空",
+        )
+
+    # count 限制在 1-5（Pydantic ge=1 le=5 已校验），但为兼容直接调用场景截断
+    count = max(1, min(5, request.count))
+
+    from app.services.ai_service import generate_smart_titles
+
+    result = generate_smart_titles(
+        description=content,
+        style="viral",
+        count=count,
+    )
+
+    titles = result.get("titles", [])[:count]
+
+    return AiGenerateTitlesResponse(titles=titles)

apps/api/app/api/routes/voice_clones.py

@@ -287,7 +287,46 @@ def retry_voice_clone(
     return _to_response(profile)
 
 
-_ALLOWED_PREVIEW_EMOTIONS = {"", "natural", "excited", "calm", "friendly"}
+_ALLOWED_PREVIEW_EMOTIONS = {
+    "",
+    # 7 种标准英文枚举（CosyVoice v3 官方值）
+    "neutral",
+    "happy",
+    "sad",
+    "angry",
+    "surprised",
+    "fearful",
+    "disgusted",
+    # 前端中文 7 标签
+    "中立",
+    "开心",
+    "难过",
+    "生气",
+    "惊讶",
+    "恐惧",
+    "厌恶",
+    # 旧英文 4 枚举 + 常见中文别名兼容
+    "natural",
+    "excited",
+    "calm",
+    "friendly",
+    "自然",
+    "愉快",
+    "高兴",
+    "快乐",
+    "兴奋",
+    "悲伤",
+    "愤怒",
+    "惊奇",
+    "吃惊",
+    "害怕",
+    "讨厌",
+    # 灵应 P1 指定别名
+    "中性",
+    "伤心",
+    "沉稳",
+    "亲切",
+}
 
 
 @router.get("/{clone_id}/preview", response_model=VoiceClonePreviewResponse)
@@ -295,7 +334,10 @@ def get_voice_clone_preview(
     clone_id: str,
     text: str = Query("", description="自定义试听文本，为空则使用默认示例"),
     speed: float = Query(1.0, ge=0.5, le=2.0, description="语速，0.5-2.0，默认 1.0"),
-    emotion: str = Query("", description="情绪：natural/excited/calm/friendly，空字符串为默认自然"),
+    emotion: str = Query(
+        "",
+        description="情绪：neutral/happy/sad/angry/surprised/fearful/disgusted，兼容旧值 natural/excited/calm/friendly，空为默认自然",
+    ),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     repository: SQLAlchemyVoiceCloneProfileRepository = Depends(get_voice_clone_profile_repository),
     cosyvoice: CosyVoiceService = Depends(get_cosyvoice_service),
@@ -311,7 +353,7 @@ def get_voice_clone_preview(
     if emotion not in _ALLOWED_PREVIEW_EMOTIONS:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"不支持的 emotion 值: {emotion}，可选: natural/excited/calm/friendly 或留空",
+            detail=f"不支持的 emotion 值: {emotion}，可选: neutral/happy/sad/angry/surprised/fearful/disgusted 或中文 中立/中性/开心/难过/伤心/生气/愤怒/惊讶/吃惊/恐惧/害怕/厌恶/讨厌 或留空",
         )
 
     use_case = GetVoiceCloneUseCase(repository)

apps/api/app/schemas/lipsync.py

@@ -67,7 +67,10 @@ class CreateLipsyncJobRequest(BaseModel):
     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="情绪（中文/英文：自然/兴奋/沉稳/亲切/开心/悲伤/愤怒/惊讶/恐惧/厌恶 等）")
+    emotion: str = Field(
+        "",
+        description="情绪（英文枚举 neutral/happy/sad/angry/surprised/fearful/disgusted，或中文 中立/开心/难过/生气/惊讶/恐惧/厌恶；空为默认自然）",
+    )
 
     enable_video_loop: bool = Field(
         True, description="音频长于视频时是否循环画面（AI数字人默认开启，防止音频长于视频被截断）"
@@ -120,7 +123,11 @@ class AiAvatarTtsPreviewRequest(BaseModel):
     voice_id: str = Field(..., min_length=1, max_length=128, description="音色 ID")
     script_text: str = Field(..., min_length=1, max_length=5000, description="要合成的文案")
     speed: float = Field(1.0, ge=0.5, le=2.0, description="语速（0.5-2.0），默认 1.0")
-    emotion: str = Field("natural", max_length=32, description="情绪")
+    emotion: str = Field(
+        "neutral",
+        max_length=32,
+        description="情绪（英文枚举 neutral/happy/sad/angry/surprised/fearful/disgusted，或中文 中立/开心/难过/生气/惊讶/恐惧/厌恶；默认 neutral）",
+    )
 
 
 class AiAvatarTtsPreviewResponse(BaseModel):

apps/api/app/schemas/scripts_ai.py

@@ -0,0 +1,60 @@
+"""Scripts AI 能力 Pydantic schemas — Issue #1893.
+
+抖音文案提取、AI 改写、AI 标题生成的请求/响应模型。
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+# ── 抖音文案提取 ─────────────────────────────────────────────────────────────
+
+
+class ExtractFromDouyinRequest(BaseModel):
+    """从抖音视频提取文案请求."""
+
+    url: str = Field(..., description="抖音视频链接（短链或长链）")
+
+
+class ExtractFromDouyinResponse(BaseModel):
+    """从抖音视频提取文案响应."""
+
+    text: str = Field(..., description="ASR 识别出的文案文本")
+    duration_seconds: float = Field(..., description="视频时长（秒）")
+    source_url: str = Field(..., description="原始视频链接")
+
+
+# ── AI 改写 ─────────────────────────────────────────────────────────────────
+
+
+class AiRewriteRequest(BaseModel):
+    """AI 文案改写请求."""
+
+    content: str = Field(..., description="原文内容")
+    style: Optional[str] = Field("口语化", description="改写风格，如 口语化/正式/活泼")
+
+
+class AiRewriteResponse(BaseModel):
+    """AI 文案改写响应."""
+
+    original: str = Field(..., description="原文")
+    rewritten: str = Field(..., description="改写后的文案")
+    style: str = Field(..., description="使用的改写风格")
+
+
+# ── AI 标题生成 ──────────────────────────────────────────────────────────────
+
+
+class AiGenerateTitlesRequest(BaseModel):
+    """AI 标题生成请求."""
+
+    content: str = Field(..., description="文案内容")
+    count: int = Field(3, ge=1, le=5, description="生成标题数量（1-5，默认3）")
+
+
+class AiGenerateTitlesResponse(BaseModel):
+    """AI 标题生成响应."""
+
+    titles: List[str] = Field(..., description="生成的标题列表")

apps/api/app/services/lipsync_service.py

@@ -360,7 +360,7 @@ class LipsyncService:
         voice_id: str,
         script_text: str,
         speed: float = 1.0,
-        emotion: str = "natural",
+        emotion: str = "neutral",
     ) -> dict:
         """同步做 TTS 合成 + 下载 + ffprobe + 句子时间戳计算.
 

apps/api/app/services/script_asr_service.py

@@ -0,0 +1,59 @@
+"""文案提取 ASR 服务封装 — Issue #1893.
+
+将已有的 ASR 服务工厂封装为面向文案提取场景的简单接口：
+- transcribe_to_text(video_path) -> str：将视频/音频转写为纯文本
+- 未配置 ASR 时抛 ASRNotConfiguredError（路由层映射为 503）
+- ASR 调用失败时抛 ASRTranscriptionError（路由层映射为 502）
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from packages.ports.asr_service import ASRServiceError
+
+logger = logging.getLogger(__name__)
+
+
+class ASRNotConfiguredError(Exception):
+    """ASR 服务未配置."""
+
+
+class ASRTranscriptionError(Exception):
+    """ASR 转写失败."""
+
+
+def transcribe_to_text(media_path: str | Path) -> str:
+    """将视频/音频文件转写为纯文本.
+
+    Args:
+        media_path: 媒体文件路径
+
+    Returns:
+        转写出的文本
+
+    Raises:
+        ASRNotConfiguredError: ASR 服务未配置
+        ASRTranscriptionError: ASR 调用失败
+    """
+    # 延迟导入，避免循环依赖和启动时副作用
+    from apps.worker.services.asr_service_factory import get_asr_service
+
+    asr = get_asr_service()
+    if asr is None:
+        raise ASRNotConfiguredError("ASR 服务未配置，请联系管理员配置火山 MediaKit 或阿里云 ASR 密钥")
+
+    try:
+        timeline = asr.transcribe(Path(media_path))
+        # 拼接所有分段的文本
+        text = "".join(seg.text for seg in timeline.segments)
+        return text.strip()
+    except ASRNotConfiguredError:
+        raise
+    except ASRServiceError as exc:
+        logger.error("ASR 转写失败: %s", exc)
+        raise ASRTranscriptionError(f"语音识别失败: {exc}") from exc
+    except Exception as exc:
+        logger.error("ASR 转写异常: %s", exc)
+        raise ASRTranscriptionError(f"语音识别失败: {exc}") from exc

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

@@ -40,7 +40,6 @@ async function loginWithRetry(
 
 type ProjectResponse = { id: string }
 type LibraryResponse = { id: string }
-type TemplateResponse = { id: string }
 type AssetListResponse = {
   items: Array<{
     id: string
@@ -126,28 +125,17 @@ test.describe("Core generation flow", () => {
       )
       .toBe("ready")
 
-    // Create an editing template so the generate page has at least one template
-    // (templates are now loaded from API; new users have none by default)
-    const template = await request.post(`${apiBase}/templates`, {
-      headers,
-      data: {
-        name: `E2E 测试模板 ${suffix}`,
-        mode: "pip",
-        estimated_duration: 30,
-        segments: [
-          {
-            segment_order: 1,
-            duration_min: 5,
-            duration_max: 30,
-            material_type: "video",
-          },
-        ],
-        tags: ["e2e"],
-      },
-    })
-    expect(template.status(), await template.text()).toBe(201)
-    const templateData = (await template.json()) as TemplateResponse
-    expect(templateData.id).toBeTruthy()
+    // #1926 P0 fix: POST /templates CRUD endpoint removed; GET /templates
+    // now auto-creates a default template for new users. Use the first one.
+    const templatesResp = await request.get(`${apiBase}/templates`, { headers })
+    expect(templatesResp.status(), await templatesResp.text()).toBe(200)
+    const templatesData = (await templatesResp.json()) as {
+      items: Array<{ id: string }>
+    }
+    expect(Array.isArray(templatesData.items)).toBe(true)
+    expect(templatesData.items.length).toBeGreaterThan(0)
+    const templateId = templatesData.items[0].id
+    expect(templateId).toBeTruthy()
 
     // Set auth in localStorage
     await page.addInitScript(

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

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

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

@@ -0,0 +1,87 @@
+/**
+ * 文案库 AI 能力 API（#1893）
+ * 三个端点均走真实后端，不参与 SCRIPTS_API_MOCK 开关。
+ */
+import apiClient from "../client"
+
+/** ── 1. 从抖音视频提取文案（下载 + ASR） */
+export interface ExtractFromDouyinRequest {
+  url: string
+}
+export interface ExtractFromDouyinResponse {
+  text: string
+  duration_seconds?: number
+  source_url?: string
+}
+
+export async function extractScriptFromDouyin(
+  body: ExtractFromDouyinRequest,
+  opts?: { signal?: AbortSignal },
+): Promise<ExtractFromDouyinResponse> {
+  const res = await apiClient.post<ExtractFromDouyinResponse>(
+    "/scripts/extract-from-douyin",
+    body,
+    {
+      // ASR 可能较慢，给足超时
+      timeout: 60_000,
+      signal: opts?.signal,
+    },
+  )
+  return res.data
+}
+
+/** ── 2. AI 改写文案 */
+export type RewriteStyle = "口语化" | "正式" | "活泼" | "治愈" | "励志"
+
+export const REWRITE_STYLE_OPTIONS: { value: RewriteStyle; label: string }[] = [
+  { value: "口语化", label: "口语化" },
+  { value: "正式", label: "正式" },
+  { value: "活泼", label: "活泼" },
+  { value: "治愈", label: "治愈" },
+  { value: "励志", label: "励志" },
+]
+
+export interface AiRewriteRequest {
+  content: string
+  style?: RewriteStyle
+}
+export interface AiRewriteResponse {
+  original: string
+  rewritten: string
+  style: RewriteStyle
+}
+
+export async function aiRewriteScript(
+  body: AiRewriteRequest,
+  opts?: { signal?: AbortSignal },
+): Promise<AiRewriteResponse> {
+  const res = await apiClient.post<AiRewriteResponse>("/scripts/ai-rewrite", body, {
+    timeout: 60_000,
+    signal: opts?.signal,
+  })
+  return res.data
+}
+
+/** ── 3. AI 生成标题 */
+export interface AiGenerateTitlesRequest {
+  content: string
+  count?: number
+}
+export interface AiGenerateTitlesResponse {
+  titles: string[]
+}
+
+export async function aiGenerateTitles(
+  body: AiGenerateTitlesRequest,
+  opts?: { signal?: AbortSignal },
+): Promise<AiGenerateTitlesResponse> {
+  const res = await apiClient.post<AiGenerateTitlesResponse>(
+    "/scripts/ai-generate-titles",
+    { content: body.content, count: body.count ?? 3 },
+    {
+      timeout: 30_000,
+      signal: opts?.signal,
+    },
+  )
+  return res.data
+}

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

@@ -1,13 +1,17 @@
 /**
- * 文案库页面 — Issue #1811（v2 完整版）
+ * 文案库页面 — Issue #1811（v2 完整版） + #1893 AI 能力
  * 功能：
  * - 列表页：卡片列表，搜索（标题/正文）、分类标签筛选、分页
  *   每条卡片展示：title、content 前 100 字摘要、title_text、分类 Tag、tags、使用次数、时间
  *   操作：编辑 / 删除 / 复制 / 使用（跳创作页预填）
  * - 新建/编辑弹窗：title、content 多行、segments（按空行自动拆分+手动编辑）、title_text、title_category、
  *   title_config（字体/颜色/位置/字号）、tags
+ * - #1893 AI 能力：
+ *   - 顶部「🎬 从抖音提取」按钮 → 输入抖音链接 → ASR 提取文案 → 自动填充到新建弹窗
+ *   - 新建/编辑弹窗中 content 下方「✨ AI 改写」按钮（带风格选择） → 对比弹窗让用户确认
+ *   - title 旁「✨ AI 生成标题」按钮 → 候选列表一键填入
  * - 删除确认（Popconfirm）
- * - 对接 api/scripts CRUD（mock 阶段 SCRIPTS_API_MOCK=true）
+ * - 对接 api/scripts CRUD（mock 阶段 SCRIPTS_API_MOCK=true，AI 接口始终走真实 API）
  *
  * 风格对齐标题库（.xx-scripts-* 命名，沿用 CSS 变量）
  */
@@ -19,12 +23,15 @@ import {
   Form,
   Input,
   InputNumber,
+  List,
   Modal,
   Pagination,
   Popconfirm,
   Select,
   Space,
+  Spin,
   Tag,
+  Typography,
   message,
 } from "antd"
 import {
@@ -35,6 +42,9 @@ import {
   PlayCircleOutlined,
   SearchOutlined,
   TagsOutlined,
+  VideoCameraOutlined,
+  RobotOutlined,
+  BulbOutlined,
 } from "@ant-design/icons"
 import { useNavigate } from "react-router-dom"
 import {
@@ -43,12 +53,23 @@ import {
   updateScript,
   deleteScript,
   duplicateScript,
+  extractScriptFromDouyin,
+  aiRewriteScript,
+  aiGenerateTitles,
+  REWRITE_STYLE_OPTIONS,
+} from "@/api/scripts"
+import type {
+  ScriptItem,
+  ScriptCategory,
+  ScriptUpsertRequest,
+  RewriteStyle,
+  AiRewriteResponse,
 } from "@/api/scripts"
-import type { ScriptItem, ScriptCategory, ScriptUpsertRequest } from "@/api/scripts"
 import { SCRIPT_CATEGORY_LABEL } from "@/api/scripts"
 import "./scripts.css"
 
 const { TextArea } = Input
+const { Paragraph, Text } = Typography
 
 const PAGE_SIZE = 12
 const CATEGORY_OPTIONS: { value: ScriptCategory | "all"; label: string }[] = [
@@ -72,6 +93,22 @@ const POSITION_OPTIONS = [
   { value: "bottom", label: "底部" },
 ] as const
 
+/** 提取后端返回的错误 detail（全局拦截器可能已弹 toast，但这里再兜一层） */
+function extractErrMsg(err: unknown, fallback: string): string {
+  const e = err as {
+    response?: { data?: { detail?: string | { message?: string }; message?: string } }
+    message?: string
+  }
+  const data = e?.response?.data
+  if (data?.detail) {
+    if (typeof data.detail === "string") return data.detail
+    if (typeof data.detail.message === "string") return data.detail.message
+  }
+  if (data?.message && typeof data.message === "string") return data.message
+  if (e?.message) return e.message
+  return fallback
+}
+
 const ScriptLibrary: React.FC = () => {
   const navigate = useNavigate()
 
@@ -82,12 +119,28 @@ const ScriptLibrary: React.FC = () => {
   const [keyword, setKeyword] = useState("")
   const [category, setCategory] = useState<ScriptCategory | "all">("all")
 
-  // 弹窗状态
+  // 主弹窗状态
   const [modalOpen, setModalOpen] = useState(false)
   const [editing, setEditing] = useState<ScriptItem | null>(null)
   const [submitting, setSubmitting] = useState(false)
   const [form] = Form.useForm<ScriptUpsertRequest & { tags_text?: string }>()
 
+  // ── #1893 AI 能力状态 ──
+  // 抖音提取
+  const [douyinModalOpen, setDouyinModalOpen] = useState(false)
+  const [douyinUrl, setDouyinUrl] = useState("")
+  const [douyinLoading, setDouyinLoading] = useState(false)
+
+  // AI 改写
+  const [rewriteModalOpen, setRewriteModalOpen] = useState(false)
+  const [rewriteStyle, setRewriteStyle] = useState<RewriteStyle>("口语化")
+  const [rewriteLoading, setRewriteLoading] = useState(false)
+  const [rewriteResult, setRewriteResult] = useState<AiRewriteResponse | null>(null)
+
+  // AI 生成标题
+  const [titleGenLoading, setTitleGenLoading] = useState(false)
+  const [titleCandidates, setTitleCandidates] = useState<string[]>([])
+
   const load = useCallback(async () => {
     setLoading(true)
     try {
@@ -97,7 +150,6 @@ const ScriptLibrary: React.FC = () => {
         keyword: keyword.trim() || undefined,
         category,
       })
-      // 兼容老接口返回数组的兜底
       if (Array.isArray(res)) {
         setItems(res)
         setTotal(res.length)
@@ -106,8 +158,7 @@ const ScriptLibrary: React.FC = () => {
         setTotal(res.total ?? 0)
       }
     } catch (err) {
-      const e = err as { message?: string }
-      message.error(e?.message ?? "加载文案列表失败")
+      message.error(extractErrMsg(err, "加载文案列表失败"))
     } finally {
       setLoading(false)
     }
@@ -117,8 +168,7 @@ const ScriptLibrary: React.FC = () => {
     load()
   }, [load])
 
-  const openCreate = () => {
-    setEditing(null)
+  const resetCreateForm = () => {
     form.resetFields()
     form.setFieldsValue({
       title: "",
@@ -137,6 +187,13 @@ const ScriptLibrary: React.FC = () => {
         italic: false,
       },
     })
+    setRewriteResult(null)
+    setTitleCandidates([])
+  }
+
+  const openCreate = () => {
+    setEditing(null)
+    resetCreateForm()
     setModalOpen(true)
   }
 
@@ -157,12 +214,16 @@ const ScriptLibrary: React.FC = () => {
         size: 48,
       },
     })
+    setRewriteResult(null)
+    setTitleCandidates([])
     setModalOpen(true)
   }
 
   const closeModal = () => {
     setModalOpen(false)
     setEditing(null)
+    setRewriteResult(null)
+    setTitleCandidates([])
   }
 
   /** 提交新建/编辑 */
@@ -189,10 +250,8 @@ const ScriptLibrary: React.FC = () => {
       closeModal()
       await load()
     } catch (err) {
-      // form 校验失败不弹 message
       if ((err as { errorFields?: unknown })?.errorFields) return
-      const e = err as { message?: string }
-      message.error(e?.message ?? "保存失败")
+      message.error(extractErrMsg(err, "保存失败"))
     } finally {
       setSubmitting(false)
     }
@@ -202,15 +261,13 @@ const ScriptLibrary: React.FC = () => {
     try {
       await deleteScript(id)
       message.success("文案已删除")
-      // 删除后若当前页空了，回退一页
       if (items.length === 1 && page > 1) {
         setPage(page - 1)
       } else {
         await load()
       }
     } catch (err) {
-      const e = err as { message?: string }
-      message.error(e?.message ?? "删除失败")
+      message.error(extractErrMsg(err, "删除失败"))
     }
   }
 
@@ -221,8 +278,7 @@ const ScriptLibrary: React.FC = () => {
       setPage(1)
       await load()
     } catch (err) {
-      const e = err as { message?: string }
-      message.error(e?.message ?? "复制失败")
+      message.error(extractErrMsg(err, "复制失败"))
     }
   }
 
@@ -254,6 +310,118 @@ const ScriptLibrary: React.FC = () => {
     other: "default",
   }
 
+  // ── #1893 AI 操作 ──
+
+  /** 打开抖音提取弹窗 */
+  const openDouyinModal = () => {
+    setDouyinUrl("")
+    setDouyinModalOpen(true)
+  }
+
+  /** 执行抖音提取，成功后打开新建弹窗并预填 content */
+  const handleDouyinExtract = async () => {
+    const url = douyinUrl.trim()
+    if (!url) {
+      message.warning("请粘贴抖音视频链接")
+      return
+    }
+    if (!/^https?:\/\//i.test(url)) {
+      message.warning("请输入以 http(s):// 开头的完整链接")
+      return
+    }
+    setDouyinLoading(true)
+    try {
+      const res = await extractScriptFromDouyin({ url })
+      message.success(`提取成功${res.duration_seconds ? `（时长 ${res.duration_seconds}s）` : ""}`)
+      setDouyinModalOpen(false)
+      setDouyinUrl("")
+      // 关闭抖音弹窗，打开新建弹窗预填 content
+      setEditing(null)
+      resetCreateForm()
+      form.setFieldsValue({
+        title: "",
+        content: res.text,
+        tags: [],
+        title_text: "",
+        title_category: "other",
+        title_config: {
+          font: "default",
+          color: "#ffffff",
+          stroke: "#000000",
+          position: "center",
+          size: 48,
+          bold: true,
+          italic: false,
+        },
+      })
+      setModalOpen(true)
+    } catch (err) {
+      message.error(extractErrMsg(err, "抖音文案提取失败"))
+    } finally {
+      setDouyinLoading(false)
+    }
+  }
+
+  /** 执行 AI 改写，结果写入 rewriteResult 让用户对比确认 */
+  const handleAiRewrite = async () => {
+    const content = form.getFieldValue("content") as string | undefined
+    if (!content || !content.trim()) {
+      message.warning("请先填写文案正文再改写")
+      return
+    }
+    setRewriteLoading(true)
+    setRewriteResult(null)
+    try {
+      const res = await aiRewriteScript({ content, style: rewriteStyle })
+      setRewriteResult(res)
+    } catch (err) {
+      message.error(extractErrMsg(err, "AI 改写失败"))
+    } finally {
+      setRewriteLoading(false)
+    }
+  }
+
+  /** 应用改写结果：替换 content 字段，关闭改写弹窗 */
+  const applyRewrite = () => {
+    if (!rewriteResult) return
+    form.setFieldsValue({ content: rewriteResult.rewritten })
+    setRewriteResult(null)
+    setRewriteModalOpen(false)
+    message.success("已应用改写结果")
+  }
+
+  /** 执行 AI 生成标题，生成候选 */
+  const handleGenerateTitles = async () => {
+    const content = form.getFieldValue("content") as string | undefined
+    if (!content || !content.trim()) {
+      message.warning("请先填写文案内容")
+      return
+    }
+    setTitleGenLoading(true)
+    setTitleCandidates([])
+    try {
+      const res = await aiGenerateTitles({ content, count: 3 })
+      if (!res.titles || res.titles.length === 0) {
+        message.info("AI 未返回可用标题，请稍后再试")
+        return
+      }
+      setTitleCandidates(res.titles)
+    } catch (err) {
+      message.error(extractErrMsg(err, "AI 生成标题失败"))
+    } finally {
+      setTitleGenLoading(false)
+    }
+  }
+
+  /** 点击候选标题直接填入 title 字段 */
+  const pickTitle = (t: string) => {
+    form.setFieldsValue({ title: t })
+  }
+
+  // 监听 content 字段，用于禁用生成标题按钮（content 为空时）
+  const watchedContent = Form.useWatch("content", form)
+  const contentEmpty = !watchedContent || !String(watchedContent).trim()
+
   return (
     <div className="xx-scripts-page">
       <div className="xx-scripts-layout">
@@ -282,6 +450,9 @@ const ScriptLibrary: React.FC = () => {
             />
           </Space>
           <div className="xx-scripts-filters-right">
+            <Button icon={<VideoCameraOutlined />} onClick={openDouyinModal}>
+              🎬 从抖音提取
+            </Button>
             <Button type="primary" icon={<PlusOutlined />} onClick={openCreate}>
               新建文案
             </Button>
@@ -296,7 +467,7 @@ const ScriptLibrary: React.FC = () => {
             description={
               keyword || category !== "all"
                 ? "没有匹配的文案"
-                : "暂无文案，点击右上角「新建文案」开始创作"
+                : "暂无文案，点击右上角「新建文案」或「🎬 从抖音提取」开始创作"
             }
           />
         ) : (
@@ -430,12 +601,49 @@ const ScriptLibrary: React.FC = () => {
         >
           <Form.Item
             name="title"
-            label="名称"
+            label={
+              <span>
+                名称
+                <Button
+                  type="link"
+                  size="small"
+                  icon={<BulbOutlined />}
+                  loading={titleGenLoading}
+                  disabled={contentEmpty}
+                  onClick={handleGenerateTitles}
+                  title={contentEmpty ? "请先填写文案内容" : "基于正文 AI 生成 3 个候选标题"}
+                  style={{ padding: "0 4px", marginLeft: 4, height: 22 }}
+                >
+                  ✨ AI 生成标题
+                </Button>
+              </span>
+            }
             rules={[{ required: true, message: "请填写文案名称" }, { max: 200 }]}
           >
             <Input placeholder="给这段文案起个名字" maxLength={200} />
           </Form.Item>
 
+          {/* AI 生成标题候选列表 */}
+          {titleCandidates.length > 0 && (
+            <div className="xx-ai-title-candidates">
+              <Text type="secondary" style={{ fontSize: 12 }}>
+                点击候选直接填入：
+              </Text>
+              <div className="xx-ai-title-list">
+                {titleCandidates.map((t, i) => (
+                  <Tag
+                    key={`${t}-${i}`}
+                    color="purple"
+                    className="xx-ai-title-tag"
+                    onClick={() => pickTitle(t)}
+                  >
+                    {t}
+                  </Tag>
+                ))}
+              </div>
+            </div>
+          )}
+
           <Form.Item
             name="content"
             label="正文"
@@ -445,6 +653,32 @@ const ScriptLibrary: React.FC = () => {
             <TextArea placeholder="在这里输入文案正文…" rows={6} maxLength={10000} />
           </Form.Item>
 
+          {/* AI 改写工具条 */}
+          <div className="xx-ai-rewrite-bar">
+            <Space size={8} wrap>
+              <Select
+                value={rewriteStyle}
+                onChange={setRewriteStyle}
+                options={REWRITE_STYLE_OPTIONS}
+                style={{ width: 110 }}
+                size="small"
+              />
+              <Button
+                size="small"
+                icon={<RobotOutlined />}
+                loading={rewriteLoading}
+                onClick={() => setRewriteModalOpen(true)}
+              >
+                ✨ AI 改写
+              </Button>
+              {rewriteResult && (
+                <Button size="small" type="link" onClick={() => setRewriteModalOpen(true)}>
+                  查看上一次改写结果
+                </Button>
+              )}
+            </Space>
+          </div>
+
           <Form.Item name="segments" hidden>
             <Input />
           </Form.Item>
@@ -510,6 +744,110 @@ const ScriptLibrary: React.FC = () => {
           </Form.Item>
         </Form>
       </Modal>
+
+      {/* 抖音提取弹窗 */}
+      <Modal
+        title="🎬 从抖音视频提取文案"
+        open={douyinModalOpen}
+        onCancel={() => !douyinLoading && setDouyinModalOpen(false)}
+        onOk={handleDouyinExtract}
+        confirmLoading={douyinLoading}
+        okText="开始提取"
+        cancelText="取消"
+        maskClosable={!douyinLoading}
+        closable={!douyinLoading}
+        destroyOnClose
+      >
+        <Paragraph type="secondary" style={{ marginBottom: 12, fontSize: 13 }}>
+          粘贴抖音分享链接（支持 v.douyin.com 短链和 www.douyin.com/video/ 长链）， AI
+          将自动下载音频并识别文案。首次识别可能需要 5-15 秒。
+        </Paragraph>
+        <Input.TextArea
+          placeholder="例如：https://v.douyin.com/xxxxx/ 或 https://www.douyin.com/video/xxxxx"
+          value={douyinUrl}
+          onChange={(e) => setDouyinUrl(e.target.value)}
+          rows={2}
+          autoSize={{ minRows: 2, maxRows: 4 }}
+          disabled={douyinLoading}
+        />
+        {douyinLoading && (
+          <div className="xx-ai-loading-hint">
+            <Spin size="small" style={{ marginRight: 8 }} />
+            正在下载视频并识别文案，可能需要数秒，请稍候…
+          </div>
+        )}
+      </Modal>
+
+      {/* AI 改写对比弹窗 */}
+      <Modal
+        title={`✨ AI 改写（${rewriteStyle}风格）`}
+        open={rewriteModalOpen}
+        onCancel={() => setRewriteModalOpen(false)}
+        footer={
+          rewriteResult ? (
+            <Space>
+              <Button onClick={() => setRewriteModalOpen(false)}>保留原文</Button>
+              <Button type="primary" onClick={applyRewrite}>
+                应用改写
+              </Button>
+            </Space>
+          ) : (
+            <Button onClick={() => setRewriteModalOpen(false)}>关闭</Button>
+          )
+        }
+        width={640}
+        destroyOnClose={false}
+      >
+        {!rewriteResult && !rewriteLoading && (
+          <Paragraph type="secondary" style={{ marginBottom: 16 }}>
+            将以「{rewriteStyle}」风格改写正文，生成后可对比确认是否应用。
+          </Paragraph>
+        )}
+        {rewriteLoading && (
+          <div className="xx-ai-loading-hint" style={{ padding: "32px 0" }}>
+            <Spin tip="AI 改写中…" />
+          </div>
+        )}
+        {rewriteResult && (
+          <List
+            dataSource={[
+              { label: "原文", text: rewriteResult.original, type: "original" },
+              {
+                label: `改写（${rewriteResult.style}）`,
+                text: rewriteResult.rewritten,
+                type: "rewrite",
+              },
+            ]}
+            renderItem={(item) => (
+              <List.Item className="xx-ai-rewrite-item">
+                <div className="xx-ai-rewrite-block">
+                  <div className="xx-ai-rewrite-label">
+                    <Tag color={item.type === "original" ? "default" : "purple"}>{item.label}</Tag>
+                  </div>
+                  <Paragraph
+                    className="xx-ai-rewrite-text"
+                    style={{ whiteSpace: "pre-wrap", marginBottom: 0 }}
+                  >
+                    {item.text}
+                  </Paragraph>
+                </div>
+              </List.Item>
+            )}
+          />
+        )}
+        {!rewriteResult && !rewriteLoading && (
+          <div style={{ textAlign: "center" }}>
+            <Button
+              type="primary"
+              icon={<RobotOutlined />}
+              loading={rewriteLoading}
+              onClick={handleAiRewrite}
+            >
+              开始改写
+            </Button>
+          </div>
+        )}
+      </Modal>
     </div>
   )
 }

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

@@ -166,3 +166,95 @@
     flex: 1;
   }
 }
+
+/* ── #1893 AI 能力样式 ── */
+
+/* 抖音提取 / AI 按钮与主按钮间距 */
+.xx-scripts-filters-right .ant-btn + .ant-btn {
+  margin-left: 8px;
+}
+
+/* AI 改写工具条（贴在正文 TextArea 下方） */
+.xx-ai-rewrite-bar {
+  display: flex;
+  align-items: center;
+  margin-top: -8px;
+  margin-bottom: 16px;
+  padding: 8px 12px;
+  background: linear-gradient(90deg, #f7f5ff 0%, #fff 100%);
+  border: 1px dashed #d3c6ff;
+  border-radius: 8px;
+}
+
+/* AI 生成标题候选 */
+.xx-ai-title-candidates {
+  margin-top: -8px;
+  margin-bottom: 12px;
+  padding: 10px 12px;
+  background: #fafaff;
+  border-radius: 8px;
+  border: 1px solid #eee6ff;
+}
+.xx-ai-title-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-top: 6px;
+}
+.xx-ai-title-tag {
+  cursor: pointer;
+  font-size: 13px;
+  padding: 4px 12px;
+  border-radius: 16px;
+  transition: transform 0.15s;
+  margin: 0;
+}
+.xx-ai-title-tag:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 2px 8px rgba(114, 46, 209, 0.18);
+}
+
+/* loading 提示文本 */
+.xx-ai-loading-hint {
+  display: flex;
+  align-items: center;
+  margin-top: 12px;
+  padding: 10px 12px;
+  color: var(--text-secondary, #666);
+  font-size: 13px;
+  background: #fafafa;
+  border-radius: 6px;
+}
+
+/* AI 改写对比块 */
+.xx-ai-rewrite-item {
+  border-bottom: 1px solid var(--border-color, #f0f0f0) !important;
+  padding: 12px 0 !important;
+}
+.xx-ai-rewrite-item:last-child {
+  border-bottom: none !important;
+}
+.xx-ai-rewrite-block {
+  width: 100%;
+}
+.xx-ai-rewrite-label {
+  margin-bottom: 6px;
+}
+.xx-ai-rewrite-text {
+  font-size: 13px;
+  line-height: 1.7;
+  color: var(--text-primary, #1f1f1f);
+  padding: 8px 12px;
+  background: #fafafa;
+  border-radius: 6px;
+  max-height: 180px;
+  overflow-y: auto;
+}
+.xx-ai-rewrite-item:first-child .xx-ai-rewrite-text {
+  color: var(--text-secondary, #666);
+  background: #f7f7f7;
+}
+.xx-ai-rewrite-item:last-child .xx-ai-rewrite-text {
+  background: linear-gradient(180deg, #faf5ff 0%, #ffffff 100%);
+  border: 1px solid #eee6ff;
+}

packages/application/cosyvoice_service.py

@@ -27,55 +27,125 @@ logger = logging.getLogger(__name__)
 
 
 # CosyVoice v3 情绪通过 input.instruction 中文自然语言指令控制（不再使用枚举 emotion 字段）。
-# 前端可传中文或英文情绪标签，统一归一化为中文描述词，再拼进 instruction。
-# 映射表 key: 小写中文/英文 → 中文情绪描述词
-EMOTION_MAP = {
-    # 原有四值（中文 + 英文）
-    "自然": "自然",
-    "兴奋": "兴奋开心",
-    "沉稳": "沉稳平静",
-    "亲切": "亲切友好",
-    "natural": "自然",
-    "excited": "兴奋开心",
-    "calm": "沉稳平静",
-    "friendly": "亲切友好",
-    "happy": "开心愉快",
-    # 新增情绪
-    "开心": "开心愉快",
-    "愉快": "开心愉快",
-    "sad": "悲伤难过",
-    "悲伤": "悲伤难过",
-    "难过": "悲伤难过",
-    "angry": "愤怒",
-    "愤怒": "愤怒",
-    "生气": "愤怒",
-    "surprised": "惊讶",
-    "惊讶": "惊讶",
-    "惊奇": "惊讶",
-    "fearful": "恐惧",
-    "恐惧": "恐惧",
-    "害怕": "恐惧",
-    "disgusted": "厌恶",
-    "厌恶": "厌恶",
-    "讨厌": "厌恶",
-    "严肃": "严肃",
-    "温柔": "温柔",
+# 官方文档：instruction 格式严格为 "你说话的情感是<情感值>。"，结尾中文句号不可省略；
+# 情感值必须是 7 种英文枚举之一：neutral/happy/sad/angry/surprised/fearful/disgusted。
+# 参考：https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list
+# 前端可传英文枚举或中文标签（中立/开心/难过/生气/惊讶/恐惧/厌恶），统一归一化为英文枚举。
+# 映射表 key（不区分大小写）: 英文枚举/旧英文/中文标签 → 7 种标准英文枚举
+EMOTION_MAP: dict[str, str] = {
+    # ── 7 种标准英文枚举（CosyVoice v3 官方支持的情感值）──
+    "neutral": "neutral",
+    "happy": "happy",
+    "sad": "sad",
+    "angry": "angry",
+    "surprised": "surprised",
+    "fearful": "fearful",
+    "disgusted": "disgusted",
+    # ── 前端中文 7 标签（P1：前端已扩展为这 7 个中文选项）──
+    "中立": "neutral",
+    "开心": "happy",
+    "难过": "sad",
+    "生气": "angry",
+    "惊讶": "surprised",
+    "恐惧": "fearful",
+    "厌恶": "disgusted",
+    # ── 常见中文别名 ──
+    "自然": "neutral",
+    "愉快": "happy",
+    "高兴": "happy",
+    "快乐": "happy",
+    "兴奋": "happy",  # 旧 excited → 映射到最接近的 happy
+    "悲伤": "sad",
+    "愤怒": "angry",
+    "惊奇": "surprised",
+    "吃惊": "surprised",
+    "害怕": "fearful",
+    "讨厌": "disgusted",
+    # ── 灵应派任务指定的中文别名（中性/伤心/愤怒 等）──
+    "中性": "neutral",
+    "伤心": "sad",
+    # ── 旧英文 4 枚举兼容（natural/excited/calm/friendly 归并到最接近的标准值）──
+    "natural": "neutral",
+    "excited": "happy",
+    "calm": "neutral",
+    "friendly": "happy",
 }
 
 
-def normalize_emotion(emotion: str) -> str:
-    """将前端情绪值归一化为中文描述词，用于拼入 instruction.
+# ── 支持 emotion Instruct 的 v3-flash 系统音色白名单（官方音色列表标注"Instruct：支持"且支持情感值）──
+# 这些音色的 instruction 必须使用中文固定格式 "你说话的情感是<emotion>。"；
+# longanhuan_v3 虽然 Instruct 支持，但只支持方言 instruct（请用<方言>表达。），不支持 emotion，故不列入。
+_SYSTEM_VOICES_WITH_EMOTION_INSTRUCT: frozenset[str] = frozenset(
+    {
+        "longanyang",  # 龙安洋（标杆音色）
+        "longanhuan",  # 龙安欢
+        "longhuhu_v3",  # 龙呼呼
+    }
+)
 
-    支持中文/英文；空串或未知值返回空串（调用方据此决定是否传 instruction）。
+
+def _is_cloned_voice(voice_id: str) -> bool:
+    """判断一个 voice_id 是否为克隆/设计音色（非系统预置音色）。
+
+    所有以 "long"/"loong" 开头的是系统预置音色（longxiaochun_v3/longanyang/loongabby_v3 等），
+    其余视为用户克隆音色/设计音色，支持任意中英文自然语言 instruction。
+    """
+    if not voice_id:
+        return False
+    v = voice_id.lower()
+    return not (v.startswith("long") or v.startswith("loong"))
+
+
+def build_emotion_instruction(voice_id: str, emotion_enum: str) -> str:
+    """根据 voice 类型构造符合官方规范的 emotion instruction.
+
+    - 克隆/设计音色（非 long*/loong* 前缀）：英文自然语言 "Speak in a {emotion} tone."，
+      DashScope 对克隆音色允许任意自然语言指令。
+    - 系统音色中 emotion-instruct 可用的（longanyang/longanhuan/longhuhu_v3）：
+      严格按官方中文固定格式 "你说话的情感是{emotion}。"，结尾中文句号不可省。
+    - 其他系统音色（含默认 longxiaochun_v3 等绝大多数 v3 系统音色）：官方不支持 Instruct，
+      返回空串（调用方据此不传 instruction，避免被 API 报错或忽略）。
+
+    Args:
+        voice_id: CosyVoice voice 参数
+        emotion_enum: 已归一化的 7 种英文枚举之一（neutral/happy/sad/...）
+
+    Returns:
+        拼接好的 instruction 字符串；不支持时返回空串
+    """
+    if not emotion_enum:
+        return ""
+    if _is_cloned_voice(voice_id):
+        return f"Speak in a {emotion_enum} tone."
+    if voice_id in _SYSTEM_VOICES_WITH_EMOTION_INSTRUCT:
+        return f"你说话的情感是{emotion_enum}。"
+    return ""
+
+
+def normalize_emotion(emotion: str) -> str:
+    """将前端情绪值归一化为 CosyVoice v3 官方英文枚举，用于拼入 instruction.
+
+    支持：
+    - 7 种标准英文枚举（neutral/happy/sad/angry/surprised/fearful/disgusted）；
+    - 前端中文 7 标签（中立/开心/难过/生气/惊讶/恐惧/厌恶）；
+    - 常见中文别名与旧英文 4 枚举兼容值（natural/excited/calm/friendly）；
+    - 大小写不敏感。
+
+    返回：始终返回 7 种英文枚举之一；空串/None 返回空串（调用方据此不传 instruction，
+    CosyVoice 按默认自然情绪合成）；未知值记录 warning 并默认 "neutral"。
     """
     if not emotion:
         return ""
     key = emotion.strip()
+    if not key:
+        return ""
+    # 大小写不敏感：先按原 key 查，再按 lower 查
     mapped = EMOTION_MAP.get(key) or EMOTION_MAP.get(key.lower())
     if mapped:
         return mapped
-    logger.warning("未知的 emotion 值，忽略: %r", emotion)
-    return ""
+    # 未识别的情绪值：默认 neutral，保证合成能正常进行
+    logger.warning("未知的 emotion 值 %r，默认使用 neutral", emotion)
+    return "neutral"
 
 
 # 系统音色仅支持中文/英文（language_hints 取值）
@@ -516,7 +586,9 @@ class CosyVoiceService:
             format: 输出格式（mp3/wav/pcm），空表示使用配置默认值
             speed: 语速（0.5-2.0），1.0 为正常速度
             volume: 音量（0-100），默认 50
-            emotion: 情绪（自然/兴奋/沉稳/亲切/开心/悲伤/愤怒/惊讶/恐惧/厌恶 等），空串不传
+            emotion: 情绪，英文枚举 neutral/happy/sad/angry/surprised/fearful/disgusted
+                     或前端中文标签（中立/开心/难过/生气/惊讶/恐惧/厌恶），兼容旧值
+                     natural/excited/calm/friendly；空串不传，未知值默认 neutral
             language: 语言代码（zh/en 等，默认 zh；系统音色仅 zh/en 传 language_hints）
 
         Returns:
@@ -545,10 +617,11 @@ class CosyVoiceService:
             "rate": speed,
             "volume": volume,
         }
-        # 情绪 → instruction 自然语言指令（CosyVoice v3 推荐方式）
+        # 情绪 → instruction（按 voice 类型选择格式）
         norm_emotion = normalize_emotion(emotion)
-        if norm_emotion:
-            input_payload["instruction"] = f"你说话的情感是{norm_emotion}。"
+        emotion_instruction = build_emotion_instruction(voice_id, norm_emotion)
+        if emotion_instruction:
+            input_payload["instruction"] = emotion_instruction
         # 语言 → language_hints 数组（仅取第一个元素生效）；
         # 系统音色（非克隆/非 voice_id 中包含下划线以外的短 ID）仅传 zh/en，其他语言不传避免报错
         norm_lang = normalize_language(language)

requirements.txt

@@ -17,3 +17,6 @@ python-dotenv==1.0.1
 # AI 数字人封面智能选帧（cover_frame_scorer 用 cv2/numpy 做清晰度/亮度/色彩评分）
 numpy==1.26.4
 opencv-python-headless==4.10.0.84
+
+# yt-dlp: 抖音视频下载（#1893 文案提取）
+yt-dlp>=2024.1.0

tests/unit/test_ai_avatar_emotion_tts_lipsync.py

@@ -20,37 +20,48 @@ os.environ.setdefault("JWT_SECRET_KEY", "dev-secret-key-for-testing")
 def test_normalize_emotion_english_values():
     from packages.application.cosyvoice_service import normalize_emotion
 
-    # 英文情绪统一归一化为中文描述词（用于 instruction 自然语言指令）
-    assert normalize_emotion("natural") == "自然"
-    assert normalize_emotion("excited") == "兴奋开心"
-    assert normalize_emotion("calm") == "沉稳平静"
-    assert normalize_emotion("friendly") == "亲切友好"
-    assert normalize_emotion("happy") == "开心愉快"
-    assert normalize_emotion("sad") == "悲伤难过"
-    assert normalize_emotion("angry") == "愤怒"
-    assert normalize_emotion("surprised") == "惊讶"
-    assert normalize_emotion("fearful") == "恐惧"
-    assert normalize_emotion("disgusted") == "厌恶"
+    # 英文情绪统一归一化为 CosyVoice v3 官方 7 种英文枚举
+    assert normalize_emotion("natural") == "neutral"
+    assert normalize_emotion("excited") == "happy"
+    assert normalize_emotion("calm") == "neutral"
+    assert normalize_emotion("friendly") == "happy"
+    assert normalize_emotion("happy") == "happy"
+    assert normalize_emotion("sad") == "sad"
+    assert normalize_emotion("angry") == "angry"
+    assert normalize_emotion("surprised") == "surprised"
+    assert normalize_emotion("fearful") == "fearful"
+    assert normalize_emotion("disgusted") == "disgusted"
 
 
 def test_normalize_emotion_chinese_values():
     from packages.application.cosyvoice_service import normalize_emotion
 
-    assert normalize_emotion("自然") == "自然"
-    assert normalize_emotion("兴奋") == "兴奋开心"
-    assert normalize_emotion("沉稳") == "沉稳平静"
-    assert normalize_emotion("亲切") == "亲切友好"
-    assert normalize_emotion("开心") == "开心愉快"
-    assert normalize_emotion("悲伤") == "悲伤难过"
-    assert normalize_emotion("愤怒") == "愤怒"
-    assert normalize_emotion("惊讶") == "惊讶"
+    # 中文标签归一化为对应英文枚举（CosyVoice v3 官方值）
+    assert normalize_emotion("自然") == "neutral"
+    assert normalize_emotion("兴奋") == "happy"
+    assert normalize_emotion("开心") == "happy"
+    assert normalize_emotion("悲伤") == "sad"
+    assert normalize_emotion("愤怒") == "angry"
+    assert normalize_emotion("惊讶") == "surprised"
+    assert normalize_emotion("恐惧") == "fearful"
+    assert normalize_emotion("厌恶") == "disgusted"
+    assert normalize_emotion("中立") == "neutral"
+    assert normalize_emotion("中性") == "neutral"
+    assert normalize_emotion("难过") == "sad"
+    assert normalize_emotion("伤心") == "sad"
+    assert normalize_emotion("生气") == "angry"
+    assert normalize_emotion("吃惊") == "surprised"
 
 
-def test_normalize_emotion_invalid_returns_empty():
+def test_normalize_emotion_invalid_defaults_neutral():
     from packages.application.cosyvoice_service import normalize_emotion
 
+    # 空串/None 返回空（调用方不传 instruction，走默认自然情绪）
     assert normalize_emotion("") == ""
-    assert normalize_emotion("喜怒哀乐") == ""
+    assert normalize_emotion(None) == ""
+    # 未知情绪默认 neutral（不中断合成，warning 日志）
+    assert normalize_emotion("喜怒哀乐") == "neutral"
+    assert normalize_emotion("unknown_xyz") == "neutral"
 
 
 # ── CosyVoice payload 携带 emotion + rate ──────────────────────────────
@@ -91,21 +102,45 @@ def _make_service_with_captured_client(captured: dict):
     return svc
 
 
-def test_submit_synthesize_payload_uses_instruction_and_language_hints():
-    """#1898: emotion 通过 instruction 中文自然语言指令传递；语言用 language_hints."""
+def test_submit_synthesize_payload_uses_instruction_for_cloned_voice():
+    """#1898: 克隆/设计音色传 emotion 时 instruction 走英文 'Speak in a {emotion} tone.' 格式；
+    不支持 Instruct 的系统音色（含默认 longxiaochun_v3）不传 instruction。"""
     captured: dict = {}
     svc = _make_service_with_captured_client(captured)
 
-    svc.submit_synthesize_task(text="你好", voice_id="longxiaochun_v3", speed=1.5, emotion="兴奋", language="zh-CN")
+    # 克隆音色（非 long/loong 前缀）→ 英文 tone 格式
+    svc.submit_synthesize_task(text="你好", voice_id="myclone_voice", speed=1.5, emotion="兴奋", language="zh-CN")
 
     inp = captured["json"]["input"]
-    # 不再传 emotion 枚举字段
     assert "emotion" not in inp
-    # 情绪通过 instruction 中文指令
-    assert inp["instruction"] == "你说话的情感是兴奋开心。"
-    # rate 字段保持
+    assert inp["instruction"] == "Speak in a happy tone."
     assert inp["rate"] == 1.5
-    # 系统音色 zh → language_hints=["zh"]
+    # 克隆音色不做 language_hints 限制
+    assert inp["language_hints"] == ["zh"]
+
+
+def test_submit_synthesize_payload_uses_chinese_instruction_for_emotion_system_voice():
+    """longanyang 等支持 emotion instruct 的系统音色 → 中文固定格式 '你说话的情感是{emotion}。'。"""
+    captured: dict = {}
+    svc = _make_service_with_captured_client(captured)
+
+    svc.submit_synthesize_task(text="你好", voice_id="longanyang", emotion="开心", language="zh-CN")
+
+    inp = captured["json"]["input"]
+    assert inp["instruction"] == "你说话的情感是happy。"
+    assert inp["language_hints"] == ["zh"]
+
+
+def test_submit_synthesize_payload_default_voice_omits_instruction_even_with_emotion():
+    """默认音色 longxiaochun_v3 官方不支持 Instruct，即使传 emotion 也不应拼 instruction，
+    避免被 API 忽略或报错。"""
+    captured: dict = {}
+    svc = _make_service_with_captured_client(captured)
+
+    svc.submit_synthesize_task(text="你好", voice_id="longxiaochun_v3", emotion="开心", language="zh-CN")
+
+    inp = captured["json"]["input"]
+    assert "instruction" not in inp
     assert inp["language_hints"] == ["zh"]
 
 
@@ -120,14 +155,15 @@ def test_submit_synthesize_payload_omits_instruction_when_emotion_empty():
     assert inp["language_hints"] == ["en"]
 
 
-def test_submit_synthesize_payload_english_emotion_maps_to_chinese():
+def test_submit_synthesize_payload_cloned_voice_english_emotion():
+    """克隆音色 + 英文 emotion 枚举 → 英文 tone 格式。"""
     captured: dict = {}
     svc = _make_service_with_captured_client(captured)
 
-    svc.submit_synthesize_task(text="hi", voice_id="longxiaochun_v3", emotion="sad")
+    svc.submit_synthesize_task(text="hi", voice_id="myclone_voice", emotion="sad")
 
     inp = captured["json"]["input"]
-    assert inp["instruction"] == "你说话的情感是悲伤难过。"
+    assert inp["instruction"] == "Speak in a sad tone."
 
 
 # ── 对口型 TTS 直生分支 ─────────────────────────────────────────────────

tests/unit/test_cosyvoice_emotion.py

@@ -0,0 +1,243 @@
+"""CosyVoice EMOTION_MAP / normalize_emotion / build_emotion_instruction 单测（P1 修复 #1898）.
+
+覆盖：
+- 7 种标准英文枚举 neutral/happy/sad/angry/surprised/fearful/disgusted
+  （CosyVoice v3 官方 emotion 值）
+- 大小写不敏感
+- 前端中文 7 标签（中立/开心/难过/生气/惊讶/恐惧/厌恶）→ 英文枚举
+- 灵应指定别名（中性/伤心/愤怒/吃惊）→ 英文枚举
+- 常见中文别名与旧英文 4 枚举兼容
+- 空串/空白/None 边界
+- 未知值默认 neutral（warning 日志）
+- build_emotion_instruction 三路分支：
+    · 克隆/设计音色 → "Speak in a {emotion} tone."
+    · 支持 emotion Instruct 的系统音色（longanyang/longanhuan/longhuhu_v3）→ "你说话的情感是{emotion}。"
+    · 默认系统音色（含 longxiaochun_v3）→ 返回空串（不传 instruction）
+"""
+
+from __future__ import annotations
+
+import logging
+
+import pytest
+
+from packages.application.cosyvoice_service import (
+    EMOTION_MAP,
+    build_emotion_instruction,
+    normalize_emotion,
+)
+
+# 7 种官方英文枚举
+SEVEN_STANDARD_ENUMS = [
+    "neutral",
+    "happy",
+    "sad",
+    "angry",
+    "surprised",
+    "fearful",
+    "disgusted",
+]
+
+# 前端中文 7 标签 → 期望英文枚举
+FRONTEND_CN_LABELS = [
+    ("中立", "neutral"),
+    ("开心", "happy"),
+    ("难过", "sad"),
+    ("生气", "angry"),
+    ("惊讶", "surprised"),
+    ("恐惧", "fearful"),
+    ("厌恶", "disgusted"),
+]
+
+# 灵应派任务补充的中文别名
+LINGYING_CN_ALIASES = [
+    ("中性", "neutral"),
+    ("伤心", "sad"),
+    ("愤怒", "angry"),
+    ("吃惊", "surprised"),
+]
+
+# 其他常见中文别名
+CN_ALIASES = [
+    ("自然", "neutral"),
+    ("愉快", "happy"),
+    ("高兴", "happy"),
+    ("快乐", "happy"),
+    ("兴奋", "happy"),
+    ("悲伤", "sad"),
+    ("惊奇", "surprised"),
+    ("害怕", "fearful"),
+    ("讨厌", "disgusted"),
+]
+
+# 旧英文 4 枚举 → 最接近的标准枚举
+OLD_FOUR_ENUMS = [
+    ("natural", "neutral"),
+    ("excited", "happy"),
+    ("calm", "neutral"),
+    ("friendly", "happy"),
+]
+
+# 支持 emotion Instruct 的系统音色（白名单）
+SYSTEM_EMOTION_VOICES = ["longanyang", "longanhuan", "longhuhu_v3"]
+
+# 不支持 Instruct 的典型系统音色（含默认音色 longxiaochun_v3）
+NON_INSTRUCT_SYSTEM_VOICES = [
+    "longxiaochun_v3",
+    "longxiaoxia_v3",
+    "longsanshu_v3",
+    "longyue_v3",
+    "longyingjing_v3",
+    "loongabby_v3",
+    "loongandy_v3",
+    "longfei_v3",
+]
+
+# 克隆/设计音色（非 long/loong 前缀）
+CLONED_VOICE_IDS = [
+    "myclone_abc123",
+    "xiaoming_20260915",
+    "clone_voice_42",
+    "custom_voice_test",
+]
+
+
+class TestEmotionMapSevenStandard:
+    @pytest.mark.parametrize("enum_val", SEVEN_STANDARD_ENUMS)
+    def test_standard_enum_maps_to_self(self, enum_val: str) -> None:
+        assert enum_val in EMOTION_MAP
+        assert EMOTION_MAP[enum_val] == enum_val
+
+    @pytest.mark.parametrize("enum_val", SEVEN_STANDARD_ENUMS)
+    def test_normalize_standard_enum(self, enum_val: str) -> None:
+        assert normalize_emotion(enum_val) == enum_val
+
+    @pytest.mark.parametrize("enum_val", SEVEN_STANDARD_ENUMS)
+    def test_normalize_case_insensitive(self, enum_val: str) -> None:
+        assert normalize_emotion(enum_val.upper()) == enum_val
+        assert normalize_emotion(enum_val.capitalize()) == enum_val
+        assert normalize_emotion(f"  {enum_val}  ") == enum_val
+
+    def test_neutral_maps_to_neutral(self) -> None:
+        assert normalize_emotion("neutral") == "neutral"
+
+
+class TestFrontendCnLabels:
+    @pytest.mark.parametrize("cn,expected", FRONTEND_CN_LABELS)
+    def test_cn_label_normalizes_to_enum(self, cn: str, expected: str) -> None:
+        assert normalize_emotion(cn) == expected
+
+
+class TestLingyingSpecAliases:
+    @pytest.mark.parametrize("cn,expected", LINGYING_CN_ALIASES)
+    def test_lingying_aliases(self, cn: str, expected: str) -> None:
+        assert normalize_emotion(cn) == expected
+
+
+class TestBackwardCompatAliases:
+    @pytest.mark.parametrize("old_key,expected", OLD_FOUR_ENUMS)
+    def test_old_four_enums(self, old_key: str, expected: str) -> None:
+        assert normalize_emotion(old_key) == expected
+
+    @pytest.mark.parametrize("cn_key,expected", CN_ALIASES)
+    def test_chinese_aliases(self, cn_key: str, expected: str) -> None:
+        assert normalize_emotion(cn_key) == expected
+
+
+class TestNormalizeEmotionEdgeCases:
+    @pytest.mark.parametrize("empty_val", ["", None])
+    def test_empty_or_none_returns_empty(self, empty_val) -> None:
+        assert normalize_emotion(empty_val) == ""
+
+    @pytest.mark.parametrize("ws", ["   ", "\t", "\n", "  \n  "])
+    def test_whitespace_only_returns_empty(self, ws: str) -> None:
+        assert normalize_emotion(ws) == ""
+
+    def test_unknown_value_defaults_to_neutral_with_warning(self, caplog) -> None:
+        caplog.set_level(logging.WARNING)
+        result = normalize_emotion("not_a_real_emotion_xyz")
+        assert result == "neutral"
+        assert any("未知的 emotion" in r.message for r in caplog.records)
+
+    def test_strips_leading_trailing_whitespace(self) -> None:
+        assert normalize_emotion("  happy  ") == "happy"
+        assert normalize_emotion("  生气  ") == "angry"
+        assert normalize_emotion("  中性  ") == "neutral"
+
+
+class TestBuildEmotionInstructionClonedVoice:
+    @pytest.mark.parametrize("voice_id", CLONED_VOICE_IDS)
+    @pytest.mark.parametrize("enum_val", SEVEN_STANDARD_ENUMS)
+    def test_cloned_voice_uses_english_tone_format(self, voice_id: str, enum_val: str) -> None:
+        inst = build_emotion_instruction(voice_id, enum_val)
+        assert inst == f"Speak in a {enum_val} tone."
+        assert inst.isascii(), f"克隆音色 instruction 必须是纯 ASCII 英文: {inst!r}"
+
+    @pytest.mark.parametrize(
+        "cn,expected",
+        FRONTEND_CN_LABELS + LINGYING_CN_ALIASES + CN_ALIASES,
+    )
+    def test_cloned_voice_chinese_input_english_output(self, cn: str, expected: str) -> None:
+        norm = normalize_emotion(cn)
+        inst = build_emotion_instruction("myclone_voice", norm)
+        assert inst == f"Speak in a {expected} tone."
+        assert inst.isascii()
+
+    def test_cloned_voice_empty_emotion_returns_empty(self) -> None:
+        assert build_emotion_instruction("myclone", "") == ""
+
+    @pytest.mark.parametrize("voice_id", CLONED_VOICE_IDS)
+    def test_cloned_voice_unknown_emotion_falls_back_neutral(self, voice_id: str) -> None:
+        norm = normalize_emotion("unknown_xyz")
+        assert norm == "neutral"
+        inst = build_emotion_instruction(voice_id, norm)
+        assert inst == "Speak in a neutral tone."
+
+
+class TestBuildEmotionInstructionSystemVoiceEmotion:
+    CN_PREFIX = "你说话的情感是"
+    CN_SUFFIX = "。"
+
+    @pytest.mark.parametrize("voice_id", SYSTEM_EMOTION_VOICES)
+    @pytest.mark.parametrize("enum_val", SEVEN_STANDARD_ENUMS)
+    def test_system_emotion_voice_cn_fixed_format(self, voice_id: str, enum_val: str) -> None:
+        inst = build_emotion_instruction(voice_id, enum_val)
+        assert inst == f"{self.CN_PREFIX}{enum_val}{self.CN_SUFFIX}"
+        assert inst.count("。") == 1
+        mid = inst[len(self.CN_PREFIX) : -len(self.CN_SUFFIX)]
+        assert mid == enum_val
+        assert mid.isascii(), f"系统音色 emotion 值必须是纯 ASCII 英文枚举: {inst!r}"
+
+    @pytest.mark.parametrize("voice_id", SYSTEM_EMOTION_VOICES)
+    def test_system_emotion_voice_empty_returns_empty(self, voice_id: str) -> None:
+        assert build_emotion_instruction(voice_id, "") == ""
+
+
+class TestBuildEmotionInstructionNonInstructSystemVoice:
+    @pytest.mark.parametrize("voice_id", NON_INSTRUCT_SYSTEM_VOICES)
+    @pytest.mark.parametrize("enum_val", SEVEN_STANDARD_ENUMS)
+    def test_non_instruct_voice_returns_empty(self, voice_id: str, enum_val: str) -> None:
+        assert build_emotion_instruction(voice_id, enum_val) == ""
+
+    def test_default_voice_longxiaochun_v3_no_instruction(self) -> None:
+        assert build_emotion_instruction("longxiaochun_v3", "happy") == ""
+        assert build_emotion_instruction("longxiaochun_v3", "neutral") == ""
+
+
+class TestBuildEmotionInstructionEdgeCases:
+    def test_empty_voice_id_treated_as_system(self) -> None:
+        assert build_emotion_instruction("", "happy") == ""
+
+    @pytest.mark.parametrize(
+        "voice_id,enum_val,expected",
+        [
+            ("MYCLONE_VOICE", "happy", "Speak in a happy tone."),
+            ("CloneVoice", "sad", "Speak in a sad tone."),
+        ],
+    )
+    def test_voice_id_case_handling(self, voice_id: str, enum_val: str, expected: str) -> None:
+        assert build_emotion_instruction(voice_id, enum_val) == expected
+
+    def test_loong_prefix_is_system_voice(self) -> None:
+        assert build_emotion_instruction("loongandy_v3", "happy") == ""
+        assert build_emotion_instruction("loongabby_v3", "angry") == ""

tests/unit/test_scripts_ai.py

@@ -0,0 +1,422 @@
+"""Scripts AI 能力单元测试 — Issue #1893.
+
+测试覆盖：
+- extract_from_douyin: 成功/非法URL/下载失败/ASR未配置/ASR失败
+- ai_rewrite: 成功/空内容/LLM失败
+- ai_generate_titles: 成功/count截断/空内容
+
+所有外部调用（yt_dlp、ASR、LLM）均通过 unittest.mock.patch 隔离。
+"""
+
+from __future__ import annotations
+
+import sys
+from unittest.mock import MagicMock, patch
+
+import pydantic
+import pytest
+
+sys.path.insert(0, "apps/api")
+
+
+def _make_auth_user(user_id: str = "u1"):
+    """构造 mock AuthenticatedUser."""
+    user = MagicMock()
+    user.id = user_id
+    auth = MagicMock()
+    auth.user = user
+    return auth
+
+
+def _mock_youtube_dl(
+    extract_info_return=None,
+    extract_info_side_effect=None,
+    prepare_filename_return="/tmp/douyin_extract_abc/abc123.mp4",
+):
+    """构造 yt_dlp.YoutubeDL 的 mock.
+
+    路由中用法: ydl = yt_dlp.YoutubeDL(opts); info = ydl.extract_info(...)
+    所以 mock_ydl_cls.return_value 就是 ydl 实例.
+    """
+    mock_ydl_instance = MagicMock()
+    if extract_info_side_effect is not None:
+        mock_ydl_instance.extract_info.side_effect = extract_info_side_effect
+    else:
+        mock_ydl_instance.extract_info.return_value = extract_info_return or {
+            "id": "abc123",
+            "duration": 120.5,
+        }
+    mock_ydl_instance.prepare_filename.return_value = prepare_filename_return
+    return mock_ydl_instance
+
+
+# ── extract_from_douyin ──────────────────────────────────────────────────────
+
+
+class TestExtractFromDouyin:
+    """POST /extract-from-douyin 测试."""
+
+    @patch("app.api.routes.scripts_ai.transcribe_to_text")
+    @patch("tempfile.TemporaryDirectory")
+    @patch("yt_dlp.YoutubeDL")
+    def test_extract_from_douyin_success(
+        self,
+        mock_ydl_cls,
+        mock_tempdir,
+        mock_transcribe,
+    ):
+        """正常流程：下载视频 + ASR 转写成功."""
+        from app.api.routes.scripts_ai import extract_from_douyin
+        from app.schemas.scripts_ai import ExtractFromDouyinRequest
+
+        mock_ydl_cls.return_value = _mock_youtube_dl(
+            extract_info_return={"id": "abc123", "duration": 120.5},
+        )
+
+        mock_td = MagicMock()
+        mock_td.__enter__ = MagicMock(return_value="/tmp/douyin_extract_abc")
+        mock_td.__exit__ = MagicMock(return_value=False)
+        mock_tempdir.return_value = mock_td
+
+        mock_transcribe.return_value = "这是一段测试文案内容"
+
+        req = ExtractFromDouyinRequest(url="https://v.douyin.com/xxxxx/")
+        auth = _make_auth_user()
+        result = extract_from_douyin(request=req, authenticated_user=auth)
+
+        assert result.text == "这是一段测试文案内容"
+        assert result.duration_seconds == 120.5
+        assert result.source_url == "https://v.douyin.com/xxxxx/"
+        mock_transcribe.assert_called_once()
+        mock_tempdir.assert_called_once()
+        mock_td.__exit__.assert_called_once()
+
+    @pytest.mark.parametrize(
+        "bad_url",
+        [
+            "",
+            "not-a-url",
+            "https://www.youtube.com/watch?v=abc",
+            "https://www.bilibili.com/video/BV123",
+            "https://douyin.com/something",
+            "ftp://v.douyin.com/xxx/",
+        ],
+    )
+    def test_extract_from_douyin_invalid_url(self, bad_url):
+        """非法 URL 返回 400."""
+        from app.api.routes.scripts_ai import extract_from_douyin
+        from app.schemas.scripts_ai import ExtractFromDouyinRequest
+        from fastapi import HTTPException
+
+        req = ExtractFromDouyinRequest(url=bad_url)
+        auth = _make_auth_user()
+
+        with pytest.raises(HTTPException) as exc_info:
+            extract_from_douyin(request=req, authenticated_user=auth)
+        assert exc_info.value.status_code == 400
+
+    @patch("tempfile.TemporaryDirectory")
+    @patch("yt_dlp.YoutubeDL")
+    def test_extract_from_douyin_download_failure(self, mock_ydl_cls, mock_tempdir):
+        """下载失败返回 502."""
+        from app.api.routes.scripts_ai import extract_from_douyin
+        from app.schemas.scripts_ai import ExtractFromDouyinRequest
+        from fastapi import HTTPException
+
+        mock_ydl_cls.return_value = _mock_youtube_dl(
+            extract_info_side_effect=Exception("Video unavailable"),
+        )
+
+        mock_td = MagicMock()
+        mock_td.__enter__ = MagicMock(return_value="/tmp/douyin_extract_abc")
+        mock_td.__exit__ = MagicMock(return_value=False)
+        mock_tempdir.return_value = mock_td
+
+        req = ExtractFromDouyinRequest(url="https://v.douyin.com/xxxxx/")
+        auth = _make_auth_user()
+
+        with pytest.raises(HTTPException) as exc_info:
+            extract_from_douyin(request=req, authenticated_user=auth)
+        assert exc_info.value.status_code == 502
+
+    @patch("app.api.routes.scripts_ai.transcribe_to_text")
+    @patch("tempfile.TemporaryDirectory")
+    @patch("yt_dlp.YoutubeDL")
+    def test_extract_from_douyin_asr_not_configured(
+        self,
+        mock_ydl_cls,
+        mock_tempdir,
+        mock_transcribe,
+    ):
+        """ASR 未配置返回 503."""
+        from app.api.routes.scripts_ai import extract_from_douyin
+        from app.schemas.scripts_ai import ExtractFromDouyinRequest
+        from app.services.script_asr_service import ASRNotConfiguredError
+        from fastapi import HTTPException
+
+        mock_ydl_cls.return_value = _mock_youtube_dl(
+            extract_info_return={"id": "abc123", "duration": 60},
+        )
+
+        mock_td = MagicMock()
+        mock_td.__enter__ = MagicMock(return_value="/tmp/douyin_extract_abc")
+        mock_td.__exit__ = MagicMock(return_value=False)
+        mock_tempdir.return_value = mock_td
+
+        mock_transcribe.side_effect = ASRNotConfiguredError("ASR 服务未配置")
+
+        req = ExtractFromDouyinRequest(url="https://v.douyin.com/xxxxx/")
+        auth = _make_auth_user()
+
+        with pytest.raises(HTTPException) as exc_info:
+            extract_from_douyin(request=req, authenticated_user=auth)
+        assert exc_info.value.status_code == 503
+
+    @patch("app.api.routes.scripts_ai.transcribe_to_text")
+    @patch("tempfile.TemporaryDirectory")
+    @patch("yt_dlp.YoutubeDL")
+    def test_extract_from_douyin_asr_failure(
+        self,
+        mock_ydl_cls,
+        mock_tempdir,
+        mock_transcribe,
+    ):
+        """ASR 调用失败返回 502."""
+        from app.api.routes.scripts_ai import extract_from_douyin
+        from app.schemas.scripts_ai import ExtractFromDouyinRequest
+        from app.services.script_asr_service import ASRTranscriptionError
+        from fastapi import HTTPException
+
+        mock_ydl_cls.return_value = _mock_youtube_dl(
+            extract_info_return={"id": "abc123", "duration": 60},
+        )
+
+        mock_td = MagicMock()
+        mock_td.__enter__ = MagicMock(return_value="/tmp/douyin_extract_abc")
+        mock_td.__exit__ = MagicMock(return_value=False)
+        mock_tempdir.return_value = mock_td
+
+        mock_transcribe.side_effect = ASRTranscriptionError("语音识别失败: timeout")
+
+        req = ExtractFromDouyinRequest(url="https://v.douyin.com/xxxxx/")
+        auth = _make_auth_user()
+
+        with pytest.raises(HTTPException) as exc_info:
+            extract_from_douyin(request=req, authenticated_user=auth)
+        assert exc_info.value.status_code == 502
+
+
+# ── ai_rewrite ───────────────────────────────────────────────────────────────
+
+
+class TestAiRewrite:
+    """POST /ai-rewrite 测试."""
+
+    @patch("app.api.routes.scripts_ai.get_doubao_client")
+    def test_ai_rewrite_success(self, mock_get_client):
+        """正常改写成功."""
+        from app.api.routes.scripts_ai import ai_rewrite
+        from app.schemas.scripts_ai import AiRewriteRequest
+
+        mock_client = MagicMock()
+        mock_client.is_available = True
+        mock_client.chat_completion.return_value = "改写后的文案内容，口语化风格"
+        mock_get_client.return_value = mock_client
+
+        req = AiRewriteRequest(content="原始文案内容", style="口语化")
+        auth = _make_auth_user()
+        result = ai_rewrite(request=req, authenticated_user=auth)
+
+        assert result.original == "原始文案内容"
+        assert result.rewritten == "改写后的文案内容，口语化风格"
+        assert result.style == "口语化"
+        mock_client.chat_completion.assert_called_once()
+
+    def test_ai_rewrite_empty_content(self):
+        """空内容返回 400."""
+        from app.api.routes.scripts_ai import ai_rewrite
+        from app.schemas.scripts_ai import AiRewriteRequest
+        from fastapi import HTTPException
+
+        req = AiRewriteRequest(content="   ", style="口语化")
+        auth = _make_auth_user()
+
+        with pytest.raises(HTTPException) as exc_info:
+            ai_rewrite(request=req, authenticated_user=auth)
+        assert exc_info.value.status_code == 400
+
+    @patch("app.api.routes.scripts_ai.get_doubao_client")
+    def test_ai_rewrite_llm_failure(self, mock_get_client):
+        """LLM 调用失败返回 502."""
+        from app.api.routes.scripts_ai import ai_rewrite
+        from app.schemas.scripts_ai import AiRewriteRequest
+        from fastapi import HTTPException
+
+        mock_client = MagicMock()
+        mock_client.is_available = True
+        mock_client.chat_completion.side_effect = Exception("API timeout")
+        mock_get_client.return_value = mock_client
+
+        req = AiRewriteRequest(content="测试内容", style="口语化")
+        auth = _make_auth_user()
+
+        with pytest.raises(HTTPException) as exc_info:
+            ai_rewrite(request=req, authenticated_user=auth)
+        assert exc_info.value.status_code == 502
+
+    @patch("app.api.routes.scripts_ai.get_doubao_client")
+    def test_ai_rewrite_client_unavailable(self, mock_get_client):
+        """客户端不可用返回 502."""
+        from app.api.routes.scripts_ai import ai_rewrite
+        from app.schemas.scripts_ai import AiRewriteRequest
+        from fastapi import HTTPException
+
+        mock_client = MagicMock()
+        mock_client.is_available = False
+        mock_get_client.return_value = mock_client
+
+        req = AiRewriteRequest(content="测试内容", style="口语化")
+        auth = _make_auth_user()
+
+        with pytest.raises(HTTPException) as exc_info:
+            ai_rewrite(request=req, authenticated_user=auth)
+        assert exc_info.value.status_code == 502
+
+
+# ── ai_generate_titles ───────────────────────────────────────────────────────
+
+
+class TestAiGenerateTitles:
+    """POST /ai-generate-titles 测试."""
+
+    @patch("app.services.ai_service.get_doubao_client")
+    def test_generate_titles_success(self, mock_get_client):
+        """正常生成标题."""
+        from app.api.routes.scripts_ai import ai_generate_titles
+        from app.schemas.scripts_ai import AiGenerateTitlesRequest
+
+        mock_client = MagicMock()
+        mock_client.is_available = False  # 走 fallback 路径
+        mock_get_client.return_value = mock_client
+
+        req = AiGenerateTitlesRequest(content="这是一段关于美食的文案", count=3)
+        auth = _make_auth_user()
+        result = ai_generate_titles(request=req, authenticated_user=auth)
+
+        assert len(result.titles) == 3
+        assert all(isinstance(t, str) for t in result.titles)
+
+    @patch("app.services.ai_service.get_doubao_client")
+    def test_generate_titles_count_clamp(self, mock_get_client):
+        """count 超出范围时 Pydantic 校验拦截."""
+        from app.schemas.scripts_ai import AiGenerateTitlesRequest
+
+        mock_client = MagicMock()
+        mock_client.is_available = False
+        mock_get_client.return_value = mock_client
+
+        auth = _make_auth_user()
+
+        # count=10 被 Pydantic le=5 校验拦截 → ValidationError
+        with pytest.raises(pydantic.ValidationError):
+            AiGenerateTitlesRequest(content="测试", count=10)
+
+        # count=0 被 Pydantic ge=1 校验拦截 → ValidationError
+        with pytest.raises(pydantic.ValidationError):
+            AiGenerateTitlesRequest(content="测试", count=0)
+
+    @patch("app.services.ai_service.get_doubao_client")
+    def test_generate_titles_count_valid_range(self, mock_get_client):
+        """count=1 和 count=5 正常工作."""
+        from app.api.routes.scripts_ai import ai_generate_titles
+        from app.schemas.scripts_ai import AiGenerateTitlesRequest
+
+        mock_client = MagicMock()
+        mock_client.is_available = False
+        mock_get_client.return_value = mock_client
+
+        auth = _make_auth_user()
+
+        # count=5
+        req = AiGenerateTitlesRequest(content="测试内容", count=5)
+        result = ai_generate_titles(request=req, authenticated_user=auth)
+        assert len(result.titles) <= 5
+
+        # count=1
+        req = AiGenerateTitlesRequest(content="测试内容", count=1)
+        result = ai_generate_titles(request=req, authenticated_user=auth)
+        assert len(result.titles) >= 1
+
+    def test_generate_titles_empty_content(self):
+        """空内容返回 400."""
+        from app.api.routes.scripts_ai import ai_generate_titles
+        from app.schemas.scripts_ai import AiGenerateTitlesRequest
+        from fastapi import HTTPException
+
+        req = AiGenerateTitlesRequest(content="", count=3)
+        auth = _make_auth_user()
+
+        with pytest.raises(HTTPException) as exc_info:
+            ai_generate_titles(request=req, authenticated_user=auth)
+        assert exc_info.value.status_code == 400
+
+    @patch("app.services.ai_service.get_doubao_client")
+    def test_generate_titles_default_count(self, mock_get_client):
+        """不传 count 时默认 3."""
+        from app.api.routes.scripts_ai import ai_generate_titles
+        from app.schemas.scripts_ai import AiGenerateTitlesRequest
+
+        mock_client = MagicMock()
+        mock_client.is_available = False
+        mock_get_client.return_value = mock_client
+
+        req = AiGenerateTitlesRequest(content="测试文案内容")
+        auth = _make_auth_user()
+        result = ai_generate_titles(request=req, authenticated_user=auth)
+
+        assert len(result.titles) == 3
+
+
+# ── URL 校验辅助函数 ─────────────────────────────────────────────────────────
+
+
+class TestValidateDouyinUrl:
+    """URL 校验逻辑单元测试."""
+
+    @pytest.mark.parametrize(
+        "valid_url",
+        [
+            "https://v.douyin.com/abc123/",
+            "http://v.douyin.com/abc123/",
+            "v.douyin.com/abc123/",
+            "https://www.douyin.com/video/1234567890",
+            "http://www.douyin.com/video/1234567890",
+            "www.douyin.com/video/1234567890",
+        ],
+    )
+    def test_valid_urls(self, valid_url):
+        """合法 URL 不抛异常."""
+        from app.api.routes.scripts_ai import _validate_douyin_url
+
+        _validate_douyin_url(valid_url)
+
+    @pytest.mark.parametrize(
+        "invalid_url",
+        [
+            "",
+            "   ",
+            "https://www.youtube.com/watch?v=abc",
+            "https://www.bilibili.com/video/BV123",
+            "https://douyin.com/something",
+            "ftp://v.douyin.com/xxx/",
+            "not-a-url",
+        ],
+    )
+    def test_invalid_urls(self, invalid_url):
+        """非法 URL 抛 400."""
+        from app.api.routes.scripts_ai import _validate_douyin_url
+        from fastapi import HTTPException
+
+        with pytest.raises(HTTPException) as exc_info:
+            _validate_douyin_url(invalid_url)
+        assert exc_info.value.status_code == 400

tests/unit/test_voice_clone_preview.py

@@ -196,7 +196,7 @@ class TestVoiceClonePreview:
         cosyvoice = MagicMock()
 
         with pytest.raises(HTTPException) as exc_info:
-            self._call_preview(profile, cosyvoice, emotion="angry")
+            self._call_preview(profile, cosyvoice, emotion="invalid_emotion_xyz")
 
         assert exc_info.value.status_code == 400
         cosyvoice.synthesize_speech.assert_not_called()