feat(web): 标题模板管理系统 — 预设区域升级为模板卡片网格，支持新建/编辑/复制/删除 + 持久化

Bug修复： - Bug1：预设选中后手动改参数自动脱离预设（useRef→useState管理activePreset） - Bug2：预设卡片预览字号统一（canvas固定120px宽度渲染） - Bug3：描边参数始终可手动调整（预设只给初始值不锁定）功能升级： - 预设区域改为4列模板卡片网格（预览+名称+系统/自定义标签） - 新增「新建模板」按钮，编辑模式实时预览+参数面板 - 支持编辑/复制/删除用户自定义模板 - 模板数据持久化到localStorage（key: xiaoxia-title-templates）影响范围：TitleStylePanel公共组件，智能剪辑和AI数字人两个页面自动生效
Merge pull request 'refactor: 统一字体常量，消除 generate/constants.ts 与 components/title/constants.ts 的重复定义' (#2012 ) from fix/unify-font-constants into develop
2026-09-22 22:25:58 +08:00 · 2026-09-22 22:00:34 +08:00 · 2026-09-22 21:11:20 +08:00 · 2026-09-22 13:17:22 +08:00 · 2026-09-22 13:03:57 +08:00 · 2026-09-22 12:53:45 +08:00
27 changed files with 1249 additions and 188 deletions
@@ -93,7 +93,7 @@ def register_worker(
    svc: GpuLipsyncService = Depends(_get_svc),
    _token: str = Depends(_verify_gpu_token),
 ):
-    svc.register_worker(
+    worker, cancel_task = svc.register_worker(
        worker_id=body.worker_id,
        hostname=body.hostname,
        gpu_name=body.gpu_name,
@@ -101,7 +101,7 @@ def register_worker(
        capabilities=body.capabilities,
        task_id=body.task_id,
    )
-    return GpuWorkerRegisterResponse(ok=True, server_time=datetime.now(UTC), message="ok")
+    return GpuWorkerRegisterResponse(ok=True, server_time=datetime.now(UTC), message="ok", cancel_task=cancel_task)


 # ── GET /lipsync/poll — Worker 轮询拉任务 ─────────────────────────
@@ -346,13 +346,13 @@ def cancel_lipsync_job(
    current_user: AuthenticatedUser = Depends(get_current_user),
    svc: LipsyncService = Depends(_get_service),
 ):
-    """取消对口型任务（仅 pending/tts_processing/submitted 状态可取消）."""
+    """取消对口型任务（仅 pending/tts_processing/submitted/processing 状态可取消）."""
    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/tts_processing/submitted 可取消",
+            detail=f"任务状态 {job.status} 不可取消，仅 pending/tts_processing/submitted/processing 可取消",
        )
    return job
@@ -36,6 +36,7 @@ class GpuWorkerRegisterResponse(BaseModel):
    ok: bool = True
    server_time: datetime
    message: str = "ok"
+    cancel_task: bool = Field(False, description="当前心跳任务是否已被用户取消；为 true 时 Worker 应终止推理")


 # ── 轮询任务 ────────────────────────────────────────────────────
@@ -50,13 +50,16 @@ class GpuLipsyncService:
        free_vram_mb: int = 0,
        capabilities: str = "musetalk",
        task_id: Optional[str] = None,
-    ) -> GpuWorkerModel:
+    ) -> tuple[GpuWorkerModel, bool]:
        """Worker 注册/心跳。

        task_id 非空时（Worker 推理期间的任务级心跳），同步把对应 processing
        任务的 last_heartbeat_at 续到当前时间，使长推理不会被
        ``_recover_timed_out_tasks`` 误回退。任务已结束 / 不属于该 worker
        （如已被超时回收重新派发）时忽略，不报错。
+
+        返回 ``(worker, cancel_task)``：当心跳任务已被用户取消时
+        ``cancel_task=True``，Worker 应尽快终止推理并释放 GPU。
        """
        now = datetime.now(UTC)
        worker = self.db.query(GpuWorkerModel).filter(GpuWorkerModel.worker_id == worker_id).one_or_none()
@@ -77,10 +80,11 @@ class GpuLipsyncService:
            worker.free_vram_mb = free_vram_mb
            worker.capabilities = capabilities or worker.capabilities
            worker.last_heartbeat_at = now
+        cancel_task = False
        if task_id:
-            self._touch_task_heartbeat(task_id, worker_id, now)
+            cancel_task = self._touch_task_heartbeat(task_id, worker_id, now)
        self.db.commit()
-        return worker
+        return worker, cancel_task

    # ── 轮询拉任务（Worker 调用） ──────────────────────────────────

@@ -166,6 +170,11 @@ class GpuLipsyncService:
            task.result_duration = duration_seconds or 0.0
            task.error_msg = ""
            task.finished_at = now
+        elif task.status == "cancelled":
+            # 用户已取消的任务，Worker 终止后上报失败，保持 cancelled 状态不回退
+            task.finished_at = now
+            task.error_msg = (error_msg or "用户取消")[:2000]
+            logger.info("GPU 任务 %s 已被用户取消，保持 cancelled 状态", task_id)
        else:
            # 失败：若仍可重试（已尝试次数 < MAX_ATTEMPTS）→ 回退 pending；否则 → failed
            if task.attempt < MAX_ATTEMPTS:
@@ -250,15 +259,21 @@ class GpuLipsyncService:
    def _result_key(self, task_id: str) -> str:
        return f"{self.RESULT_PREFIX}{task_id}.mp4"

-    def _touch_task_heartbeat(self, task_id: str, worker_id: str, now: datetime) -> None:
+    def _touch_task_heartbeat(self, task_id: str, worker_id: str, now: datetime) -> bool:
        """Worker 推理期间的任务级心跳：只刷新属于该 worker 且仍在 processing 的任务。

        任务不存在 / 已被超时回收重新派发 / 已完成 → 静默忽略（此时旧 worker 的
        结果上报会被结果接口按最终态处理）。
+
+        返回 ``cancel_task``：任务已被用户取消时为 True，Worker 应终止推理。
        """
        task = self.db.get(GpuLipsyncTaskModel, task_id)
        if task is None:
-            return
+            return False
+        # 任务已被用户取消 → 通知 Worker 终止推理
+        if task.status == "cancelled":
+            logger.info("任务心跳检测到已取消 task=%s worker=%s，通知 Worker 终止", task_id, worker_id)
+            return True
        if task.status != "processing" or task.worker_id != worker_id:
            logger.info(
                "忽略过期任务心跳 task=%s worker=%s（status=%s owner=%s）",
@@ -267,10 +282,11 @@ class GpuLipsyncService:
                task.status,
                task.worker_id,
            )
-            return
+            return False
        task.last_heartbeat_at = now
        task.updated_at = now
        self.db.flush()
+        return False

    def _touch_worker(self, worker_id: str, now: datetime) -> None:
        if not worker_id:
@@ -371,9 +387,7 @@ class GpuLipsyncService:
            task = self.db.get(GpuLipsyncTaskModel, task_id)
            if task is None:
                return None
-            if task.status == "done":
-                return task
-            if task.status == "failed":
+            if task.status in ("done", "failed", "cancelled"):
                return task
            # pending/processing 继续等
            if time.monotonic() >= deadline:
@@ -783,12 +783,32 @@ class LipsyncService:
    # ── 取消任务 ──────────────────────────────────────────────────────────

    def cancel_job(self, job_id: str, user_id: str) -> Optional[LipsyncJobModel]:
-        """取消任务（仅 pending/tts_processing/submitted 状态可取消）."""
+        """取消任务（pending/tts_processing/submitted/processing 状态可取消）.
+
+        当 job 走 GPU 路径（mediakit_task_id 以 "gpu:" 开头）且状态为 processing 时，
+        同步将关联的 GpuLipsyncTask 标记为 cancelled，以便 Worker 心跳时检测到取消信号。
+        """
        job = self.get_job(job_id, user_id)
        if job is None:
            return None

-        if job.status in ("pending", "tts_processing", "submitted"):
+        if job.status in ("pending", "tts_processing", "submitted", "processing"):
+            # GPU 路径：同步标记关联的 GPU 任务为 cancelled
+            if job.status == "processing" and job.mediakit_task_id and job.mediakit_task_id.startswith("gpu:"):
+                gpu_task_id = job.mediakit_task_id[4:]  # 去掉 "gpu:" 前缀
+                try:
+                    from packages.adapters.sqlalchemy_impl.models import GpuLipsyncTaskModel
+
+                    gpu_task = self.db.get(GpuLipsyncTaskModel, gpu_task_id)
+                    if gpu_task and gpu_task.status == "processing":
+                        gpu_task.status = "cancelled"
+                        gpu_task.error_msg = "用户取消"
+                        gpu_task.updated_at = datetime.now(UTC)
+                        gpu_task.finished_at = datetime.now(UTC)
+                        logger.info("GPU 任务 %s 已被用户取消（通过 job_id=%s）", gpu_task_id, job_id)
+                except Exception as exc:
+                    logger.warning("标记 GPU 任务取消失败（不影响 job 取消）: %s", exc)
+
            job.status = "cancelled"
            job.updated_at = datetime.now(UTC)
            self.db.commit()
@@ -98,6 +98,14 @@ def lipsync_gpu_process_async(self, job_id: str, user_id: str, gpu_task_id: str)
            _fallback_to_mediakit(db, job)
            return

+        if final_task.status == "cancelled":
+            # 用户已取消任务，不回退 MediaKit，直接标记 job 为 cancelled
+            job.status = "cancelled"
+            job.updated_at = datetime.now(UTC)
+            db.commit()
+            logger.info("[lipsync_gpu_async] GPU 任务已被用户取消: job_id=%s", job_id)
+            return
+
        if final_task.status != "done":
            logger.warning(
                "[lipsync_gpu_async] GPU 失败，回退 MediaKit: job_id=%s gpu_task=%s status=%s",
@@ -15,6 +15,7 @@ import type { TitleOption } from "@/pages/generate/components/title/TitleLibrary
 import type { TitleSettings } from "@/pages/generate/types"
 import { POSITION_OPTIONS } from "@/pages/generate/constants"
 import { FONT_OPTIONS, TITLE_PRESETS } from "@/components/title/constants"
+import { useTitleTemplates } from "@/pages/generate/hooks/useStep4Title/useTitleTemplates"
 import type { AiAvatarTitleConfig } from "../types"
 // #1894: 标题数据源切换到文案库，取 script.title 作为候选
 import { getScripts } from "@/api/scripts"
@@ -30,6 +31,9 @@ const PanelTitleConfig: React.FC<PanelTitleConfigProps> = ({ titleConfig, onUpda
  /** TitleStylePanel 内部高亮的预设 key（面板本地状态） */
  const [activePreset, setActivePreset] = useState<string | null>(null)

+  /** 模板管理 */
+  const { allTemplates, saveTemplate, updateTemplate, deleteTemplate, duplicateTemplate } = useTitleTemplates()
+
  /** 标题库选项（#1894：从文案库 scripts[].title 取候选） */
  const [titleOptions, setTitleOptions] = useState<TitleOption[]>([])
  useEffect(() => {
@@ -218,33 +222,63 @@ const PanelTitleConfig: React.FC<PanelTitleConfigProps> = ({ titleConfig, onUpda
    }
  }, [titleConfig])

-  /** 应用预设：覆盖新细粒度字段（颜色/描边/阴影/字号/字体等） */
+  /** 应用预设/模板：覆盖新细粒度字段（颜色/描边/阴影/字号/字体等） */
  const handleApplyPreset = (presetKey: string) => {
+    // 先找系统预设
    const preset = TITLE_PRESETS.find((p) => p.key === presetKey)
-    if (!preset) return
-    setActivePreset(presetKey)
-    const st = preset.style || {}
-    onUpdate({
-      font: st.font,
-      size: st.size,
-      color: st.color,
-      bold: st.bold,
-      italic: st.italic,
-      stroke: st.stroke,
-      stroke_width: st.stroke_width,
-      stroke_color: st.stroke_color,
-      shadow: st.shadow,
-      shadow_offset_x: st.shadow_offset_x,
-      shadow_offset_y: st.shadow_offset_y,
-      shadow_blur: st.shadow_blur,
-      shadow_color: st.shadow_color,
-      bg_enabled: st.bg_enabled,
-      bg_color: st.bg_color,
-      bg_padding: st.bg_padding,
-      bg_radius: st.bg_radius,
-      line_overrides: [],
-      cover_title_config: null,
-    })
+    if (preset) {
+      setActivePreset(presetKey)
+      const st = preset.style || {}
+      onUpdate({
+        font: st.font,
+        size: st.size,
+        color: st.color,
+        bold: st.bold,
+        italic: st.italic,
+        stroke: st.stroke,
+        stroke_width: st.stroke_width,
+        stroke_color: st.stroke_color,
+        shadow: st.shadow,
+        shadow_offset_x: st.shadow_offset_x,
+        shadow_offset_y: st.shadow_offset_y,
+        shadow_blur: st.shadow_blur,
+        shadow_color: st.shadow_color,
+        bg_enabled: st.bg_enabled,
+        bg_color: st.bg_color,
+        bg_padding: st.bg_padding,
+        bg_radius: st.bg_radius,
+        line_overrides: [],
+        cover_title_config: null,
+      })
+      return
+    }
+    // 再找用户模板
+    const tmpl = allTemplates.find((t) => t.key === presetKey)
+    if (tmpl && !tmpl.isSystem) {
+      setActivePreset(presetKey)
+      const st = tmpl.style || {}
+      onUpdate({
+        font: st.font,
+        size: st.size,
+        color: st.color,
+        bold: st.bold,
+        italic: st.italic,
+        stroke: st.stroke,
+        stroke_width: (st as any).stroke_width,
+        stroke_color: (st as any).stroke_color,
+        shadow: st.shadow,
+        shadow_offset_x: (st as any).shadow_offset_x,
+        shadow_offset_y: (st as any).shadow_offset_y,
+        shadow_blur: (st as any).shadow_blur,
+        shadow_color: (st as any).shadow_color,
+        bg_enabled: (st as any).bg_enabled,
+        bg_color: (st as any).bg_color,
+        bg_padding: (st as any).bg_padding,
+        bg_radius: (st as any).bg_radius,
+        line_overrides: [],
+        cover_title_config: null,
+      })
+    }
  }

  /** 字段 patch 透传：TitleStylePanel 的 onUpdateStyle（camelCase → snake_case） */
@@ -381,6 +415,11 @@ const PanelTitleConfig: React.FC<PanelTitleConfigProps> = ({ titleConfig, onUpda
        }
        POSITION_OPTIONS={POSITION_OPTIONS}
        FONT_OPTIONS={FONT_OPTIONS}
+        templates={allTemplates}
+        onSaveTemplate={(label, style, emoji) => saveTemplate(label, style as any, emoji)}
+        onUpdateTemplate={(key, patch) => updateTemplate(key, patch as any)}
+        onDeleteTemplate={deleteTemplate}
+        onDuplicateTemplate={duplicateTemplate}
      />

      {/* 自动生成字幕 */}
@@ -29,6 +29,7 @@ import { usePreviewAssets } from "./hooks/usePreviewAssets"
 import { useBatchVariantPlans } from "./hooks/useBatchVariantPlans"
 import { useVariantVoicePreview } from "./hooks/useVariantVoicePreview"
 import { useTitleStyleUpdaters } from "./hooks/useStep4Title/useTitleStyleUpdaters"
+import { useTitleTemplates } from "./hooks/useStep4Title/useTitleTemplates"
 import { getAssetsByKind } from "@/api/assets"
 import { previewTts } from "@/api/tts"
 import { usePointsStore } from "@/store/pointsStore"
@@ -156,6 +157,9 @@ const GeneratePage: React.FC = () => {
    onTitleSettingsChange: setTitleSettings,
  })

+  /* ── 模板管理 ─ */
+  const { allTemplates, saveTemplate, updateTemplate, deleteTemplate, duplicateTemplate } = useTitleTemplates()
+
  /* ── 配音素材库（TTS 试听）── */
  const { data: voiceMaterials = [] } = useQuery({
    queryKey: ["assets", "voice"],
@@ -643,6 +647,11 @@ const GeneratePage: React.FC = () => {
            onUpdateStyle={styleUpdaters.updateStyle}
            activePreset={styleUpdaters.activePreset}
            titlePresets={styleUpdaters.titlePresets}
+            templates={allTemplates}
+            onSaveTemplate={(label, style, emoji) => saveTemplate(label, style as any, emoji)}
+            onUpdateTemplate={(key, patch) => updateTemplate(key, patch as any)}
+            onDeleteTemplate={deleteTemplate}
+            onDuplicateTemplate={duplicateTemplate}
            bgm={bgm}
            bgmConfig={bgmConfig}
            coverSettings={coverSettings}
@@ -17,7 +17,7 @@ import type { EditPlanClip } from "@/api/template-editor"
 import { useSegmentScheduler, type PlaybackSegment } from "../hooks/useSegmentScheduler"
 import { usePreviewAudio } from "../hooks/usePreviewAudio"
 import { PreviewControls } from "./PreviewControls"
-import { getFontFamily } from "../constants"
+import { getFontFamily } from "@/components/title/constants"

 interface FrontendPreviewPlayerProps {
  assets: AssetItem[]
@@ -59,6 +59,20 @@ export interface GenerateStepContentProps {
    emoji?: string
    style: Record<string, unknown>
  }>
+  /* ── 模板管理 ── */
+  templates?: Array<{
+    key: string
+    label: string
+    emoji?: string
+    isSystem: boolean
+    style: Record<string, unknown>
+  }>
+  onSaveTemplate?: (label: string, style: Record<string, unknown>, emoji?: string) => void
+  onUpdateTemplate?: (key: string, patch: { label?: string; style?: Record<string, unknown>; emoji?: string }) => void
+  onDeleteTemplate?: (key: string) => void
+  onDuplicateTemplate?: (key: string) => void
+  selectedTemplateKey?: string | null
+  onSelectTemplate?: (key: string | null) => void
  /* ── 封面 ── */
  coverSettings: CoverConfig
  onCoverSettingsChange: (settings: CoverConfig) => void
@@ -128,6 +142,13 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
    onUpdateStyle,
    activePreset,
    titlePresets,
+    templates,
+    onSaveTemplate,
+    onUpdateTemplate,
+    onDeleteTemplate,
+    onDuplicateTemplate,
+    selectedTemplateKey,
+    onSelectTemplate,
    coverSettings,
    onCoverSettingsChange,
    onServerClipsChange,
@@ -201,6 +222,13 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
          onUpdateStyle={onUpdateStyle}
          activePreset={activePreset}
          titlePresets={titlePresets}
+          templates={templates}
+          onSaveTemplate={onSaveTemplate}
+          onUpdateTemplate={onUpdateTemplate}
+          onDeleteTemplate={onDeleteTemplate}
+          onDuplicateTemplate={onDuplicateTemplate}
+          selectedTemplateKey={selectedTemplateKey}
+          onSelectTemplate={onSelectTemplate}
          previewCount={previewCount}
          previewTitles={previewTitles}
          onPreviewTitlesChange={onPreviewTitlesChange}
@@ -43,6 +43,20 @@ interface Step4TitleSettingsProps {
    style?: Record<string, unknown>
    previewStyle?: React.CSSProperties
  }>
+  /* ── 模板管理 ── */
+  templates?: Array<{
+    key: string
+    label: string
+    emoji?: string
+    isSystem: boolean
+    style: Record<string, unknown>
+  }>
+  onSaveTemplate?: (label: string, style: Record<string, unknown>, emoji?: string) => void
+  onUpdateTemplate?: (key: string, patch: { label?: string; style?: Record<string, unknown>; emoji?: string }) => void
+  onDeleteTemplate?: (key: string) => void
+  onDuplicateTemplate?: (key: string) => void
+  selectedTemplateKey?: string | null
+  onSelectTemplate?: (key: string | null) => void
  /* ── 批量生成（#1677）── */
  /** 生成数量 */
  previewCount?: number
@@ -95,6 +109,13 @@ const Step4TitleSettings: React.FC<Step4TitleSettingsProps> = (props) => {
    onUpdateStyle,
    activePreset,
    titlePresets,
+    templates,
+    onSaveTemplate,
+    onUpdateTemplate,
+    onDeleteTemplate,
+    onDuplicateTemplate,
+    selectedTemplateKey,
+    onSelectTemplate,
    previewCount = 1,
    previewTitles,
    onPreviewTitlesChange,
@@ -300,6 +321,13 @@ const Step4TitleSettings: React.FC<Step4TitleSettingsProps> = (props) => {
        titlePresets={titlePresets}
        POSITION_OPTIONS={POSITION_OPTIONS}
        FONT_OPTIONS={FONT_OPTIONS}
+        templates={templates}
+        onSaveTemplate={onSaveTemplate}
+        onUpdateTemplate={onUpdateTemplate}
+        onDeleteTemplate={onDeleteTemplate}
+        onDuplicateTemplate={onDuplicateTemplate}
+        selectedTemplateKey={selectedTemplateKey}
+        onSelectTemplate={onSelectTemplate}
      />
    </div>
  )
@@ -12,7 +12,7 @@
 */
 import React, { useEffect, useRef } from "react"
 import type { TitleSettings } from "../../types"
-import { getFontFamily } from "../../constants"
+import { getFontFamily } from "@/components/title/constants"

 interface Props {
  settings: TitleSettings
@@ -4,7 +4,7 @@
 * 避免 -webkit-text-stroke 在 Chromium 中吞掉填充色的问题
 */
 import React from "react"
-import { getFontFamily } from "../../constants"
+import { getFontFamily } from "@/components/title/constants"

 interface TitlePresetItem {
  key: string
@@ -442,3 +442,190 @@
  font-size: 12px !important;
  padding: 6px 8px !important;
 }
+
+/* ============================================================
+   #模板管理系统 — 模板卡片网格样式
+   ============================================================ */
+
+/* 模板头部（标签 + 新建按钮） */
+.ts-template-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+}
+.ts-template-header label {
+  margin-bottom: 0;
+}
+.ts-new-template-btn {
+  padding: 4px 12px;
+  font-size: 12px;
+  font-weight: 500;
+  color: #7c3aed;
+  background: #faf5ff;
+  border: 1px solid #ddd6fe;
+  border-radius: 6px;
+  cursor: pointer;
+  transition: 0.15s;
+}
+.ts-new-template-btn:hover {
+  background: #ede9fe;
+  border-color: #7c3aed;
+}
+
+/* 模板网格：4列 */
+.ts-template-grid {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 8px;
+}
+
+/* 模板卡片 */
+.ts-template-card {
+  position: relative;
+  border: 2px solid #e5e7eb;
+  border-radius: 8px;
+  background: #fff;
+  overflow: hidden;
+  transition: 0.15s;
+}
+.ts-template-card:hover {
+  border-color: #c4b5fd;
+  box-shadow: 0 2px 8px rgba(124, 58, 237, 0.1);
+}
+.ts-template-card.active {
+  border-color: #7c3aed;
+  background: #faf5ff;
+  box-shadow: 0 0 0 1px #7c3aed;
+}
+
+/* 预览按钮 */
+.ts-template-preview-btn {
+  display: block;
+  width: 100%;
+  padding: 0;
+  border: none;
+  background: none;
+  cursor: pointer;
+}
+
+/* 预览 canvas 容器 */
+.ts-template-canvas-wrap {
+  height: 48px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #0f172a;
+  overflow: hidden;
+}
+.ts-template-canvas-wrap canvas {
+  max-width: 100%;
+  max-height: 100%;
+}
+
+/* 标签行 */
+.ts-template-label-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 4px 6px;
+  gap: 4px;
+}
+.ts-template-name {
+  font-size: 10px;
+  color: #4b5563;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex: 1;
+}
+.ts-template-tag {
+  font-size: 9px;
+  padding: 1px 4px;
+  border-radius: 3px;
+  flex-shrink: 0;
+}
+.ts-template-tag.system {
+  background: #f3f4f6;
+  color: #6b7280;
+}
+.ts-template-tag.user {
+  background: #ede9fe;
+  color: #7c3aed;
+}
+
+/* 操作按钮 */
+.ts-template-actions {
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  display: flex;
+  justify-content: center;
+  gap: 2px;
+  padding: 3px 4px;
+  background: rgba(255, 255, 255, 0.95);
+  border-top: 1px solid #e5e7eb;
+  z-index: 2;
+}
+.ts-template-action-btn {
+  padding: 2px 6px;
+  font-size: 10px;
+  border: 1px solid #d1d5db;
+  border-radius: 4px;
+  background: #fff;
+  cursor: pointer;
+  color: #374151;
+  transition: 0.1s;
+}
+.ts-template-action-btn:hover {
+  border-color: #7c3aed;
+  color: #7c3aed;
+}
+.ts-template-action-delete:hover {
+  border-color: #ef4444;
+  color: #ef4444;
+}
+
+/* 编辑模式横幅 */
+.ts-editing-banner {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  margin-bottom: 10px;
+  background: #ede9fe;
+  border: 1px solid #c4b5fd;
+  border-radius: 8px;
+  font-size: 13px;
+  color: #5b21b6;
+}
+.ts-editing-save-btn {
+  padding: 4px 12px;
+  font-size: 12px;
+  font-weight: 500;
+  color: #fff;
+  background: #7c3aed;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  margin-left: auto;
+  transition: 0.15s;
+}
+.ts-editing-save-btn:hover {
+  background: #6d28d9;
+}
+.ts-editing-cancel-btn {
+  padding: 4px 12px;
+  font-size: 12px;
+  color: #6b7280;
+  background: #fff;
+  border: 1px solid #d1d5db;
+  border-radius: 6px;
+  cursor: pointer;
+  transition: 0.15s;
+}
+.ts-editing-cancel-btn:hover {
+  border-color: #9ca3af;
+  color: #374151;
+}
@@ -1,17 +1,21 @@
 /**
- * 标题样式设置面板（#2001 升级）
+ * 标题样式设置面板（#2001 升级 + #模板管理系统）
 *
 * P0：描边宽度滑块 / 描边颜色选择器 / 每行最大字符数 / 行距+顶部边距 /
- *     4款爆款字体 / 抖音爆款黄预设
- * P1：阴影参数化 / 背景色块 / Canvas 实时迷你预览 /
- *     封面独立标题配置入口
+ *     模板卡片网格 / 新建模板 / 编辑模板
 *
 * 向后兼容：旧的 onToggleBold/Italic/Stroke/Shadow/onUpdatePosition/onUpdateFont/
 * onUpdateSize/onApplyPreset props 全部保留；新增字段通过 onUpdateStyle 统一回写。
+ *
+ * Bug修复（#模板管理系统）：
+ * - Bug1：预设选中后手动改参数自动脱离预设
+ * - Bug2：预设卡片预览字号统一（canvas 固定宽度渲染）
+ * - Bug3：描边参数始终可手动调整（预设只给初始值）
 */
-import React, { useState } from "react"
-import { Tabs } from "antd"
+import React, { useState, useMemo } from "react"
+import { Tabs, Modal, Input, Button } from "antd"
 import type { TitleSettings } from "../../types"
+import type { TitleStyleConfig } from "@/components/title/types"
 import {
  FONT_OPTIONS as NEW_FONT_OPTIONS,
  TITLE_PRESETS,
@@ -19,10 +23,12 @@ import {
  STROKE_COLOR_PALETTE,
  BG_COLOR_PALETTE,
 } from "@/components/title/constants"
+import type { TitleTemplate } from "../../hooks/useStep4Title/useTitleTemplates"

 import TitleMiniPreview from "./TitleMiniPreview"
 import "./TitleStylePanel.css"

+/* ── 类型定义 ── */
 interface PositionOption {
  value: string
  label: string
@@ -57,9 +63,27 @@ interface TitleStylePanelProps {
  showCoverToggle?: boolean
  /** 画布预览宽度（默认 200） */
  previewWidth?: number
+  /* ── 模板管理新增 ── */
+  /** 所有模板列表（系统 + 用户） */
+  templates?: TitleTemplate[]
+  /** 保存模板 */
+  onSaveTemplate?: (label: string, style: Partial<TitleStyleConfig>, emoji?: string) => TitleTemplate | void
+  /** 更新模板 */
+  onUpdateTemplate?: (key: string, patch: { label?: string; style?: Partial<TitleStyleConfig>; emoji?: string }) => void
+  /** 删除模板 */
+  onDeleteTemplate?: (key: string) => void
+  /** 复制模板 */
+  onDuplicateTemplate?: (key: string) => void
+  /** 当前选中的模板 key（编辑模式） */
+  selectedTemplateKey?: string | null
+  /** 选中模板 */
+  onSelectTemplate?: (key: string | null) => void
 }

-/* ── 通用 Slider + Label 行 ── */
+/* ── 统一预览字号：所有预设卡片用相同 canvas 宽度渲染 ─ */
+const PREVIEW_CANVAS_WIDTH = 120
+
+/* ── SliderRow ── */
 const SliderRow: React.FC<{
  label: string
  value: number
@@ -89,7 +113,7 @@ const SliderRow: React.FC<{
  </div>
 )

-/* ── 色板 + 自定义颜色选择 ── */
+/* ── ColorPicker ── */
 const ColorPicker: React.FC<{
  label?: string
  value: string
@@ -140,40 +164,172 @@ const ColorPicker: React.FC<{
  )
 }

-/* ── 预设网格（含爆款黄，10 个 + 迷你 Canvas 缩略） ── */
-const PresetGrid: React.FC<{
-  activePreset: string | null
-  onApply: (key: string) => void
-  settings: TitleSettings
-}> = ({ activePreset, onApply, settings }) => {
+/* ── 保存模板弹窗 ── */
+const SaveTemplateDialog: React.FC<{
+  open: boolean
+  isEdit: boolean
+  currentLabel?: string
+  onCancel: () => void
+  onSave: (label: string, emoji: string) => void
+}> = ({ open, isEdit, currentLabel = "", onCancel, onSave }) => {
+  const [label, setLabel] = useState(currentLabel)
+  const [emoji, setEmoji] = useState("")
+
+  React.useEffect(() => {
+    if (open) {
+      setLabel(currentLabel)
+      setEmoji("")
+    }
+  }, [open, currentLabel])
+
+  const handleSave = () => {
+    if (!label.trim()) return
+    onSave(label.trim(), emoji.trim())
+  }
+
  return (
-    <div className="ts-presets-grid">
-      {TITLE_PRESETS.map((p) => {
-        const isActive = activePreset === p.key
-        // 合并当前 style 与 preset.style 用于预览（仅预览时覆盖）
-        const previewStyle: TitleSettings = { ...settings, ...(p.style as Partial<TitleSettings>) }
+    <Modal
+      title={isEdit ? "编辑模板" : "保存模板"}
+      open={open}
+      onCancel={onCancel}
+      onOk={handleSave}
+      okText="保存"
+      cancelText="取消"
+      okButtonProps={{ disabled: !label.trim() }}
+    >
+      <div style={{ marginBottom: 16 }}>
+        <label style={{ display: "block", marginBottom: 6, fontWeight: 500 }}>模板名称</label>
+        <Input
+          placeholder="请输入模板名称"
+          value={label}
+          onChange={(e) => setLabel(e.target.value)}
+          maxLength={20}
+        />
+      </div>
+      <div>
+        <label style={{ display: "block", marginBottom: 6, fontWeight: 500 }}>
+          模板图标（可选）
+        </label>
+        <Input
+          placeholder="输入 emoji，如 🔥"
+          value={emoji}
+          onChange={(e) => setEmoji(e.target.value)}
+          maxLength={4}
+        />
+      </div>
+      <div style={{ marginTop: 16, fontSize: 12, color: "#9ca3af", lineHeight: 1.6 }}>
+        <p style={{ margin: "0 0 4px" }}>保存内容包括：</p>
+        <ul style={{ margin: 0, paddingLeft: 20 }}>
+          <li>字体、字号、字色、加粗、斜体</li>
+          <li>描边开关、描边宽度、描边颜色</li>
+          <li>阴影开关及参数</li>
+          <li>背景色块及参数</li>
+          <li>排版参数（行距、行字符数等）</li>
+        </ul>
+      </div>
+    </Modal>
+  )
+}
+
+/* ── 模板卡片网格（替代旧 PresetGrid） ─ */
+const TemplateGrid: React.FC<{
+  templates: TitleTemplate[]
+  activeKey: string | null
+  onApply: (key: string) => void
+  onEdit: (key: string) => void
+  onCopy: (key: string) => void
+  onDelete: (key: string) => void
+  currentSettings: TitleSettings
+  hoveredKey: string | null
+  onHover: (key: string | null) => void
+}> = ({ templates, activeKey, onApply, onEdit, onCopy, onDelete, currentSettings, hoveredKey, onHover }) => {
+  return (
+    <div className="ts-template-grid">
+      {templates.map((t) => {
+        const isActive = activeKey === t.key
+        const isHovered = hoveredKey === t.key
+        // 预览用：合并当前设置与模板样式
+        const previewSettings: TitleSettings = {
+          ...currentSettings,
+          ...(t.style as Partial<TitleSettings>),
+        }
        return (
-          <button
-            key={p.key}
-            type="button"
-            className={`ts-preset-card${isActive ? " active" : ""}`}
-            onClick={() => onApply(p.key)}
-            title={p.label}
+          <div
+            key={t.key}
+            className={`ts-template-card${isActive ? " active" : ""}`}
+            onMouseEnter={() => onHover(t.key)}
+            onMouseLeave={() => onHover(null)}
          >
-            <div className="ts-preset-preview">
-              <TitleMiniPreview settings={previewStyle} width={100} sampleText="标题" />
+            {/* 预览区 */}
+            <button
+              type="button"
+              className="ts-template-preview-btn"
+              onClick={() => onApply(t.key)}
+              title={t.label}
+            >
+              <div className="ts-template-canvas-wrap">
+                <TitleMiniPreview
+                  settings={previewSettings}
+                  width={PREVIEW_CANVAS_WIDTH}
+                  sampleText="标题"
+                />
+              </div>
+            </button>
+            {/* 标签行 */}
+            <div className="ts-template-label-row">
+              <span className="ts-template-name">{t.emoji} {t.label}</span>
+              <span className={`ts-template-tag ${t.isSystem ? "system" : "user"}`}>
+                {t.isSystem ? "系统" : "自定义"}
+              </span>
            </div>
-            <div className="ts-preset-meta">
-              <span className="ts-preset-emoji">{p.emoji}</span>
-              <span className="ts-preset-label">{p.label}</span>
-            </div>
-          </button>
+            {/* 操作按钮（hover 显示，系统预设不显示删除） */}
+            {isHovered && (
+              <div className="ts-template-actions">
+                <button
+                  type="button"
+                  className="ts-template-action-btn"
+                  onClick={(e) => {
+                    e.stopPropagation()
+                    onEdit(t.key)
+                  }}
+                  title="编辑"
+                >
+                  编辑
+                </button>
+                <button
+                  type="button"
+                  className="ts-template-action-btn"
+                  onClick={(e) => {
+                    e.stopPropagation()
+                    onCopy(t.key)
+                  }}
+                  title="复制"
+                >
+                  复制
+                </button>
+                {!t.isSystem && (
+                  <button
+                    type="button"
+                    className="ts-template-action-btn ts-template-action-delete"
+                    onClick={(e) => {
+                      e.stopPropagation()
+                      onDelete(t.key)
+                    }}
+                    title="删除"
+                  >
+                    删除
+                  </button>
+                )}
+              </div>
+            )}
+          </div>
        )
      })}
    </div>
  )
 }

+/* ── 主面板 ── */
 const TitleStylePanel: React.FC<TitleStylePanelProps> = ({
  settings,
  onUpdatePosition,
@@ -190,16 +346,130 @@ const TitleStylePanel: React.FC<TitleStylePanelProps> = ({
  showCoverToggle = false,
  previewWidth = 220,
  onUpdateStyle,
+  /* 模板管理 */
+  templates = [],
+  onSaveTemplate,
+  onUpdateTemplate,
+  onDeleteTemplate,
+  onDuplicateTemplate,
+  selectedTemplateKey,
+  onSelectTemplate,
 }) => {
  const upd = (patch: Partial<TitleSettings>) => {
    onUpdateStyle?.(patch)
  }

-  /* 封面独立标题切换 */
  const [coverOpen, setCoverOpen] = useState(!!settings.coverTitle)

+  /* ── 模板管理状态 ── */
+  const [saveDialogOpen, setSaveDialogOpen] = useState(false)
+  const [saveDialogEdit, setSaveDialogEdit] = useState(false)
+  const [saveDialogKey, setSaveDialogKey] = useState<string | null>(null)
+  const [hoveredTemplateKey, setHoveredTemplateKey] = useState<string | null>(null)
+
+  // 编辑模板：选择某个模板进入编辑模式，修改参数后保存
+  const [editingTemplateKey, setEditingTemplateKey] = useState<string | null>(null)
+
+  const handleNewTemplate = () => {
+    setSaveDialogEdit(false)
+    setSaveDialogKey(null)
+    setSaveDialogOpen(true)
+  }
+
+  const handleEditTemplate = (key: string) => {
+    setEditingTemplateKey(key)
+    setSaveDialogEdit(true)
+    setSaveDialogKey(key)
+    // 应用模板样式到当前设置
+    const tmpl = templates.find((t) => t.key === key)
+    if (tmpl) {
+      onApplyPreset(key)
+    }
+  }
+
+  const handleSaveDialog = (label: string, emoji: string) => {
+    // 将当前设置转为 TitleStyleConfig 格式
+    const style: Partial<TitleStyleConfig> = {
+      font: settings.font,
+      size: settings.size,
+      color: settings.color,
+      bold: settings.bold,
+      italic: settings.italic,
+      stroke: settings.stroke,
+      stroke_width: settings.strokeWidth,
+      stroke_color: settings.strokeColor,
+      shadow: settings.shadow,
+      shadow_offset_x: settings.shadowOffsetX,
+      shadow_offset_y: settings.shadowOffsetY,
+      shadow_blur: settings.shadowBlur,
+      shadow_color: settings.shadowColor,
+      bg_enabled: settings.bgEnabled,
+      bg_color: settings.bgColor,
+      bg_padding: settings.bgPadding,
+      bg_radius: settings.bgRadius,
+      line_height: settings.lineHeight,
+      max_chars_per_line: settings.maxCharsPerLine,
+    }
+
+    if (saveDialogEdit && saveDialogKey && onUpdateTemplate) {
+      onUpdateTemplate(saveDialogKey, { label, style, emoji: emoji || undefined })
+    } else if (onSaveTemplate) {
+      onSaveTemplate(label, style, emoji || undefined)
+    }
+    setSaveDialogOpen(false)
+    setEditingTemplateKey(null)
+    setSaveDialogKey(null)
+  }
+
+  const handleDeleteTemplate = (key: string) => {
+    if (onDeleteTemplate) {
+      onDeleteTemplate(key)
+    }
+  }
+
+  const handleCopyTemplate = (key: string) => {
+    if (onDuplicateTemplate) {
+      onDuplicateTemplate(key)
+    }
+  }
+
+  const handleApplyTemplate = (key: string) => {
+    onApplyPreset(key)
+    onSelectTemplate?.(key)
+    setEditingTemplateKey(null)
+  }
+
+  // 编辑模式提示
+  const isEditing = editingTemplateKey !== null
+  const editingTemplate = editingTemplateKey ? templates.find((t) => t.key === editingTemplateKey) : null
+
  return (
    <div className="xx-title-style-section ts-panel">
+      {/* 编辑模式提示 */}
+      {isEditing && editingTemplate && (
+        <div className="ts-editing-banner">
+          <span>正在编辑：{editingTemplate.label}</span>
+          <button
+            type="button"
+            className="ts-editing-save-btn"
+            onClick={() => {
+              setSaveDialogEdit(true)
+              setSaveDialogKey(editingTemplateKey)
+              setSaveDialogOpen(true)
+            }}
+          >
+            保存模板
+          </button>
+          <button
+            type="button"
+            className="ts-editing-cancel-btn"
+            onClick={() => setEditingTemplateKey(null)}
+          >
+            取消编辑
+          </button>
+        </div>
+      )}
+
      {/* 实时迷你预览 */}
      <div className="ts-preview-wrap">
        <TitleMiniPreview
@@ -209,12 +479,28 @@ const TitleStylePanel: React.FC<TitleStylePanelProps> = ({
        />
      </div>

-      {/* 预设样式（10个，含抖音爆款黄） */}
+      {/* 模板管理区域 */}
      <div className="ts-form-field">
-        <label>爆款预设</label>
-        <PresetGrid activePreset={activePreset} onApply={onApplyPreset} settings={settings} />
+        <div className="ts-template-header">
+          <label style={{ margin: 0 }}>标题模板</label>
+          <button type="button" className="ts-new-template-btn" onClick={handleNewTemplate}>
+            + 新建模板
+          </button>
+        </div>
+        <TemplateGrid
+          templates={templates.length > 0 ? templates : []}
+          activeKey={activePreset}
+          onApply={handleApplyTemplate}
+          onEdit={handleEditTemplate}
+          onCopy={handleCopyTemplate}
+          onDelete={handleDeleteTemplate}
+          currentSettings={settings}
+          hoveredKey={hoveredTemplateKey}
+          onHover={setHoveredTemplateKey}
+        />
      </div>

+      {/* 基础参数面板 */}
      <Tabs
        size="small"
        defaultActiveKey="basic"
@@ -224,7 +510,6 @@ const TitleStylePanel: React.FC<TitleStylePanelProps> = ({
            label: "基础",
            children: (
              <>
-                {/* 位置 + 字体 */}
                <div className="ts-row-2">
                  <div className="ts-form-field ts-half">
                    <label>位置</label>
@@ -249,7 +534,7 @@ const TitleStylePanel: React.FC<TitleStylePanelProps> = ({
                    >
                      {NEW_FONT_OPTIONS.map((f) => (
                        <option key={f.value} value={f.value}>
-                          {f.tag === "hot" ? "🔥 " : f.tag === "new" ? "🆕 " : ""}
+                          {f.tag === "hot" ? " " : f.tag === "new" ? "🆕 " : ""}
                          {f.label}
                        </option>
                      ))}
@@ -265,7 +550,6 @@ const TitleStylePanel: React.FC<TitleStylePanelProps> = ({
                  onChange={onUpdateSize}
                />

-                {/* 样式按钮 */}
                <div className="ts-form-field">
                  <label>样式</label>
                  <div className="ts-style-btns">
@@ -288,7 +572,6 @@ const TitleStylePanel: React.FC<TitleStylePanelProps> = ({
                      className={`ts-style-btn${settings.stroke ? " active" : ""}`}
                      onClick={() => {
                        onToggleStroke()
-                        // 如果之前 strokeWidth 为 0，启用时给个默认值
                        if (!settings.stroke && (settings.strokeWidth ?? 0) < 2) {
                          upd({ strokeWidth: 4 })
                        }
@@ -318,7 +601,6 @@ const TitleStylePanel: React.FC<TitleStylePanelProps> = ({
                  </div>
                </div>

-                {/* 字色 */}
                <ColorPicker
                  label="字色"
                  value={settings.color}
@@ -531,6 +813,19 @@ const TitleStylePanel: React.FC<TitleStylePanelProps> = ({
            : []),
        ]}
      />
+
+      {/* 保存模板弹窗 */}
+      <SaveTemplateDialog
+        open={saveDialogOpen}
+        isEdit={saveDialogEdit}
+        currentLabel={saveDialogKey ? templates.find((t) => t.key === saveDialogKey)?.label : ""}
+        onCancel={() => {
+          setSaveDialogOpen(false)
+          setSaveDialogEdit(false)
+          setSaveDialogKey(null)
+        }}
+        onSave={handleSaveDialog}
+      />
    </div>
  )
 }
@@ -54,39 +54,8 @@ export const POSITION_OPTIONS = [
  { value: "custom", label: "自定义" },
 ]

-/* ── 标题字体选项（#2001：新增 4 款爆款字体） ── */
-export const FONT_OPTIONS = [
-  "优设标题黑",
-  "阿里普惠体Bold",
-  "抖音美好体",
-  "思源黑体Heavy",
-  "思源黑体",
-  "思源宋体",
-  "苹方",
-  "微软雅黑",
-  "楷体",
-]
-
-/* ── 标题字体 CSS font-family 映射（中文显示名 → 浏览器可识别的字体栈） ── */
-export const FONT_FAMILY_MAP: Record<string, string> = {
-  优设标题黑:
-    '"YouSheBiaoTiHei","YouShe Title Black","Source Han Sans SC Heavy","Noto Sans SC","PingFang SC",sans-serif',
-  阿里普惠体Bold:
-    '"Alibaba PuHuiTi Bold","Alibaba PuHuiTi","Source Han Sans SC","PingFang SC",sans-serif',
-  抖音美好体: '"Douyin Sans","DouyinSansBold","Source Han Sans SC Heavy","PingFang SC",sans-serif',
-  思源黑体Heavy:
-    '"Source Han Sans SC Heavy","Noto Sans SC Heavy","Source Han Sans CN Heavy","PingFang SC",sans-serif',
-  思源黑体: '"Source Han Sans SC", "Noto Sans SC", "PingFang SC", "Microsoft YaHei", sans-serif',
-  思源宋体: '"Source Han Serif SC", "Noto Serif SC", "Songti SC", "SimSun", serif',
-  苹方: '"PingFang SC", -apple-system, "Helvetica Neue", sans-serif',
-  PingFang: '"PingFang SC", -apple-system, "Helvetica Neue", sans-serif',
-  微软雅黑: '"Microsoft YaHei", "PingFang SC", sans-serif',
-  楷体: '"KaiTi", "STKaiti", "DFKai-SB", serif',
-}
-
-export function getFontFamily(font: string): string {
-  return FONT_FAMILY_MAP[font] || FONT_FAMILY_MAP["思源黑体"]
-}
+/* ── 标题字体：统一使用公共层定义（#2001） ── */
+export { getFontFamily } from "@/components/title/constants"

 /* ── 标题样式预设 ── */
 export const TITLE_PRESETS = [
@@ -114,6 +114,7 @@ export function useStep4Title({
    aiTitleResults,
    hasGeneratedTitles,
    activePreset: styleUpdaters.activePreset,
+    setActivePreset: styleUpdaters.setActivePreset,
    titlePresets: styleUpdaters.titlePresets,
    // AI 标题操作
    handleGenerateAiTitles,
@@ -132,6 +133,7 @@ export function useStep4Title({
    toggleStroke: styleUpdaters.toggleStroke,
    toggleShadow: styleUpdaters.toggleShadow,
    applyPreset: styleUpdaters.applyPreset,
+    updateStyle: styleUpdaters.updateStyle,
  }
 }

@@ -1,4 +1,4 @@
-import { useCallback, useMemo } from "react"
+import { useCallback, useState } from "react"
 import { TITLE_PRESETS } from "../../constants"
 import { TITLE_PRESETS as NEW_TITLE_PRESETS } from "@/components/title/constants"
 import type { TitleSettings } from "../../types"
@@ -11,28 +11,15 @@ interface UseTitleStyleUpdatersOptions {
 /**
 * 标题样式更新 Hook
 * 封装标题文字、位置、字体、样式等所有设置更新函数
+ *
+ * Bug修复：手动修改参数时自动脱离预设（#模板管理系统）
 */
 export function useTitleStyleUpdaters({
  titleSettings,
  onTitleSettingsChange,
 }: UseTitleStyleUpdatersOptions) {
-  /** 匹配预设：只用 color/bold/italic/stroke/shadow，不再匹配 size */
-  const getActivePreset = (settings: TitleSettings): string | null => {
-    for (const p of TITLE_PRESETS) {
-      if (
-        settings.color === p.style.color &&
-        settings.bold === p.style.bold &&
-        settings.italic === p.style.italic &&
-        settings.stroke === p.style.stroke &&
-        settings.shadow === p.style.shadow
-      ) {
-        return p.key
-      }
-    }
-    return null
-  }
-
-  const activePreset = useMemo(() => getActivePreset(titleSettings), [titleSettings])
+  /** 当前选中的预设 key（手动修改参数时置 null） */
+  const [activePreset, setActivePreset] = useState<string | null>(null)

  const updateTitle = useCallback(
    (title: string) => {
@@ -47,7 +34,6 @@ export function useTitleStyleUpdaters({

  const updatePosition = useCallback(
    (position: string) => {
-      // 切回三档预设时清掉自定义坐标
      onTitleSettingsChange({ ...titleSettings, position, posX: null, posY: null })
    },
    [titleSettings, onTitleSettingsChange],
@@ -61,8 +47,18 @@ export function useTitleStyleUpdaters({
    [titleSettings, onTitleSettingsChange],
  )

+  /** 通用手动更新：自动脱离预设 */
+  const updateStyle = useCallback(
+    (patch: Partial<TitleSettings>) => {
+      setActivePreset(null)
+      onTitleSettingsChange({ ...titleSettings, ...patch })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
  const updateFont = useCallback(
    (font: string) => {
+      setActivePreset(null)
      onTitleSettingsChange({ ...titleSettings, font })
    },
    [titleSettings, onTitleSettingsChange],
@@ -70,6 +66,7 @@ export function useTitleStyleUpdaters({

  const updateSize = useCallback(
    (size: number) => {
+      setActivePreset(null)
      onTitleSettingsChange({ ...titleSettings, size })
    },
    [titleSettings, onTitleSettingsChange],
@@ -77,65 +74,64 @@ export function useTitleStyleUpdaters({

  const updateColor = useCallback(
    (color: string) => {
+      setActivePreset(null)
      onTitleSettingsChange({ ...titleSettings, color })
    },
    [titleSettings, onTitleSettingsChange],
  )

  const toggleBold = useCallback(() => {
+    setActivePreset(null)
    onTitleSettingsChange({ ...titleSettings, bold: !titleSettings.bold })
  }, [titleSettings, onTitleSettingsChange])

  const toggleItalic = useCallback(() => {
+    setActivePreset(null)
    onTitleSettingsChange({ ...titleSettings, italic: !titleSettings.italic })
  }, [titleSettings, onTitleSettingsChange])

  const toggleStroke = useCallback(() => {
+    setActivePreset(null)
    onTitleSettingsChange({ ...titleSettings, stroke: !titleSettings.stroke })
  }, [titleSettings, onTitleSettingsChange])

  const toggleShadow = useCallback(() => {
+    setActivePreset(null)
    onTitleSettingsChange({ ...titleSettings, shadow: !titleSettings.shadow })
  }, [titleSettings, onTitleSettingsChange])

  /** 应用预设（支持新预设细粒度字段） */
  const applyPreset = useCallback(
    (presetKey: string) => {
-      // 优先匹配新预设（10个爆款预设），fallback 旧预设
      const newPreset = NEW_TITLE_PRESETS.find((p) => p.key === presetKey)
      const oldPreset = TITLE_PRESETS.find((p) => p.key === presetKey)
      if (newPreset) {
        onTitleSettingsChange({
          ...titleSettings,
          ...(newPreset.style as Partial<TitleSettings>),
-          // 清除逐行覆盖
          lineOverrides: [],
        })
+        setActivePreset(presetKey)
        return
      }
-      if (!oldPreset) return
-      onTitleSettingsChange({
-        ...titleSettings,
-        color: oldPreset.style.color,
-        bold: oldPreset.style.bold,
-        italic: oldPreset.style.italic,
-        stroke: oldPreset.style.stroke,
-        shadow: oldPreset.style.shadow,
-      })
-    },
-    [titleSettings, onTitleSettingsChange],
-  )
-
-  /** 通用字段更新（patch） */
-  const updateStyle = useCallback(
-    (patch: Partial<TitleSettings>) => {
-      onTitleSettingsChange({ ...titleSettings, ...patch })
+      if (oldPreset) {
+        onTitleSettingsChange({
+          ...titleSettings,
+          color: oldPreset.style.color,
+          bold: oldPreset.style.bold,
+          italic: oldPreset.style.italic,
+          stroke: oldPreset.style.stroke,
+          shadow: oldPreset.style.shadow,
+        })
+        setActivePreset(presetKey)
+      }
    },
    [titleSettings, onTitleSettingsChange],
  )

  return {
    activePreset,
+    setActivePreset,
    titlePresets: NEW_TITLE_PRESETS,
    updateTitle,
    toggleAiAutoSelect,
@@ -0,0 +1,82 @@
+/**
+ * 标题模板管理 Hook
+ * - 系统预设从 TITLE_PRESETS 加载（始终可用）
+ * - 用户自定义模板存 localStorage
+ * - 支持创建、编辑、复制、删除
+ */
+import { useState, useCallback, useEffect } from "react"
+import { TITLE_PRESETS } from "@/components/title/constants"
+import type { TitleStyleConfig } from "@/components/title/types"
+
+const STORAGE_KEY = "xiaoxia-title-templates"
+
+export interface TitleTemplate {
+  key: string
+  label: string
+  emoji?: string
+  isSystem: boolean
+  style: Partial<TitleStyleConfig>
+}
+
+/** 生成唯一模板 key */
+function genTemplateKey(label: string): string {
+  const slug = label
+    .toLowerCase()
+    .replace(/[^\w\u4e00-\u9fff]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_|_$/g, "")
+  return `user_${slug}_${Date.now().toString(36)}`
+}
+
+export function useTitleTemplates() {
+  const [userTemplates, setUserTemplates] = useState<TitleTemplate[]>(() => {
+    try {
+      const raw = localStorage.getItem(STORAGE_KEY)
+      return raw ? JSON.parse(raw) : []
+    } catch {
+      return []
+    }
+  })
+
+  useEffect(() => {
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(userTemplates))
+    } catch {
+      // ignore
+    }
+  }, [userTemplates])
+
+  const allTemplates: TitleTemplate[] = [
+    ...TITLE_PRESETS.map((p) => ({ ...p, isSystem: true })),
+    ...userTemplates,
+  ]
+
+  const saveTemplate = useCallback((label: string, style: Partial<TitleStyleConfig>, emoji?: string) => {
+    const t: TitleTemplate = { key: genTemplateKey(label), label, emoji: emoji || "", isSystem: false, style }
+    setUserTemplates((prev) => [...prev, t])
+    return t
+  }, [])
+
+  const updateTemplate = useCallback((key: string, patch: { label?: string; style?: Partial<TitleStyleConfig>; emoji?: string }) => {
+    setUserTemplates((prev) => prev.map((t) => (t.key === key ? { ...t, ...patch } : t)))
+  }, [])
+
+  const deleteTemplate = useCallback((key: string) => {
+    setUserTemplates((prev) => prev.filter((t) => t.key !== key))
+  }, [])
+
+  const duplicateTemplate = useCallback((key: string) => {
+    setUserTemplates((prev) => {
+      const src = prev.find((t) => t.key === key)
+      if (!src) return prev
+      const dup: TitleTemplate = {
+        ...src,
+        key: genTemplateKey(src.label + "_copy"),
+        label: src.label + " 副本",
+      }
+      return [...prev, dup]
+    })
+  }, [])
+
+  return { allTemplates, saveTemplate, updateTemplate, deleteTemplate, duplicateTemplate }
+}
@@ -108,11 +108,14 @@ def _check_musetalk_health() -> tuple[bool, dict]:
        return False, {"error": str(exc)}


-def _register(task_id: Optional[str] = None) -> bool:
+def _register(task_id: Optional[str] = None) -> tuple[bool, bool]:
    """向服务端注册 / 心跳，附带 GPU 信息。

    推理期间的心跳线程传 task_id：服务端会同步刷新该 processing 任务的
-    last_heartbeat_at，防止长推理被误判超时回收。
+    last_heartbeat_at，防止长推理被误判超时回收。同时服务端会检查该任务
+    是否已被用户取消，若是则返回 cancel_task=True。
+
+    返回 (ok, cancel_task)。
    """
    ok, info = _check_musetalk_health()
    if isinstance(info, dict):
@@ -142,12 +145,14 @@ def _register(task_id: Optional[str] = None) -> bool:
            timeout=15,
        )
        if r.status_code == 200:
-            return True
+            resp_body = r.json()
+            cancel_task = resp_body.get("cancel_task", False)
+            return True, cancel_task
        logger.error("注册/心跳失败: HTTP %d body=%s", r.status_code, r.text[:300])
-        return False
+        return False, False
    except Exception as exc:
        logger.error("注册/心跳异常: %s", exc)
-        return False
+        return False, False


 def _probe_gpu_name() -> str:
@@ -329,6 +334,9 @@ class TaskHeartbeat(threading.Thread):
    期间无法发送，服务端会因任务 last_heartbeat_at 停滞而误判超时回退 pending。
    本线程每 task_heartbeat_interval 秒（默认 30s）POST /gpu/register 并
    携带当前 task_id，让服务端持续续期任务心跳；任务处理结束 stop()。
+
+    同时检测服务端返回的 cancel_task 信号：若为 True，说明用户已取消任务，
+    立即调用 _cancel_musetalk() 终止本地推理，并设置 cancelled 标志供主流程检查。
    """

    def __init__(self, task_id: str, interval: float):
@@ -336,13 +344,21 @@ class TaskHeartbeat(threading.Thread):
        self.task_id = task_id
        self.interval = max(5.0, interval)
        self._stop_event = threading.Event()
+        self.cancelled = False  # 外部可读的取消标志

    def run(self) -> None:
        # 先立即发一次，再按间隔循环（首次心跳失败不影响主流程）
        while not self._stop_event.is_set():
            try:
-                if _register(self.task_id):
+                ok, cancel_task = _register(self.task_id)
+                if ok:
                    logger.debug("任务 %s 心跳已发送", self.task_id)
+                if cancel_task:
+                    logger.warning("任务 %s 已被用户取消，正在终止本地推理...", self.task_id)
+                    self.cancelled = True
+                    _cancel_musetalk()
+                    self._stop_event.set()
+                    return
            except Exception as exc:  # noqa: BLE001
                logger.warning("任务 %s 心跳异常（忽略）: %s", self.task_id, exc)
            self._stop_event.wait(self.interval)
@@ -369,9 +385,17 @@ def _handle_task(task: dict) -> None:
            if not _download(task["video_url"], video_path):
                _report_result(task_id, False, 0.0, "下载人物视频失败")
                return
+            if hb.cancelled:
+                logger.info("任务 %s 在下载阶段被用户取消", task_id)
+                _report_result(task_id, False, 0.0, "用户取消任务")
+                return
            if not _download(task["audio_url"], audio_path):
                _report_result(task_id, False, 0.0, "下载驱动音频失败")
                return
+            if hb.cancelled:
+                logger.info("任务 %s 在下载阶段被用户取消", task_id)
+                _report_result(task_id, False, 0.0, "用户取消任务")
+                return

            # 2. 输入时长前置校验：短视频 MuseTalk 会 division by zero，
            #    直接上报 failed，不浪费 GPU 时间。ffprobe 不可用/读失败（0.0）
@@ -392,12 +416,20 @@ def _handle_task(task: dict) -> None:
            err = ""
            retryable = False
            for attempt in range(Config.task_max_retry + 1):
+                if hb.cancelled:
+                    logger.info("任务 %s 在推理前被用户取消", task_id)
+                    _report_result(task_id, False, 0.0, "用户取消任务")
+                    return
                if attempt > 0:
                    logger.info("任务 %s 第 %d 次重试（瞬时错误）...", task_id, attempt + 1)
                    time.sleep(2)
                success, duration, err, retryable = _call_musetalk(video_path, audio_path, out_path)
                if success or not retryable:
                    break
+            if hb.cancelled:
+                logger.info("任务 %s 被用户取消（推理已终止）", task_id)
+                _report_result(task_id, False, 0.0, "用户取消任务")
+                return
            if not success:
                logger.error("任务 %s 推理失败: %s", task_id, err)
                _report_result(task_id, False, 0.0, err)
@@ -467,7 +499,8 @@ def main() -> int:
            # 心跳
            now = time.time()
            if now - last_heartbeat >= Config.heartbeat_interval:
-                if _register():
+                ok, _ = _register()
+                if ok:
                    last_heartbeat = now

            # 轮询任务
@@ -526,13 +526,12 @@ def _load_musetalk_models():
                        gfpgan_key = "params_ema" if "params_ema" in gfpgan_ckpt else "params"
                        gfpgan_model.load_state_dict(gfpgan_ckpt[gfpgan_key], strict=True)
                        gfpgan_model.eval()
-                        if Config.use_float16:
-                            gfpgan_model = gfpgan_model.half()
+                        # GFPGAN 始终使用 FP32 推理，避免 FP16 色偏导致紫/灰色块
                        gfpgan_model = gfpgan_model.to(device)
                        del gfpgan_ckpt
                        _gfpgan_loaded = True
                        _gfpgan_load_error = None
-                        logger.info("GFPGAN 加载完成 (FP16=%s)", Config.use_float16)
+                        logger.info("GFPGAN 加载完成 (FP32，避免色偏)")
                    else:
                        _gfpgan_loaded = False
                        _gfpgan_load_error = f"模型文件不存在: {gfpgan_path}"
@@ -920,25 +919,30 @@ def _run_inference(
                _ff_proc.stdin.write(ori_frame.tobytes())
                continue

-            # GFPGAN 人脸超分增强
+            # GFPGAN 人脸超分增强（FP32 推理，避免 FP16 色偏）
+            # 色彩通道约定：ori_frame / res_frame / _face_up 均为 BGR（OpenCV 默认）；
+            # GFPGAN 输出用 return_rgb=True 拿到 RGB，再转 BGR，与后续 face_parsing 融合保持一致。
            if gfpgan_enhancer is not None:
                try:
                    _fh, _fw = res_frame_resized.shape[:2]
                    _face_up = cv2.resize(res_frame_resized, (512, 512),
                                          interpolation=cv2.INTER_LANCZOS4)
                    _face_rgb = cv2.cvtColor(_face_up, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0
-                    _face_t = torch.from_numpy(_face_rgb.transpose(2,0,1)).unsqueeze(0)
+                    _face_t = torch.from_numpy(_face_rgb.transpose(2, 0, 1)).unsqueeze(0)
+                    # GFPGAN 始终 FP32，避免 FP16 精度导致色偏；归一化到 [-1, 1]
                    _face_t = ((_face_t - 0.5) / 0.5).to(device)
-                    if Config.use_float16:
-                        _face_t = _face_t.half()
                    with torch.no_grad():
-                        _out = gfpgan_enhancer(_face_t, return_rgb=False, weight=0.5)[0]
-                    _out = _out.squeeze(0).float().cpu().clamp_(-1,1)
-                    _out = ((_out + 1)/2*255).numpy().transpose(1,2,0)
-                    _out_bgr = cv2.cvtColor(_out.astype(np.uint8), cv2.COLOR_RGB2BGR)
+                        _out = gfpgan_enhancer(_face_t, return_rgb=True, weight=0.35)[0]
+                    # 输出 tensor: RGB, [-1, 1] 范围 → clamp → 映射到 [0, 255] uint8
+                    _out = _out.squeeze(0).float().cpu().clamp_(-1.0, 1.0)
+                    _out = ((_out + 1.0) / 2.0 * 255.0).numpy().transpose(1, 2, 0)
+                    _out_rgb = _out.astype(np.uint8)
+                    # RGB → BGR，与 ori_frame 保持一致，确保 face_parsing 融合时通道正确
+                    _out_bgr = cv2.cvtColor(_out_rgb, cv2.COLOR_RGB2BGR)
+
                    res_frame_resized = cv2.resize(_out_bgr, (_fw, _fh),
                                                    interpolation=cv2.INTER_LANCZOS4)
-                    del _face_t, _out, _out_bgr
+                    del _face_t, _out, _out_rgb, _out_bgr
                except Exception as _gfpgan_err:
                    logger.warning("GFPGAN 增强失败（帧 %d），使用原图: %s", i, _gfpgan_err)

@@ -985,7 +989,7 @@ def _run_inference(
    if video_downsampled:
        logger.info("输入视频 %.1f fps，降帧至 %.1f fps 推理后直接输出（不做插帧还原）", original_fps, inference_fps)

-    shutil.copy2(str(final_video), str(output_path))
+    _mux_video_with_audio(final_video, audio_path, output_path)

    try:
        torch.cuda.empty_cache()
@@ -18,6 +18,10 @@ def build_engine(
    pool_timeout: int = 30,
    pool_recycle: int = 3600,
 ):
+    # SQLite 不支持 QueuePool 的 pool_size/max_overflow/pool_timeout，
+    # 传了会在 create_engine 阶段直接 TypeError，这里只对非 SQLite 传连接池参数。
+    if _is_sqlite(database_url):
+        return create_engine(database_url, pool_recycle=pool_recycle)
    return create_engine(
        database_url,
        pool_size=pool_size,
@@ -68,7 +68,9 @@ def test_register_payload_includes_task_id_only_when_provided(worker, monkeypatc

    class _Resp:
        status_code = 200
-        text = ""
+
+        def json(self):
+            return {"worker_id": captured[-1]["worker_id"], "cancel_task": False}

    def _fake_post(url, json=None, headers=None, timeout=None):
        captured.append(json)
@@ -77,7 +79,9 @@ def test_register_payload_includes_task_id_only_when_provided(worker, monkeypatc
    monkeypatch.setattr(worker.requests, "post", _fake_post)
    monkeypatch.setattr(worker, "_check_musetalk_health", lambda: (True, {}))

-    assert worker._register("task-abc") is True
+    _ok, _cancel = worker._register("task-abc")
+    assert _ok is True
+    assert _cancel is False
    assert captured[-1]["task_id"] == "task-abc"
    assert captured[-1]["worker_id"]

@@ -93,7 +97,7 @@ def test_task_heartbeat_thread_sends_and_stops(worker, monkeypatch):

    def _fake_register(task_id=None):
        calls.append(task_id)
-        return True
+        return True, False

    monkeypatch.setattr(worker, "_register", _fake_register)
    hb = worker.TaskHeartbeat("task-hb1", interval=5)
@@ -105,6 +109,50 @@ def test_task_heartbeat_thread_sends_and_stops(worker, monkeypatch):
    assert calls and all(c == "task-hb1" for c in calls)


+def test_task_heartbeat_cancel_calls_musetalk_cancel(worker, monkeypatch):
+    """心跳响应 cancel_task=True → 调 _cancel_musetalk 并设置 cancelled 标志。"""
+    cancel_calls = []
+
+    monkeypatch.setattr(worker, "_register", lambda *a, **k: (True, True))
+    monkeypatch.setattr(worker, "_cancel_musetalk", lambda: cancel_calls.append(1))
+
+    hb = worker.TaskHeartbeat("task-cancel-1", interval=5)
+    hb.start()
+    hb.join(timeout=2)  # 检测到取消后线程自行 return
+    assert not hb.is_alive()
+    assert hb.cancelled is True
+    assert cancel_calls == [1]
+
+
+def test_handle_task_reports_cancelled_after_musetalk_abort(worker, monkeypatch):
+    """推理被 /cancel 终止后，hb.cancelled=True → 上报失败而非重试。"""
+    reports = []
+
+    monkeypatch.setattr(worker, "_register", lambda *a, **k: (True, False))
+    monkeypatch.setattr(worker, "_download", lambda url, path: True)
+    monkeypatch.setattr(worker, "_probe_duration", lambda path: 12.0)
+    # 模拟推理被终止（/inference 返回错误）
+    monkeypatch.setattr(worker, "_call_musetalk", lambda v, a, o: (False, 0.0, "推理被取消", False))
+    monkeypatch.setattr(
+        worker,
+        "_report_result",
+        lambda task_id, success, duration=0.0, error_msg="": reports.append(error_msg) or True,
+    )
+
+    # 让 TaskHeartbeat 在主线程检查时报告已取消
+    orig_hb_init = worker.TaskHeartbeat
+
+    def _hb(task_id, interval):
+        h = orig_hb_init(task_id, interval)
+        h.cancelled = True
+        return h
+
+    monkeypatch.setattr(worker, "TaskHeartbeat", _hb)
+
+    worker._handle_task({"task_id": "t-canceled", "video_url": "u", "audio_url": "u"})
+    assert reports == ["用户取消任务"]
+
+
 # ── 短视频前置拦截 ─────────────────────────────────────────────────


@@ -115,7 +163,7 @@ def test_handle_task_short_video_reports_failed_without_inference(worker, monkey
    audio.write_bytes(b"fake-audio")
    reports = []

-    monkeypatch.setattr(worker, "_register", lambda *a, **k: True)
+    monkeypatch.setattr(worker, "_register", lambda *a, **k: (True, False))
    monkeypatch.setattr(worker, "_download", lambda url, path: True)
    # ffprobe 读出 1.2s → 低于 3s 阈值
    monkeypatch.setattr(worker, "_probe_duration", lambda path: 1.2)
@@ -148,7 +196,7 @@ def test_handle_task_short_video_reports_failed_without_inference(worker, monkey
 def test_handle_task_probe_failure_does_not_block(worker, monkeypatch):
    """ffprobe 不可用（duration=0.0）时不能误杀，应继续推理."""
    reports = []
-    monkeypatch.setattr(worker, "_register", lambda *a, **k: True)
+    monkeypatch.setattr(worker, "_register", lambda *a, **k: (True, False))
    monkeypatch.setattr(worker, "_download", lambda url, path: True)
    monkeypatch.setattr(worker, "_probe_duration", lambda path: 0.0)
    monkeypatch.setattr(
@@ -214,7 +262,7 @@ def test_handle_task_retries_once_for_transient_then_succeeds(worker, monkeypatc
            return False, 0.0, "MuseTalk HTTP 503: busy", True
        return True, 6.5, "", False

-    monkeypatch.setattr(worker, "_register", lambda *a, **k: True)
+    monkeypatch.setattr(worker, "_register", lambda *a, **k: (True, False))
    monkeypatch.setattr(worker, "_download", lambda url, path: True)
    monkeypatch.setattr(worker, "_probe_duration", lambda path: 12.0)
    monkeypatch.setattr(worker, "_call_musetalk", _fake_call)
@@ -239,7 +287,7 @@ def test_handle_task_no_retry_for_deterministic_failure(worker, monkeypatch):
        return False, 0.0, "MuseTalk HTTP 400: bad input", False

    reports = []
-    monkeypatch.setattr(worker, "_register", lambda *a, **k: True)
+    monkeypatch.setattr(worker, "_register", lambda *a, **k: (True, False))
    monkeypatch.setattr(worker, "_download", lambda url, path: True)
    monkeypatch.setattr(worker, "_probe_duration", lambda path: 12.0)
    monkeypatch.setattr(worker, "_call_musetalk", _fake_call)
@@ -0,0 +1,89 @@
+"""GPU Worker 路由单测 — #2009 取消链路.
+
+直接调用路由函数（不经 HTTP 栈），显式注入 svc / _token 以跳过 Depends。
+CI 增量映射: gpu_lipsync.py (route) → test_gpu_lipsync_routes.py
+"""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def _payload(**overrides):
+    from app.schemas.gpu_lipsync import GpuWorkerRegisterRequest
+
+    data = {
+        "worker_id": "w-1",
+        "hostname": "gpu-host",
+        "gpu_name": "RTX3060",
+        "free_vram_mb": 10000,
+        "capabilities": json.dumps({"musetalk": True}),
+    }
+    data.update(overrides)
+    return GpuWorkerRegisterRequest(**data)
+
+
+def test_register_returns_cancel_task_true_when_cancelled():
+    """心跳接口在任务已取消时必须把 cancel_task=True 透传给 Worker."""
+    fake_worker = MagicMock()
+    fake_worker.worker_id = "w-1"
+    fake_worker.hostname = "gpu-host"
+    fake_worker.gpu_name = "RTX3060"
+    fake_worker.free_vram_mb = 10000
+    fake_worker.capabilities = "musetalk"
+    fake_svc = MagicMock()
+    fake_svc.register_worker.return_value = (fake_worker, True)
+
+    from app.api.routes.gpu_lipsync import register_worker as route
+
+    resp = route(_payload(task_id="task-cancelled"), svc=fake_svc, _token="t")
+
+    assert resp.cancel_task is True
+    assert resp.ok is True
+    fake_svc.register_worker.assert_called_once()
+    kwargs = fake_svc.register_worker.call_args.kwargs
+    assert kwargs["task_id"] == "task-cancelled"
+
+
+def test_register_returns_cancel_task_false_normal():
+    """正常心跳 cancel_task=False."""
+    fake_worker = MagicMock()
+    fake_worker.worker_id = "w-1"
+    fake_worker.hostname = "gpu-host"
+    fake_worker.gpu_name = "RTX3060"
+    fake_worker.free_vram_mb = 10000
+    fake_worker.capabilities = "musetalk"
+    fake_svc = MagicMock()
+    fake_svc.register_worker.return_value = (fake_worker, False)
+
+    from app.api.routes.gpu_lipsync import register_worker as route
+
+    resp = route(_payload(), svc=fake_svc, _token="t")
+
+    assert resp.cancel_task is False
+
+
+def test_cancel_route_accepts_processing_status():
+    """cancel 路由允许 processing 状态（GPU 推理中），不再 400。"""
+    fake_job = MagicMock()
+    fake_job.status = "cancelled"
+
+    svc = MagicMock()
+    svc.cancel_job.return_value = fake_job
+
+    current_user = MagicMock()
+    current_user.user.id = "u1"
+
+    from app.api.routes.lipsync import cancel_lipsync_job as route
+
+    result = route("job-1", current_user, svc)
+
+    svc.cancel_job.assert_called_once_with("job-1", "u1")
+    assert result.status == "cancelled"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-q"])
@@ -173,10 +173,10 @@ def test_timed_out_task_is_redispatched(svc):


 def test_register_worker_creates_then_updates(svc):
-    w = svc.register_worker("w-1", hostname="pc1", gpu_name="RTX2060", free_vram_mb=3500)
+    w, _cancel = svc.register_worker("w-1", hostname="pc1", gpu_name="RTX2060", free_vram_mb=3500)
    assert w.worker_id == "w-1"
    assert w.gpu_name == "RTX2060"
-    w2 = svc.register_worker("w-1", hostname="pc1", gpu_name="RTX2060", free_vram_mb=2000)
+    w2, _cancel2 = svc.register_worker("w-1", hostname="pc1", gpu_name="RTX2060", free_vram_mb=2000)
    assert w2.free_vram_mb == 2000  # 更新
    assert w2.created_at == w.created_at  # 没新建

@@ -195,7 +195,7 @@ def test_register_with_task_id_refreshes_task_heartbeat(svc):
        {"last_heartbeat_at": old_hb - timedelta(seconds=300)}
    )
    svc.db.commit()
-    svc.register_worker("w-1", task_id=t.id)
+    _w, _c = svc.register_worker("w-1", task_id=t.id)
    svc.db.refresh(t)
    assert t.last_heartbeat_at > old_hb
    assert t.status == "processing"  # 心跳不改变状态
@@ -213,7 +213,7 @@ def test_register_task_heartbeat_ignores_finished_or_foreign_task(svc):
    svc.poll_task("w-1")
    done = svc.report_result(t.id, "w-1", success=True, duration_seconds=10.0)
    hb_when_done = done.last_heartbeat_at
-    svc.register_worker("w-1", task_id=t.id)
+    _w, _c = svc.register_worker("w-1", task_id=t.id)
    svc.db.refresh(t)
    assert t.status == "done"
    assert t.last_heartbeat_at == hb_when_done  # 没被改写
@@ -232,17 +232,61 @@ def test_register_task_heartbeat_ignores_finished_or_foreign_task(svc):
        {"last_heartbeat_at": owner_hb - timedelta(seconds=600)}
    )
    svc.db.commit()
-    svc.register_worker("w-1", task_id=t2.id)  # 旧 worker 迟到心跳
+    _w2, _c2 = svc.register_worker("w-1", task_id=t2.id)  # 旧 worker 迟到心跳
    svc.db.refresh(t2)
    assert t2.worker_id == "w-2"
    assert t2.status == "processing"
    assert t2.last_heartbeat_at == owner_hb

    # 场景 3：不存在的 task_id 不报错
-    svc.register_worker("w-1", task_id="nonexistent-id")
+    _wn, _cn = svc.register_worker("w-1", task_id="nonexistent-id")
    assert svc.db.get(GpuLipsyncTaskModel, "nonexistent-id") is None


+def test_register_task_heartbeat_detects_cancelled(svc):
+    """取消链路：任务已 cancelled 时，register 心跳必须返回 cancel_task=True."""
+    t = svc.create_task(video_url="v", audio_url="a")
+    svc.poll_task("w-1")
+    svc.db.refresh(t)
+    # 用户取消：直接把任务置为 cancelled
+    t.status = "cancelled"
+    t.finished_at = datetime.now(UTC)
+    svc.db.commit()
+
+    _w, cancel_task = svc.register_worker("w-1", task_id=t.id)
+    assert cancel_task is True
+    svc.db.refresh(t)
+    assert t.status == "cancelled"  # 心跳不改写已取消状态
+
+
+def test_report_result_cancelled_stays_cancelled(svc):
+    """Worker 终止取消任务后上报失败，report_result 必须保持 cancelled 不回退 pending."""
+    t = svc.create_task(video_url="v", audio_url="a")
+    svc.poll_task("w-1")
+    svc.db.refresh(t)
+    t.status = "cancelled"
+    svc.db.commit()
+
+    result = svc.report_result(t.id, "w-1", success=False, error_msg="推理被终止")
+    assert result.status == "cancelled"
+    assert result.finished_at is not None
+    assert "推理被终止" in (result.error_msg or "")
+
+
+def test_wait_for_result_returns_when_cancelled(svc):
+    """wait_for_result 将 cancelled 视为终态，立即返回，Celery 不回退 MediaKit."""
+    t = svc.create_task(video_url="v", audio_url="a")
+    svc.poll_task("w-1")
+    svc.db.refresh(t)
+    t.status = "cancelled"
+    t.finished_at = datetime.now(UTC)
+    svc.db.commit()
+
+    result = svc.wait_for_result(t.id, timeout_seconds=5, poll_interval=0.1)
+    assert result is not None
+    assert result.status == "cancelled"
+
+
 def test_default_gpu_task_timeout_is_900(svc):
    """#1970 默认超时 300→900，覆盖 RTX2060 长视频推理."""
    assert svc.settings.gpu_task_timeout_seconds == 900
@@ -248,3 +248,41 @@ class TestSignMediaUrl:
        with patch.object(task_mod, "get_shared_storage_service", side_effect=RuntimeError("x")):
            url = "https://own-bucket.oss-cn-beijing.aliyuncs.com/a.wav"
            assert task_mod._sign_media_url(url) == url
+
+
+def test_cancelled_gpu_task_does_not_fallback_mediakit(monkeypatch):
+    """GPU 任务被用户取消 → Celery 任务直接标记 cancelled，不回退 MediaKit。"""
+    job = MagicMock()
+    job.id = "job-1"
+    job.status = "processing"
+    job.mediakit_task_id = "gpu:gpu-task-1"
+
+    gpu_task = MagicMock()
+    gpu_task.status = "cancelled"
+    gpu_task.error_msg = "用户取消"
+
+    fake_gpu_svc = MagicMock()
+    fake_gpu_svc.wait_for_result.return_value = gpu_task
+    gpu_service_cls = MagicMock(return_value=fake_gpu_svc)
+
+    fake_db = MagicMock()
+    fake_db.query.return_value.filter_by.return_value.first.return_value = job
+
+    # 直接替换 sys.modules 里的 gpu_lipsync_service 模块（全量跑时它可能已被
+    # 其他测试换成 MagicMock），保证任务函数内 from...import 一定拿到我们的类；
+    # 并替换 _get_db_session 绕开 worker_app / app.db 两条 import 分支。
+    import sys
+    from types import SimpleNamespace
+
+    fake_mod = SimpleNamespace(GpuLipsyncService=gpu_service_cls)
+    monkeypatch.setitem(sys.modules, "app.services.gpu_lipsync_service", fake_mod)
+    monkeypatch.setattr(task_mod, "_get_db_session", lambda: fake_db)
+    monkeypatch.setattr(task_mod, "logger", MagicMock())
+
+    task_mod.lipsync_gpu_process_async.run("job-1", "u1", "gpu-task-1")
+
+    assert job.status == "cancelled"
+    assert not str(job.mediakit_task_id).startswith("mk-")
+    fake_db.commit.assert_called()
+    fake_gpu_svc.wait_for_result.assert_called_once()
+    gpu_service_cls.assert_called_once_with(fake_db)
@@ -323,3 +323,126 @@ class TestGpuServiceHelpers:
        svc = GpuLipsyncService(db=fake_db)
        fake_db.query.return_value.filter.return_value.first.return_value = None
        assert svc.has_available_worker() is False
+
+
+# ── cancel_job 取消链路 (#2009) ─────────────────────────────────────
+
+
+def _build_sqlite_session():
+    from sqlalchemy import create_engine
+    from sqlalchemy.orm import sessionmaker
+
+    from packages.adapters.sqlalchemy_impl import models as _  # noqa: F401
+    from packages.adapters.sqlalchemy_impl.models import Base
+
+    engine = create_engine("sqlite:///:memory:", future=True)
+    Base.metadata.create_all(engine)
+    Session = sessionmaker(bind=engine, future=True)
+    return Session()
+
+
+def _make_real_job(db, *, status="processing", mediakit_task_id="gpu:gpu-task-1"):
+    import uuid
+
+    from packages.adapters.sqlalchemy_impl.models import LipsyncJobModel
+
+    job = LipsyncJobModel(
+        id=str(uuid.uuid4()),
+        user_id="u1",
+        project_id="p1",
+        video_url="videos/v.mp4",
+        audio_url="audios/a.wav",
+        enable_video_loop=True,
+        mediakit_task_id=mediakit_task_id,
+        status=status,
+    )
+    db.add(job)
+    db.commit()
+    return job
+
+
+def test_cancel_processing_gpu_job_marks_gpu_task_cancelled():
+    """processing 的 GPU job 取消时，关联 GpuLipsyncTask 必须同步置 cancelled."""
+    import uuid
+
+    from packages.adapters.sqlalchemy_impl.models import GpuLipsyncTaskModel
+
+    db = _build_sqlite_session()
+    gpu_task_id = str(uuid.uuid4())
+    gpu_task = GpuLipsyncTaskModel(
+        id=gpu_task_id,
+        video_url="v",
+        audio_url="a",
+        status="processing",
+        worker_id="w-1",
+        attempt=1,
+    )
+    db.add(gpu_task)
+    db.commit()
+
+    job = _make_real_job(db, mediakit_task_id=f"gpu:{gpu_task_id}")
+    from app.services.lipsync_service import LipsyncService
+
+    svc = LipsyncService(db=db, client=MagicMock())
+    result = svc.cancel_job(job.id, "u1")
+
+    assert result.status == "cancelled"
+    db.refresh(gpu_task)
+    assert gpu_task.status == "cancelled"
+    assert gpu_task.error_msg == "用户取消"
+    assert gpu_task.finished_at is not None
+
+
+def test_cancel_processing_gpu_job_skips_non_processing_gpu_task():
+    """GPU task 已不在 processing（如已 done）时，取消 job 不应改它，也不报错."""
+    import uuid
+
+    from packages.adapters.sqlalchemy_impl.models import GpuLipsyncTaskModel
+
+    db = _build_sqlite_session()
+    gpu_task_id = str(uuid.uuid4())
+    gpu_task = GpuLipsyncTaskModel(
+        id=gpu_task_id, video_url="v", audio_url="a", status="done", worker_id="w-1", attempt=1
+    )
+    db.add(gpu_task)
+    db.commit()
+
+    job = _make_real_job(db, mediakit_task_id=f"gpu:{gpu_task_id}")
+    from app.services.lipsync_service import LipsyncService
+
+    svc = LipsyncService(db=db, client=MagicMock())
+    result = svc.cancel_job(job.id, "u1")
+
+    assert result.status == "cancelled"
+    db.refresh(gpu_task)
+    assert gpu_task.status == "done"  # 没被动
+
+
+def test_cancel_processing_non_gpu_job_does_not_touch_gpu_table():
+    """mediakit_task_id 不是 gpu: 前缀（普通 MediaKit 任务）时，不查 GPU task."""
+    db = _build_sqlite_session()
+    job = _make_real_job(db, mediakit_task_id="mk-task-99")
+    from app.services.lipsync_service import LipsyncService
+
+    svc = LipsyncService(db=db, client=MagicMock())
+    result = svc.cancel_job(job.id, "u1")
+    assert result.status == "cancelled"
+
+
+def test_cancel_completed_job_unchanged():
+    """completed 状态不可取消，cancel_job 原样返回."""
+    db = _build_sqlite_session()
+    job = _make_real_job(db, status="completed", mediakit_task_id="gpu:x")
+    from app.services.lipsync_service import LipsyncService
+
+    svc = LipsyncService(db=db, client=MagicMock())
+    result = svc.cancel_job(job.id, "u1")
+    assert result.status == "completed"
+
+
+def test_cancel_job_not_found_returns_none():
+    db = _build_sqlite_session()
+    from app.services.lipsync_service import LipsyncService
+
+    svc = LipsyncService(db=db, client=MagicMock())
+    assert svc.cancel_job("nonexistent", "u1") is None