MediaCrawler/mac-agent-os-main/PLANS/reference/DCS_说明书_v2.0_原文.md

# 导演创作系统（Director Creative System, DCS）· 项目开发说明书 v2.0

> **来源**：用户原始设计文档 `~/Documents/导演创作系统（Director.docx`（829 行，2026-10-01 09:48 更新）
> **入库原因**：作为视频工厂的**设计基准**（`PLANS/VIDEO_FACTORY_MASTER.md` 附录 C 即对照本文档）
> **入库时间**：2026-10-01 | 原文由 textutil 从 docx 提取（仅格式变换，内容未改）

---

导演创作系统（Director Creative System, DCS）

项目开发说明书 v2.0

一、项目定位

DCS是一套面向广告导演/制片人的AI视频生产系统。导演用自然语言描述故事，系统自动完成分镜拆解、资产调度、视频生成、特效叠加和后期合成，输出接近真人实拍质感的20-30秒短片。

核心设计原则：

1. 解耦：导演系统、编排系统、能力API、合成后期互相独立，可单独替换。
2. 标准化：所有模块通过统一分镜Schema交互，换模块不改流程。
3. 导演优先：3D角色、特效运镜、产品资产均可由导演在控制台按需调用，不盲目抽卡。
4. 真实感优先：分镜遵循伪纪录片/手机随手拍美学，后期强制走去AI化处理链。
5. 低成本起步：本地零GPU，所有算力走远端API。

二、系统架构

```
┌───────────────────────────────────────────────────────────────────────┐
│ 层0：导演控制台（Appsmith，本地Docker，端口80）                        │
│                                                                       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │分镜编辑  │ │资产库    │ │3D角色    │ │特效库    │ │任务状态  │  │
│  │          │ │          │ │生产      │ │          │ │          │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                             │
│  │成片预览  │ │参数模板  │ │系统设置  │                             │
│  └──────────┘ └──────────┘ └──────────┘                             │
└─────────────────────────────┬─────────────────────────────────────────┘
                              ↓
┌───────────────────────────────────────────────────────────────────────┐
│ 层1：导演层（可替换）                                                  │
│                                                                       │
│  导演系统（当前选型：AI Storyboard Director v5.2）                     │
│  职责：自然语言故事 → 统一分镜Schema (JSON)                           │
│                                                                       │
│  ┌─────────────────────────────────────────────────────────┐         │
│  │ 统一分镜Schema（标准接口）                               │         │
│  │ 所有模块的“普通话”                                      │         │
│  └─────────────────────────────────────────────────────────┘         │
└─────────────────────────────┬─────────────────────────────────────────┘
                              ↓
┌───────────────────────────────────────────────────────────────────────┐
│ 层2：编排层（n8n，本地Docker，端口5678）                              │
│                                                                       │
│  读取分镜Schema → 按type分发 → 调用各API → 收集输出 → 交给合成层     │
│                                                                       │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│  │TTS节点 │ │口播节点│ │动作节点│ │背景节点│ │特效节点│ │3D节点  │ │
│  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │
└─────────────────────────────┬─────────────────────────────────────────┘
                              ↓
┌───────────────────────────────────────────────────────────────────────┐
│ 层3：能力层（全部远端API，可替换）                                     │
│                                                                       │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐│
│ │Fish Audio│ │D-ID/     │ │可灵/     │ │通义万相  │ │RunningHub    ││
│ │TTS       │ │HeyGen    │ │Wan-Anim  │ │背景/空镜 │ │(ComfyUI)     ││
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────────┘│
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐                  │
│ │混元3D    │ │万兴天幕  │ │海螺AI    │ │其他特效  │                  │
│ │角色生成  │ │子弹时间  │ │运镜      │ │          │                  │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘                  │
└─────────────────────────────┬─────────────────────────────────────────┘
                              ↓
┌───────────────────────────────────────────────────────────────────────┐
│ 层4：合成层（FFmpeg，本地）                                            │
│                                                                       │
│  去AI化处理链：轻微模糊 → 胶片颗粒 → 调色 → 帧混合 → 拼接            │
│  输出：成片mp4                                                        │
└───────────────────────────────────────────────────────────────────────┘
```

三、分层职责与模块规范

3.1 层0：导演控制台

部署：Appsmith，本地Docker，端口80。跨平台（macOS/Linux），迁移时导出数据库+环境变量即可。

页面清单：

页面 功能 数据源
分镜编辑 输入故事大纲 → 调用导演系统 → 展示分镜表 → 逐条修改 FastAPI /api/director/generate
资产库 角色/场景/道具/产品/BGM/音效管理 FastAPI /api/assets/*
3D角色生产 上传概念图 → 生成多视图+骨骼绑定 → 存入资产库 混元3D API
特效库 浏览可用特效，查看参数说明，预览示例 FastAPI /api/vfx/list
任务状态 查看n8n任务队列，每条分镜状态 FastAPI /api/task/*
成片预览 按项目分组播放成片 本地文件系统
参数模板 管理各内容类型的模板（广告/日记/短剧） config/templates/
系统设置 API Key管理、提供商切换、去AI化参数 config/providers.yaml

控制台可设置参数：

A. 导演系统配置

· 当前导演系统：下拉选择
· 导演系统API地址
· 默认输出Schema版本

B. 能力提供商配置

模块 可选提供商 切换方式
TTS Fish Audio / ElevenLabs / Qwen3-TTS 下拉 + Key
口播视频 D-ID / HeyGen / 本地LongCat 下拉 + Key
动作视频 可灵 / Wan-Animate-2 / Runway 下拉 + Key
背景/空镜 通义万相 / Sora 2 / 可灵 下拉 + Key
ComfyUI RunningHub / ComfyDeploy / 自建 下拉 + API地址
3D角色 混元3D / Autodesk Flow Studio 下拉 + Key
特效-子弹时间 万兴天幕 / 海螺AI / 可灵 下拉 + Key
特效-运镜 可灵 / 海螺AI 下拉 + Key

C. 去AI化参数（全局默认，可被分镜覆盖）

· 模糊 sigma：默认 0.4
· 胶片颗粒强度：默认 12
· 饱和度偏移：默认 -0.12
· 色温偏移：默认 +0.03
· 帧混合帧数：默认 2

3.2 层1：导演层

职责：接收自然语言故事，输出统一分镜Schema。

可替换性：任何导演系统，只要输出符合统一分镜Schema的JSON，即可接入。若输出格式不同，需写薄适配器转换。

导演系统输入：

```json
{
  "story": "我住院第三天，躺在病床上录了一段……",
  "content_type": "personal_vlog",
  "template_id": "vlog_hospital_001",
  "global_anchors": {
    "character_id": "char_001",
    "location_id": "loc_hospital_302",
    "shooting_style": "documentary_realism"
  }
}
```

当前推荐：AI Storyboard Director v5.2（支持“假设标记”，可强制保留不完美细节）。备选：clip-storyboard-director（4D持久化缓冲区，跨场景一致性最强）。

3.3 层2：编排层（n8n）

部署：本地 Docker，端口 5678。

工作流设计：

```
[Webhook触发]
  → [读取分镜Schema JSON]
  → [循环每条shot]
      → [Switch节点：按type分发]
          ├─ type == "talking_head" → [HTTP Request: 口播API]
          ├─ type == "action" → [HTTP Request: 动作API]
          ├─ type == "background" → [HTTP Request: 背景API]
          ├─ type == "comfyui" → [HTTP Request: RunningHub API]
          ├─ type == "vfx" → [HTTP Request: 特效API]
          └─ type == "3d_character" → [HTTP Request: 混元3D API]
      → [等待任务完成（轮询）]
      → [下载输出片段到本地临时目录]
  → [FFmpeg节点：去AI化处理链]
  → [FFmpeg节点：拼接所有片段]
  → [输出成片mp4到指定目录]
  → [回调控制台更新任务状态]
```

3.4 层3：能力层

统一接口约定：所有能力API返回格式统一为：

```json
{
  "status": "success",
  "video_url": "https://.../output.mp4",
  "duration": 8.0,
  "format": "mp4",
  "error": null
}
```

各模块调用方式：

模块 API 调用方式 关键参数
TTS Fish Audio POST /v1/tts text, voice_id, emotion_tags
口播 D-ID POST /talks source_url, script.audio_url, config.sentiment
动作 可灵 POST /v1/videos image_url, prompt, camera_control
背景 通义万相 POST /api/v1/video prompt, size, seconds
ComfyUI RunningHub POST /api/v1/workflow workflow_id, node_overrides
3D角色 混元3D SubmitHunyuanTo3DProJob Prompt/ImageUrl, ViewImage
子弹时间 万兴天幕 POST /api/v1/vfx image_url, effect_type
运镜 可灵 camera_control参数 pan/tilt/roll/zoom ∈ [-10,10]
运镜 海螺AI 嵌套指令 环绕+降速+焦点锁定

四、统一分镜 Schema（标准接口）

src/schemas.py：

```python
from pydantic import BaseModel, Field
from typing import List, Optional, Literal

class GlobalAnchors(BaseModel):
    character_id: str
    character_3d_id: Optional[str] = None
    location_id: str
    product_id: Optional[str] = None
    wardrobe: str
    lighting_state: str
    camera_lens: str
    shooting_style: str = "documentary_realism"
    consistency_seed: int = 42

class ShotContract(BaseModel):
    shot_size: str
    angle: str
    camera_move: str
    lens_feel: str
    depth_of_field: str
    frame_rate_feel: str

class VFXConfig(BaseModel):
    vfx_id: Optional[str] = None
    vfx_type: Optional[Literal["bullet_time", "orbit", "slow_motion",
                                "focus_lock", "custom"]] = None
    provider: Optional[str] = None
    params: Optional[dict] = None

class ExpressionDetail(BaseModel):
    eyes: Optional[str] = None
    mouth: Optional[str] = None
    brow: Optional[str] = None

class SFX(BaseModel):
    id: str
    at_second: float
    volume: float = 0.4

class AudioConfig(BaseModel):
    voice_volume: float = 1.0
    bgm_id: Optional[str] = None
    bgm_volume: float = 0.15
    bgm_fade_in: float = 1.0
    bgm_fade_out: float = 1.0
    sfx: List[SFX] = []
    audio_cue: Optional[str] = None
    denoise: bool = False

class Subtitle(BaseModel):
    enabled: bool = True
    text: str
    style: str = "手机系统默认"
    position: str = "bottom_center"

class Transition(BaseModel):
    type: Literal["cut", "dissolve", "fade", "wipe"] = "cut"
    duration: float = 0

class Speed(BaseModel):
    factor: float = 1.0
    ramp: Optional[str] = None

class ColorConfig(BaseModel):
    lut: Optional[str] = None
    saturation_offset: float = -0.12
    temperature_shift: float = 0.03

class PostProcess(BaseModel):
    grain_intensity: int = 12
    blur_sigma: float = 0.4
    frame_interpolation: bool = False

class OutputConfig(BaseModel):
    resolution: str = "1080x1920"
    fps: int = 30
    bitrate: str = "8M"

class Shot(BaseModel):
    shot_id: str
    scene_id: str
    duration: float
    type: Literal["talking_head", "action", "background",
                  "comfyui", "vfx", "3d_character"]
    character_id: str
    character_3d_id: Optional[str] = None
    location_id: str
    product_id: Optional[str] = None
    product_focus: bool = False
    product_placement: Optional[str] = None
    props: List[str] = []
    continuity_mode: Literal[
        "fresh_location",
        "previous_frame_continuation",
        "location_reappearance"
    ]
    shot_contract: ShotContract
    vfx: Optional[VFXConfig] = None
    visual_description: str
    text: Optional[str] = None
    sentiment: Optional[str] = None
    expression_detail: Optional[ExpressionDetail] = None
    action: Optional[str] = None
    audio: Optional[AudioConfig] = None
    subtitle: Optional[Subtitle] = None
    transition_in: Transition = Transition()
    transition_out: Transition = Transition()
    speed: Speed = Speed()
    color: ColorConfig = ColorConfig()
    post_process: PostProcess = PostProcess()
    output: OutputConfig = OutputConfig()

class Storyboard(BaseModel):
    project_id: str
    schema_version: str = "2.0"
    global_anchors: GlobalAnchors
    shots: List[Shot]
```

特效参数示例（vfx字段）：

```json
{
  "vfx": {
    "vfx_id": "vfx_bullet_time_01",
    "vfx_type": "bullet_time",
    "provider": "wondershare_tianmu",
    "params": {
      "source_image": "keyframe_01.png",
      "duration": 3.0,
      "freeze_radius": 0.5
    }
  }
}
```

可灵环绕运镜参数（写入shot_contract.camera_move或vfx.params）：

可灵的camera_control支持六种运镜参数，取值范围均为[-10, 10]：horizontal（水平平移）、vertical（垂直平移）、pan（水平摇镜，绕y轴旋转）、tilt（垂直摇镜，绕x轴）、roll（旋转运镜，绕z轴）、zoom（变焦）。同时支持预定义运镜类型：simple、down_back（下移拉远）、forward_up（推进上移）、right_turn_forward（右旋推进）、left_turn_forward（左旋推进）。导演可在控制台选择预定义类型或手动指定六参数组合。

五、资产库规范

目录结构：

```
assets/
├── characters/
│   └── char_001/
│       ├── reference.png
│       ├── reference_side.png
│       ├── reference_full.png
│       ├── lora.safetensors
│       ├── voice_sample.mp3
│       └── meta.json
├── characters_3d/
│   └── char_001_3d/
│       ├── model.glb
│       ├── model.fbx
│       ├── texture/
│       ├── rig_info.json
│       └── meta.json
├── locations/
│   └── loc_hospital_302/
│       ├── reference.png
│       ├── reference_video.mp4
│       └── meta.json
├── real_locations/
│   └── loc_cafe_01/
│       ├── reference_wide.jpg
│       ├── reference_detail.jpg
│       ├── reference_light.jpg
│       ├── reference_video.mp4
│       └── meta.json
├── products/
│   └── prod_skin_cream/
│       ├── reference_front.png
│       ├── reference_angle.png
│       ├── reference_detail.png
│       ├── reference_in_hand.png
│       └── meta.json
├── props/
├── bgm/
├── sfx/
└── vfx_presets/
    ├── bullet_time.yaml
    ├── orbit.yaml
    └── slow_motion.yaml
```

角色3D元数据（meta.json） ：

```json
{
  "id": "char_001_3d",
  "name": "患者A-3D",
  "source_tool": "hunyuan_3d",
  "model_formats": ["glb", "fbx"],
  "rigged": true,
  "rig_type": "humanoid",
  "reference_2d_id": "char_001",
  "consistency_seed": 42,
  "created_at": "2026-10-01"
}
```

产品元数据：

```json
{
  "id": "prod_skin_cream",
  "name": "XX精华面霜",
  "category": "护肤品",
  "must_keep": ["瓶身标签文字", "瓶盖金色边框", "整体配色"],
  "reference_images": {
    "front": "reference_front.png",
    "angle": "reference_angle.png",
    "detail": "reference_detail.png",
    "in_hand": "reference_in_hand.png"
  },
  "consistency_seed": 88
}
```

调用方式：分镜Schema中通过 character_id、character_3d_id、location_id、product_id、props、bgm_id、sfx.id、vfx.vfx_id 引用。n8n根据ID从资产库读取文件路径，注入API请求。

六、3D角色生产模块

功能：导演上传角色概念图，系统自动生成多视图+骨骼绑定3D模型，存入资产库，后续分镜通过 character_3d_id 引用。

调用流程：

```
导演上传正面概念图
    ↓ 控制台 → FastAPI → 混元3D API
混元3D SubmitHunyuanTo3DProJob
    ↓ 传入 Prompt/ImageUrl + ViewImage（多视角图片）
返回 JobId → 轮询 DescribeProfileTo3DJob
    ↓ Status == DONE
获得 File3D（OBJ/GLB格式，含Url和PreviewImageUrl）
    ↓ 下载到 assets/characters_3d/
自动绑定骨骼（混元3D内置AutoRigging）
    ↓ 存入资产库
后续分镜通过 character_3d_id 引用
```

混元3D API关键参数：

· 输入：Prompt（文本）或 ImageUrl（图片URL，有效期24小时）或 ViewImage（多视角图片，支持back/left/right）
· 输出：File3D 数组，包含 Type（文件格式）、Url（文件URL）、PreviewImageUrl（预览图）
· 任务查询：DescribeProfileTo3DJob 返回 Status（WAIT/RUN/FAIL/DONE）和 ResultFile3Ds
· 支持接口：SubmitHunyuanTo3DProJob（专业版）、SubmitHunyuanTo3DRapidJob（极速版）、SubmitAutoRiggingJob（自动骨骼绑定）

七、特效运镜库

7.1 子弹时间

提供商 调用方式 关键参数
万兴天幕 POST /api/v1/vfx image_url, effect_type="bullet_time", duration
可灵 camera_control参数组合 pan ∈ [-10,10], roll ∈ [-10,10], zoom
海螺AI T2V-01-Director模型 内置Bullet Time模板，自动应用时间凝滞+环绕视角
ComfyUI RunningHub工作流 VFX-Bullet Time Effect工作流，两阶段渲染

万兴天幕的“子弹时间”特效支持单张静态图片一键生成影视级动态视频，无需复杂拍摄，且已开放API接口支持MCP协议。海螺AI的T2V-01-Director模型预置了标准化运镜模组，调用内置Bullet Time模板即可触发基础子弹时间逻辑，系统自动应用时间凝滞+环绕视角参数。

7.2 环绕运镜

可灵支持精细的环绕运镜控制。预定义类型中，right_turn_forward 实现“先右旋转后前进”，left_turn_forward 实现“先左旋并前进”。手动模式下可通过 pan 参数实现水平面上的旋转，pan 负值表示绕y轴向左旋转，正值表示向右旋转，取值范围[-10, 10]。

7.3 慢动作/升格

可灵的 frame_rate_feel 参数控制帧率感觉。海螺AI支持嵌套运镜指令，将“环绕+降速+焦点锁定”三重动作按时间顺序嵌套至提示词中。

7.4 特效库的导演操作方式

导演在控制台分镜编辑页面中，每条镜头可展开“特效”面板：

1. 从下拉菜单选择特效类型（子弹时间/环绕/慢动作/焦点锁定/自定义）
2. 选择提供商（万兴天幕/可灵/海螺AI/ComfyUI）
3. 填写参数表单（根据特效类型动态显示）
4. 点击“预览”可调用测试API生成样片
5. 确认后，参数写入分镜Schema的 vfx 字段

八、去AI化处理链

de_ai.py：

```python
class DeAIProcessor:
    def process(self, input_path: str, output_path: str,
                params: PostProcess, color: ColorConfig):
        """
        按顺序执行：
        1. gblur sigma={blur_sigma}               # 消除AI边缘锐利感
        2. noise alls={grain_intensity}:allf=t+u   # 添加真实传感器噪点
        3. eq saturation={1+saturation_offset}     # 饱和度降低
        4. curves=all='0/0 0.5/0.55 1/1'           # S曲线拉反差
        5. colortemperature=temperature=5300        # 色温偏移
        """
```

FFmpeg命令模板：

```bash
ffmpeg -i input.mp4 \
  -vf "gblur=sigma=0.4,noise=alls=12:allf=t+u,\
       eq=saturation=0.88,curves=all='0/0 0.5/0.55 1/1',\
       colortemperature=temperature=5300" \
  -c:v libx264 -preset medium -crf 18 \
  output.mp4
```

拼接：所有处理后的片段用 concat 滤镜拼接，输出最终mp4。

九、FastAPI入口

端点列表：

方法 路径 功能
POST /api/director/generate 输入故事，返回分镜Schema
POST /api/task/submit 提交分镜，返回task_id
GET /api/task/{task_id} 查询任务状态
POST /api/task/{task_id}/retry 重试某镜头
GET /api/assets/characters 列出所有角色
POST /api/assets/characters 上传角色
GET /api/assets/characters_3d 列出3D角色
POST /api/assets/characters_3d/generate 调用混元3D生成角色
GET /api/assets/products 列出产品资产
POST /api/assets/products 上传产品
GET /api/vfx/list 列出可用特效
POST /api/vfx/preview 生成特效样片
GET /api/output/{project_id} 列出成片
GET /api/config/providers 获取当前提供商配置
PUT /api/config/providers 切换提供商

十、部署说明

10.1 本地环境

组件 部署方式 端口 备注
n8n Docker 5678 挂载 ~/dcs/n8n
Appsmith Docker 80 挂载 ~/dcs/appsmith
FastAPI Docker 8000 挂载 assets/output/temp/config
FFmpeg 本地安装 — brew install ffmpeg / apt install ffmpeg
资产库 本地文件夹 — ~/dcs/assets
导演系统 本地脚本或远端API — 包装为FastAPI端点

10.2 Docker Compose

```yaml
version: '3.8'
services:
  n8n:
    image: n8nio/n8n
    ports:
      - "5678:5678"
    volumes:
      - ./n8n:/home/node/.n8n
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=admin

  appsmith:
    image: appsmith/appsmith-ce
    ports:
      - "80:80"
    volumes:
      - ./appsmith:/appsmith-stacks

  api:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./assets:/app/assets
      - ./output:/app/output
      - ./temp:/app/temp
      - ./config:/app/config
    env_file:
      - .env
    depends_on:
      - n8n
```

10.3 远程访问

Tailscale：本地机器和其他设备安装Tailscale，登录同一账号。访问 http://<Tailscale IP>:80（Appsmith）和 http://<Tailscale IP>:5678（n8n）。

十一、环境变量清单

```bash
# ========== 导演系统 ==========
DIRECTOR_TYPE=storyboard_director_v52

# ========== TTS ==========
TTS_PROVIDER=fish_audio
FISH_AUDIO_API_KEY=
FISH_AUDIO_VOICE_ID=
ELEVENLABS_API_KEY=

# ========== 口播视频 ==========
TALKING_HEAD_PROVIDER=d_id
D_ID_API_KEY=
D_ID_AVATAR_ID=
HEYGEN_API_KEY=

# ========== 动作视频 ==========
ACTION_PROVIDER=kling
KLING_API_KEY=
KLING_API_SECRET=
WAN_ANIMATE_API_KEY=

# ========== 背景视频 ==========
BACKGROUND_PROVIDER=tongyi_wanxiang
TONGYI_API_KEY=
SORA_API_KEY=

# ========== ComfyUI ==========
COMFYUI_PROVIDER=runninghub
RUNNINGHUB_API_KEY=
RUNNINGHUB_WORKFLOW_ID=

# ========== 3D角色 ==========
CHARACTER_3D_PROVIDER=hunyuan_3d
HUNYUAN_3D_SECRET_ID=
HUNYUAN_3D_SECRET_KEY=
HUNYUAN_3D_REGION=ap-guangzhou

# ========== 特效 ==========
VFX_BULLET_TIME_PROVIDER=wondershare_tianmu
WONDERSHARE_TIANMU_API_KEY=
VFX_CAMERA_PROVIDER=kling
# 可灵camera_control参数在分镜Schema中动态传入

# ========== 本地路径 ==========
ASSETS_DIR=./assets
OUTPUT_DIR=./output
TEMP_DIR=./temp

# ========== 去AI化默认参数 ==========
DEAI_BLUR_SIGMA=0.4
DEAI_GRAIN_INTENSITY=12
DEAI_SATURATION_OFFSET=-0.12
DEAI_TEMPERATURE_SHIFT=0.03
DEAI_FRAME_BLEND=2

# ========== 服务端口 ==========
API_PORT=8000
N8N_PORT=5678
APPSMITH_PORT=80
```

十二、项目目录结构

```
dcs/
├── README.md
├── docker-compose.yml
├── .env.example
├── requirements.txt
├── start.sh
├── stop.sh
│
├── config/
│   ├── providers.yaml
│   ├── templates/
│   │   ├── vlog_hospital.yaml
│   │   ├── product_ad.yaml
│   │   └── daily_diary.yaml
│   └── post_process.yaml
│
├── assets/
│   ├── characters/
│   ├── characters_3d/
│   ├── locations/
│   ├── real_locations/
│   ├── products/
│   ├── props/
│   ├── bgm/
│   ├── sfx/
│   └── vfx_presets/
│
├── src/
│   ├── main.py
│   ├── schemas.py
│   │
│   ├── director/
│   │   ├── base.py
│   │   ├── storyboard_director.py
│   │   └── adapter.py
│   │
│   ├── orchestrator/
│   │   ├── dispatcher.py
│   │   └── task_manager.py
│   │
│   ├── providers/
│   │   ├── base.py
│   │   ├── tts/
│   │   │   ├── fish_audio.py
│   │   │   └── elevenlabs.py
│   │   ├── talking_head/
│   │   │   ├── d_id.py
│   │   │   └── heygen.py
│   │   ├── action/
│   │   │   ├── kling.py
│   │   │   └── wan_animate.py
│   │   ├── background/
│   │   │   ├── tongyi_wanxiang.py
│   │   │   └── sora.py
│   │   ├── comfyui/
│   │   │   └── runninghub.py
│   │   ├── character_3d/
│   │   │   ├── hunyuan_3d.py
│   │   │   └── flow_studio.py
│   │   └── vfx/
│   │       ├── wondershare_tianmu.py
│   │       ├── hailuo.py
│   │       └── kling_vfx.py
│   │
│   ├── compositor/
│   │   ├── de_ai.py
│   │   ├── concat.py
│   │   └── ffmpeg_utils.py
│   │
│   ├── assets_manager/
│   │   ├── loader.py
│   │   └── validator.py
│   │
│   └── utils/
│       ├── logger.py
│       ├── retry.py
│       └── file_utils.py
│
├── n8n/
│   └── workflow.json
│
├── appsmith/
│   └── application.json
│
├── output/
├── temp/
│
└── tests/
    ├── test_schemas.py
    ├── test_director.py
    ├── test_providers.py
    ├── test_compositor.py
    └── fixtures/
        └── sample_storyboard.json
```

十三、开发路线图

阶段 目标 交付物
阶段1：手动验证 用现有API跑通一条20秒测试片 分镜JSON、测试视频、去AI化参数
阶段2：本地环境 部署n8n + Appsmith + FFmpeg 可访问的控制台
阶段3：导演系统接入 导演系统输出统一Schema 分镜编辑页面可用
阶段4：n8n工作流 串联TTS+口播+背景+FFmpeg 自动生成第一条成片
阶段5：3D角色+特效 接入混元3D + 万兴天幕/可灵运镜 3D角色和特效可用
阶段6：ComfyUI接入 RunningHub API调用 精细控制镜头
阶段7：批量生产 循环分镜表，批量输出 批量任务队列
阶段8：优化迭代 调参、换API、迁移服务器 稳定生产系统

十四、AI编程工具执行清单

```
请按以下顺序生成项目代码：

1. 创建项目根目录结构（mkdir -p dcs/src/...）
2. requirements.txt（fastapi, uvicorn, pydantic, requests, pyyaml, ffmpeg-python）
3. .env.example（按第十一节）
4. src/schemas.py（按第四节）
5. src/director/base.py + storyboard_director.py + adapter.py
6. src/providers/base.py
7. src/providers/tts/fish_audio.py
8. src/providers/talking_head/d_id.py
9. src/providers/action/kling.py（含camera_control参数支持）
10. src/providers/background/tongyi_wanxiang.py
11. src/providers/comfyui/runninghub.py
12. src/providers/character_3d/hunyuan_3d.py
13. src/providers/vfx/wondershare_tianmu.py
14. src/providers/vfx/hailuo.py
15. src/providers/vfx/kling_vfx.py
16. src/compositor/de_ai.py + concat.py + ffmpeg_utils.py
17. src/assets_manager/loader.py + validator.py
18. src/orchestrator/dispatcher.py + task_manager.py
19. src/main.py
20. src/utils/logger.py + retry.py
21. docker-compose.yml
22. start.sh
23. config/providers.yaml + templates/vlog_hospital.yaml
24. tests/test_schemas.py + fixtures/sample_storyboard.json
25. n8n/workflow.json
26. appsmith/application.json（可先留框架）

生成后运行 pytest 确保测试通过。
所有API Key从环境变量读取，不硬编码。
所有异步API调用使用统一的 poll_until_complete 轮询逻辑。
所有Provider继承 BaseProvider，实现 generate(shot, assets) -> dict 方法。
```

十五、需团队手动完成的事项

事项 操作
注册API Fish Audio、D-ID、可灵、通义万相、RunningHub、混元3D、万兴天幕
填写.env 把Key填入.env文件
导入n8n工作流 n8n界面 → Import from File
导入Appsmith应用 Appsmith界面 → Import Application
准备角色参考图 放入assets/characters/char_001/
准备产品参考图 放入assets/products/
在RunningHub搭建工作流 导入社区工作流或手动搭建，发布为API工作流
跑第一条测试 在控制台输入故事，点击生成

十六、导演操作流程（日常使用）

```
1. 打开浏览器 → http://localhost
2. 在分镜编辑页输入故事大纲
3. 选择内容类型（产品广告/个人日记/场景短剧）
4. 选择角色（2D参考图 或 3D绑定模型）
5. 选择场景/场地/产品
6. 点击“生成分镜” → 导演系统返回分镜表
7. 逐条检查/修改 → 可添加特效（子弹时间/环绕运镜等）
8. 点击“提交任务”
9. n8n自动调用各API生成片段
10. FFmpeg自动去AI化+拼接
11. 刷新页面 → 预览成片
12. 不满意 → 修改对应镜头参数 → 重试单条
```