[refactor] 重构生成能力相关的契约，统一输入/输出 DTO 和供应商配置，简化任务与集成模块的依赖关系

.cursor/rules/jellyfish-code-and-api.mdc

@@ -17,6 +17,9 @@ alwaysApply: true
 - 后端严格区分层职责：
   - `api` 层负责收参、鉴权、响应组织。
   - `service` 层负责业务逻辑、状态流转、数据编排。
+- 生成能力相关的通用契约（输入/输出 DTO、供应商配置等）统一放在 `app/core/contracts`：
+  - `tasks` 仅保留任务封装、分派与执行编排，不定义跨层 DTO。
+  - `integrations` 仅依赖 `contracts`，不依赖 `tasks` 类型模块。
 
 ## 变更同步要求
 

AGENTS.md

@@ -24,6 +24,9 @@
    - 当前真实实现、当前边界、当前状态流转，放 `architecture`。
    - 正在推进或待推进的改造方案、任务拆解、阶段计划，放 `plans`。
    - 操作说明、开发流程、接入方式，放 `guide`。
+9. 生成能力相关的通用契约（输入/输出 DTO、供应商配置等）统一放在 `app/core/contracts`：
+   - `tasks` 仅保留任务封装、分派与执行编排，不定义跨层 DTO。
+   - `integrations` 仅依赖 `contracts`，不依赖 `tasks` 类型模块。
 
 ## 前端页面职责
 

backend/app/core/contracts/__init__.py

@@ -0,0 +1,23 @@
+"""生成任务共享契约导出。"""
+
+from app.core.contracts.image_generation import (
+    ImageGenerationInput,
+    ImageGenerationResult,
+    ImageItem,
+    InputImageRef,
+    ResponseFormat,
+)
+from app.core.contracts.provider import ProviderConfig, ProviderKey
+from app.core.contracts.video_generation import VideoGenerationInput, VideoGenerationResult
+
+__all__ = [
+    "ProviderConfig",
+    "ProviderKey",
+    "VideoGenerationInput",
+    "VideoGenerationResult",
+    "ImageGenerationInput",
+    "ImageGenerationResult",
+    "ImageItem",
+    "InputImageRef",
+    "ResponseFormat",
+]

backend/app/core/contracts/image_generation.py

@@ -1,4 +1,4 @@
-"""图片生成任务：输入输出模型（供 tasks 与 integrations 共用，避免循环导入）。"""
+"""图片生成共享输入输出契约。"""
 
 from __future__ import annotations
 
@@ -6,7 +6,7 @@ from typing import Literal, Optional
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
-from app.core.tasks.provider_types import ProviderKey
+from app.core.contracts.provider import ProviderKey
 
 ResponseFormat = Literal["url", "b64_json"]
 

backend/app/core/contracts/provider.py

@@ -1,4 +1,4 @@
-"""任务执行层供应商公共类型。"""
+"""生成能力共享的供应商类型契约。"""
 
 from __future__ import annotations
 
@@ -10,7 +10,7 @@ ProviderKey = Literal["openai", "volcengine"]
 
 @dataclass(frozen=True, slots=True)
 class ProviderConfig:
-    """任务执行时所需的供应商配置。"""
+    """执行生成任务时需要的供应商配置。"""
 
     provider: ProviderKey
     api_key: str

backend/app/core/contracts/video_generation.py

@@ -1,4 +1,4 @@
-"""视频生成任务：输入输出模型（供 tasks 与 integrations 共用）。"""
+"""视频生成共享输入输出契约。"""
 
 from __future__ import annotations
 
@@ -6,7 +6,7 @@ from typing import Optional
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
-from app.core.tasks.provider_types import ProviderKey
+from app.core.contracts.provider import ProviderKey
 
 
 def _strip_optional_b64(value: str | None) -> str | None:

backend/app/core/integrations/openai/images.py

@@ -11,12 +11,12 @@ from app.core.integrations.http_logging import (
     log_image_http_response,
     safe_body_for_log_openai,
 )
-from app.core.tasks.image_generation_types import (
+from app.core.contracts.image_generation import (
     ImageGenerationInput,
     ImageGenerationResult,
     ImageItem,
 )
-from app.core.tasks.provider_types import ProviderConfig
+from app.core.contracts.provider import ProviderConfig
 
 
 class OpenAIImageApiAdapter:

backend/app/core/integrations/openai/video.py

@@ -5,8 +5,8 @@ from __future__ import annotations
 from typing import Any
 
 from app.core.integrations.openai.video_payload import build_create_video_body
-from app.core.tasks.provider_types import ProviderConfig
-from app.core.tasks.video_generation_types import VideoGenerationInput
+from app.core.contracts.provider import ProviderConfig
+from app.core.contracts.video_generation import VideoGenerationInput
 
 
 class OpenAIVideoApiAdapter:

backend/app/core/integrations/openai/video_payload.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from app.core.tasks.video_generation_types import VideoGenerationInput, _strip_optional_b64
+from app.core.contracts.video_generation import VideoGenerationInput, _strip_optional_b64
 
 
 def to_image_data_url(value: str) -> str:

backend/app/core/integrations/volcengine/images.py

@@ -11,12 +11,12 @@ from app.core.integrations.http_logging import (
     log_image_http_response,
     safe_body_for_log_volcengine_image,
 )
-from app.core.tasks.image_generation_types import (
+from app.core.contracts.image_generation import (
     ImageGenerationInput,
     ImageGenerationResult,
     ImageItem,
 )
-from app.core.tasks.provider_types import ProviderConfig
+from app.core.contracts.provider import ProviderConfig
 
 
 class VolcengineImageApiAdapter:

backend/app/core/integrations/volcengine/video.py

@@ -5,8 +5,8 @@ from __future__ import annotations
 from typing import Any
 
 from app.core.integrations.volcengine.video_payload import build_create_task_body
-from app.core.tasks.provider_types import ProviderConfig
-from app.core.tasks.video_generation_types import VideoGenerationInput
+from app.core.contracts.provider import ProviderConfig
+from app.core.contracts.video_generation import VideoGenerationInput
 
 
 class VolcengineVideoApiAdapter:

backend/app/core/integrations/volcengine/video_payload.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import Any
 
 from app.core.integrations.openai.video_payload import to_image_data_url
-from app.core.tasks.video_generation_types import VideoGenerationInput, _strip_optional_b64
+from app.core.contracts.video_generation import VideoGenerationInput, _strip_optional_b64
 
 
 def volcengine_ratio(size: str | None) -> str:

backend/app/core/tasks/__init__.py

@@ -1,10 +1,10 @@
 """Tasks for the skills runtime."""
 
 from app.core.tasks.image_generation_tasks import ImageGenerationTask
-from app.core.tasks.image_generation_types import ImageGenerationInput, ImageGenerationResult
-from app.core.tasks.provider_types import ProviderConfig, ProviderKey
+from app.core.contracts.image_generation import ImageGenerationInput, ImageGenerationResult
+from app.core.contracts.provider import ProviderConfig, ProviderKey
 from app.core.tasks.video_generation_tasks import VideoGenerationTask
-from app.core.tasks.video_generation_types import VideoGenerationInput, VideoGenerationResult
+from app.core.contracts.video_generation import VideoGenerationInput, VideoGenerationResult
 
 __all__ = [
     "ProviderConfig",

backend/app/core/tasks/image_generation_tasks.py

@@ -10,14 +10,14 @@ from typing import Any, AsyncIterator
 
 from app.core.integrations.openai.images import OpenAIImageApiAdapter
 from app.core.integrations.volcengine.images import VolcengineImageApiAdapter
-from app.core.tasks.image_generation_types import (
+from app.core.contracts.image_generation import (
     ImageGenerationInput,
     ImageGenerationResult,
     ImageItem,
     InputImageRef,
     ResponseFormat,
 )
-from app.core.tasks.provider_types import ProviderConfig
+from app.core.contracts.provider import ProviderConfig
 from app.core.tasks.registry import resolve_task_adapter
 from app.core.task_manager.types import BaseTask
 

backend/app/core/tasks/video_generation_tasks.py

@@ -11,9 +11,9 @@ from typing import Any, AsyncIterator
 
 from app.core.integrations.openai.video import OpenAIVideoApiAdapter
 from app.core.integrations.volcengine.video import VolcengineVideoApiAdapter
-from app.core.tasks.provider_types import ProviderConfig
+from app.core.contracts.provider import ProviderConfig
 from app.core.tasks.registry import resolve_task_adapter
-from app.core.tasks.video_generation_types import VideoGenerationInput, VideoGenerationResult
+from app.core.contracts.video_generation import VideoGenerationInput, VideoGenerationResult
 from app.core.task_manager.types import BaseTask
 
 __all__ = [

backend/app/services/film/generated_video.py

@@ -11,12 +11,9 @@ from app.core import storage
 from app.core.db import async_session_maker
 from app.core.task_manager import SqlAlchemyTaskStore
 from app.core.task_manager.types import TaskStatus
-from app.core.tasks import (
-    ProviderConfig,
-    VideoGenerationInput,
-    VideoGenerationResult,
-    VideoGenerationTask,
-)
+from app.core.contracts.provider import ProviderConfig
+from app.core.contracts.video_generation import VideoGenerationInput, VideoGenerationResult
+from app.core.tasks import VideoGenerationTask
 from app.models.llm import Model, ModelCategoryKey, ModelSettings
 from app.models.task_links import GenerationTaskLink
 from app.models.studio import FileItem, Shot, ShotDetail, ShotFrameType

backend/app/services/studio/image_task_runner.py

@@ -6,7 +6,9 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.core.db import async_session_maker
 from app.core.task_manager import DeliveryMode, SqlAlchemyTaskStore, TaskManager
 from app.core.task_manager.types import TaskStatus
-from app.core.tasks import ImageGenerationInput, ImageGenerationResult, ImageGenerationTask, ProviderConfig
+from app.core.contracts.image_generation import ImageGenerationInput, ImageGenerationResult
+from app.core.contracts.provider import ProviderConfig
+from app.core.tasks import ImageGenerationTask
 from app.models.studio import (
     ActorImage,
     AssetQualityLevel,

backend/app/services/studio/image_tasks.py

@@ -11,7 +11,7 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core import storage
-from app.core.tasks import ProviderConfig
+from app.core.contracts.provider import ProviderConfig
 from app.models.llm import Model, ModelCategoryKey
 from app.models.studio import AssetViewAngle, FileItem, PromptCategory, PromptTemplate, ShotFrameType
 from app.services.llm import get_model_by_category

backend/tests/core/integrations/test_image_adapters.py

@@ -9,8 +9,8 @@ import pytest
 
 from app.core.integrations.openai.images import OpenAIImageApiAdapter
 from app.core.integrations.volcengine.images import VolcengineImageApiAdapter
-from app.core.tasks.image_generation_types import ImageGenerationInput, InputImageRef
-from app.core.tasks.provider_types import ProviderConfig
+from app.core.contracts.image_generation import ImageGenerationInput, InputImageRef
+from app.core.contracts.provider import ProviderConfig
 
 
 def _patch_httpx_client(monkeypatch: pytest.MonkeyPatch, transport: httpx.MockTransport) -> None:

backend/tests/core/integrations/test_video_adapters.py

@@ -9,8 +9,8 @@ import pytest
 
 from app.core.integrations.openai.video import OpenAIVideoApiAdapter
 from app.core.integrations.volcengine.video import VolcengineVideoApiAdapter
-from app.core.tasks.provider_types import ProviderConfig
-from app.core.tasks.video_generation_types import VideoGenerationInput
+from app.core.contracts.provider import ProviderConfig
+from app.core.contracts.video_generation import VideoGenerationInput
 
 
 def _patch_httpx_client(monkeypatch: pytest.MonkeyPatch, transport: httpx.MockTransport) -> None:

site/content/docs/architecture/project-structure.md

@@ -35,6 +35,12 @@ jellyfish/
 - 管理数据库模型、文件存储与任务状态
 - 通过 `chains / services / core.tasks` 接入 AI 能力
 
+## 生成能力分层约束
+
+- 通用生成契约（输入/输出 DTO、供应商配置等）统一放在 `app/core/contracts`。
+- `app/core/tasks` 仅保留任务封装、分派与执行编排，不定义跨层 DTO。
+- `app/core/integrations` 仅实现供应商协议适配，依赖 `contracts`，不依赖 `tasks` 类型模块。
+
 ## 站点职责
 
 - 官网首页与产品介绍