feat(monitor): 抖音 Web 接口客户端 —— 绕开爬虫子进程，直接发 HTTP

移植自 mac-agent-os 的 mediacrawler_adapter：不起子进程、不开页面，用浏览器里那份
登录态直接调抖音 Web 接口。产物键名照抄 store/douyin，所以 ingest 那条链路一个字不用改。

**目前能用的（真环境实测，非推断）**：

    profile/other : 200, 7075 字节  —— 博主主页指标（粉丝/获赞/作品数/昵称）
    aweme/detail  : 200, 45425 字节 —— 单条作品详情（含点赞/评论/收藏/分享）

**目前不能用的：作品列表 `aweme/post`。** 两个互相独立的原因：
  1. 这个接口被抖音单独升级成了真校验：不带 x-tt-argus 回 403「Uifid Not Found」，
     带上 dummy 值回 200 + **空 body**。也就是说「头在不在」骗得过，「真校验」过不了。
     同一套头打 profile/other 和 aweme/detail 都是通的 —— 抖音是挑着接口加保护的，
     挑中的恰好是「批量拉作品列表」这个最敏感的动作。
  2. 改走页面截获也不行：CDP 浏览器打开博主主页会落到「验证码中间页」（当天大量探测的
     代价，过几小时要重测）。

  所以现在的边界是：**已知作品的指标刷新能做，自动发现新作品做不了**。

**排查中控住变量后得到的两条事实**（都写进注释了）：
  · `Accept` / `Accept-Language` / `Referer` 才是主页接口能返回真数据的原因 —— 只有
    UA+client hints+Cookie 时是 200 但仅 121 字节的空壳，补上这三个头变 7074 字节。
    （我先前猜的 sec-ch-ua 不是关键。）
  · 因此 UA 与 client hints 必须**成套地取自同一个浏览器**，所以 BrowserIdentity 一次
    从 CDP 取齐 cookie + UA + hints，而不是各自写死。

「200 + 空 body 必须当场报错」也是刻意写死的：放过去它会在下游变成「这个博主没作品」，
把一次失败伪装成一条正常结果 —— 爬虫那条路正是这么栽的，还被翻译成「账号被封」。

测试 +11：cookie 解析、请求头成套性（含 uifid 缺失/回退）、产物键名与 store 对齐、
以及 _get 的三条失败路径（空 body / 403 带网关原话 / 正常返回）。

mac-agent-os-main/PLANS/VIDEO_FACTORY_MASTER.md

@@ -0,0 +1,526 @@
+# 视频工厂 · 总体架构 v2.0（唯一权威版）
+
+> 创建：2026-10-01 | 状态：**讨论中，待确认后动手**
+> 本文档**替代**此前的 `VIDEO_FACTORY_FRAMEWORK.md` / `VIDEO_FACTORY_ARCHITECTURE.md` / `DCS_VIDEO_FACTORY_PLAN.md`（已归档，见文末）
+> 原则：**流程是主角，能力是零件，资产是原料** —— 三者是引用关系，不是平级菜单
+
+---
+
+## 〇、一句话
+
+> 我进「流程」做一件事（口播 / 短剧 / 导演创作…）→ 流程由若干「节点」串成 → 每个节点是一个「能力」（可换、可配、可调模型）→ 执行后**每一步都能看结果、能改、能重做** → 产物出片。
+> 「资产底座」（角色 / 场景 / 道具 / 产品 / 音色…）是所有流程共用的原料库。
+
+---
+
+## 一、三层模型（核心，先看这张）
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 【流程】Process / Template —— 我要做的一件事                 │
+│   导演创作 · 口播 · 卡点视频 · 角色叙事 · 数字人口播          │
+│   口播+混剪 · 短剧创作 · 人物置换 · …（可扩展、可自建）        │
+│                                                             │
+│   流程 = 节点串（每个节点 = 一个能力 + 该节点的配置）          │
+│   可预制（原来的 6 条）· 可自建（拖节点拼）· 节点可替换        │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ 节点引用能力
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 【能力】Capability —— 解决"一个环节"的最小可执行单元          │
+│   语音合成（文字→音频）· 文生图（文字→图片）· 图生视频         │
+│   音色提炼（音频→音色）· 去AI化 · 拼接/变速/转场 · 字幕        │
+│   分镜规划 · 提示词生成 · 审核门 · 导演编排(元能力)…           │
+│                                                             │
+│   每个能力都有：默认设置 + 可调整参数 + **可选不同大模型**     │
+│   同一个环节可以有多个能力可选（要声音：调库音色 / AI提炼音色 /│
+│   文字直转），节点上可**替换**                                │
+│                                                             │
+│   能力分两类用途：                                            │
+│   ① 产出型（生成资产）：角色生成 / 背景生成 / 音色提炼 …       │
+│   ② 处理型（流程节点）：TTS / 生图 / 生视频 / 合成 …           │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ 产物落入 / 被引用
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 【资产底座】Assets —— 共用原料库（所有流程共享）              │
+│   角色 · 场景/背景 · 道具 · 产品 · 服装 · 音色 · BGM · 音效    │
+│   特效预设 · 风格 · …                                        │
+│   （字段与分类：**待你给出**，见第九节）                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**关键结论**：
+- **导演创作 = 一条流程**（不是独立板块）
+- **人物置换 = 一条流程**（选人→换人），不属于资产
+- **工作流 = 流程本身**（画布是流程的编辑/查看形式）
+- **资产 ≠ 能力**：资产是"原料"（角色图、音色文件），能力是"做事的手"（生成、合成、转换）
+
+---
+
+## 二、前端信息架构（一二级菜单）
+
+```
+🎬 视频工厂                                    ← 一级：大模块
+│
+├─ 📦 资源库                                   ← 二级：基础底座（原料）
+│    ├─ 🧑 角色库           角色筛选/生成/引用
+│    ├─ 🏞️ 场景库           AI 生成场景
+│    ├─ 🏙️ 真实场地库        实拍参考（多角度图 + 视频）
+│    ├─ 🧰 道具库
+│    ├─ 📦 产品库           含 must_keep 必保特征
+│    ├─ 👗 服装库
+│    ├─ 🔊 音色库           音色样本 + 音色 ID（可从音频提炼）
+│    ├─ 🎵 BGM 库
+│    ├─ 💥 音效库
+│    └─ ✨ 特效预设库        子弹时间/环绕/慢动作（参数模板）
+│
+├─ 🎞️ 流程                                     ← 二级：做事入口（模板）
+│    ├─ 🎬 导演创作          ★ 剧本→分镜→逐镜头配置→生成→成片
+│    ├─ 🎭 短剧创作          故事→脚本→角色→分镜→场景→配音→字幕→成片（原有，12 节点）
+│    ├─ 🎙️ 基础口播          脚本→TTS→素材→BGM→输出（原有）
+│    ├─ 🥁 卡点视频          BGM→卡点风格→审核→输出（原有）
+│    ├─ 📖 角色叙事          剧本→改编→角色→策略→生成→旁白→审核→输出（原有）
+│    ├─ 👤 数字人口播        文案→人声→数字人角色→数字人视频（原有）
+│    ├─ 🎞️ 口播+混剪         口播脚本→人声→混合风格→混合视频（原有）
+│    ├─ 🔄 人物置换          选源人物→选目标人物→换人→出片
+│    └─ ➕ 新建流程          从能力库拖节点自建
+│
+├─ 🧩 能力中心                                 ← 二级：能力配置
+│    ├─ ⚙️ 能力配置          25 能力 × 供应商 × 模型 × 参数默认值
+│    ├─ 🔌 供应商管理        各能力可选哪些供应商 + 密钥状态
+│    └─ 🧪 能力试跑          单独测某个能力（不跑整条流程）
+│
+└─ 📊 运营                                     ← 二级：辅助
+     ├─ 📋 生产记录          每次跑流程的记录（产物/耗时/状态）
+     ├─ 💰 费用统计          按能力/供应商/项目统计
+     ├─ 🕐 历史操作          谁在什么时候改了什么
+     └─ ⚙️ 视频工厂设置      全局默认（去AI化参数/输出规格…）
+```
+
+**设计原则**：
+- **一级只有 4 个**：资源库（原料）· 流程（做事）· 能力中心（零件）· 运营（辅助）
+- **二级是具体库/流程**（可继续扩）
+- 你**日常只用「流程」**（选一条 → 画布 → 执行）；资源库/能力中心是**配置时**才去
+
+### 2.1 🧑 角色库细化（重点，按你的要求）
+
+**列表页**
+```
+🔍 [搜索名字/标签]   筛选：类型▾ 用途▾ 项目▾ 标签▾ 有音色☐ 有LoRA☐   排序：最近使用▾
+────────────────────────────────────────────────────────────
+卡片视图（默认）：
+  ┌─────────┐ ┌─────────┐ ┌─────────┐
+  │ [缩略图] │ │ [缩略图] │ │ [缩略图] │
+  │ 阿远     │ │ 小漫     │ │ 患者A    │
+  │ 真人·主角│ │ 动漫·配角│ │ 真人·主角│
+  │ 用过 12 次│ │ 用过 3 次│ │ 用过 8 次│
+  └─────────┘ └─────────┘ └─────────┘
+表格视图：名字 | 类型 | 用途 | 音色 | 参考图数 | 使用次数 | 更新时间
+批量操作：☑多选 → 加标签 / 导出 / 删除
+```
+
+**角色详情页**
+```
+[基本信息]  名字 · 类型(真人/动漫/3D) · 用途(主角/配角/群演) · 项目 · 标签 · 一致性种子
+[参考图]    正面 / 侧面 / 背面 / 全身 / 多角度缩略图（可上传、可生成、可删）
+[服装变体]  服装A(图) · 服装B(图) …（每套可切换）
+[音色]      voice_sample.mp3 ▶ + 音色 ID（可从「音色库」选，或现场提炼）
+[使用记录]  被哪些项目/流程用过（可跳转）
+[操作]      ✏️ 编辑 · 🎨 重新生成参考图 · 📤 导出 · 🔒 锁定（流程中不被覆盖）
+```
+
+**生成入口**（"基础能力"的体现）
+```
+➕ 新建角色 → ① 填描述（性别/年龄/外形/性格）
+            → ② 调「文生图」能力（Kling Grid Method 出 6 张候选）
+            → ③ 选 1 张 → ④ 生成多角度（图生图变体）
+            → ⑤ 补音色（录音上传 / TTS 合成 / 从音色库选）
+            → ⑥ 确认入库
+📤 上传已有参考图（跳过生成）
+```
+
+**在流程里怎么用**（引用机制）
+```
+流程节点「角色」字段 → 点击 → 弹【角色选择器】（带上面的筛选器）
+  选中 → 节点保存 character_id
+  → 执行器按 ID 从资源库取：参考图路径 + 音色文件 → 注入 API 请求
+分镜级：每个镜头可指定不同角色（shot.character_id）
+```
+
+### 2.2 其他资源库（同结构，字段按 DCS 文档第五节）
+
+| 库 | 字段要点 |
+|:--|:--|
+| **场景库** | id / 名字 / 拓扑结构 / 空间锚点 / 光源 / 材质 / 参考图 + 参考视频 |
+| **真实场地库** | 多角度图（wide/detail/light）+ 实拍视频 + 备注 |
+| **道具库** | id / 结构 / 比例 / 可见面 / 持用状态 / 新旧状态 / 参考图 |
+| **产品库** | id / 名字 / **category** / **must_keep[]（必保特征）** / 参考图（front/angle/detail/in_hand）/ 一致性种子 |
+| **服装库** | 关联角色 / 正面背面图 / 材质 · 可挂到角色的"服装变体" |
+| **音色库** | id / 名字 / 样本音频 / 来源（官方库/AI提炼/录制）/ owned_by |
+| **BGM 库 / 音效库** | 标签（情绪/节奏）· 时长 · 版权 |
+| **特效预设库** | 类型（子弹时间/环绕/慢动作/焦点锁定）· 参数模板 · 适用供应商 |
+
+**统一能力**（每个库都有）：
+```
+🔍 搜索 + 筛选 + 排序    📤 上传    ➕ 生成（调对应产出型能力）
+✏️ 编辑    🗑 删除    🔗 查看被哪些流程引用
+```
+
+---
+
+## 三、流程清单与现状（诚实标注）
+
+| # | 流程 | 节点链 | 现状 | 待修 |
+|:--|:--|:--|:--|:--|
+| 1 | **导演创作** | 剧本输入 → 剧本创作(导演系统) → 分镜配置 → 编排执行 → 结果挑选 | 🟡 可跑通（引擎已接），但缺"每步审视/纠正" | 补：分镜后的逐镜头配置面板、执行前预览 |
+| 2 | 基础口播 | 脚本 → TTS → 素材搜索 → BGM → 视频输出 | ❌ **模板在，执行器空转** | 通电（接能力）+ 逐节点审视 |
+| 3 | 卡点视频 | BGM导入 → 卡点风格 → 质量审核 → 视频输出 | ❌ 同上 | 同上 |
+| 4 | 角色叙事 | 剧本→改编→角色→策略→Kling生成→旁白TTS→审核→输出 | ❌ 同上 | 同上 |
+| 5 | 数字人口播 | 文案 → 人声合成 → 数字人角色 → 数字人视频 | ❌ 同上（且数字人能力未接） | 同上 + 接数字人供应商 |
+| 6 | 口播+混剪 | 口播脚本 → 人声合成 → 混合风格 → 混合视频 | ❌ 同上 | 同上 |
+| 7 | 短剧创作 | 12 节点（故事→…→成片） | ❌ 同上（但模板结构完整） | 同上 |
+| 8 | 人物置换 | 选源人物 → 选目标人物 → 换人 → 出片 | 🟡 能力已接（百炼 wan2.2），未包成流程 | 包成流程 + 界面 |
+
+> **现状真相**：`workflows.py` 的 6 条模板**结构完整、节点定义齐全**，但 `WorkflowRunner._execute()` **只做拓扑排序然后标记 completed**，**没有任何节点真的执行** —— 这是"点了不跑"的根因。
+
+---
+
+## 四、节点与配置体系（你强调的重点）
+
+### 4.1 节点 = 能力 + 配置 + 上下游
+
+```yaml
+node:
+  id: n3
+  capability_id: tts_generate        # 用哪个能力（可替换！）
+  provider: volcano                  # 该能力的供应商（默认可改）
+  model: CosyVoice-v2                # 大模型（默认可改）
+  params:                            # 该节点所有可配置项（默认值预填，全部可改）
+    text: "{{n1.script}}"            # 上游节点输出 → 本节点输入（数据流）
+    emotion: warm
+    speed: 1.0
+  outputs: { audio_path: "var.vo" }  # 本节点输出 → 供下游引用
+```
+
+### 4.2 配置的三个来源（全部暴露给你）
+
+```
+① 能力默认值（出厂设置）      ← 打开节点就能看到
+② 流程级默认（这条流程整体改）  ← 比如"这条流程统一用 9:16 竖屏"
+③ 节点级覆盖（本次执行改）      ← 只改这一个节点
+```
+
+**UI 规则（你要求的"能改的地方都要能选"）**：
+- 每个节点的**所有可配置项都列出来**（默认值预填）
+- 显示**来源标记**（默认 / 流程 / 节点），改了就在当前层生效
+- 提供「恢复默认」
+- **供应商 + 模型**是独立下拉（每个能力可选多家 → 每个供应商可选自家模型）
+
+### 4.3 节点可替换（"同一个需求找不同能力"）
+
+以"要一段声音"为例，节点里可以选：
+```
+▸ 能力 A：TTS 合成        输入文字 → 出音频（默认路径）
+▸ 能力 B：音色提炼 + 合成  先给一段参考音频 → 提炼音色 → 再合成
+▸ 能力 C：从资产库调音色    选一个已有音色 → 合成
+```
+→ 节点上有个「🔄 替换能力」，选不同能力，参数面板随之切换。
+
+---
+
+## 五、执行与审查机制 ★ 你最关心的部分
+
+### 5.1 两种模式（可随时切换）
+
+```
+▸ 自动模式：点「▶▶ 全部执行（默认配置）」→ 一条龙跑完 → 出成品 → 你在成品上审
+             （前提：默认配置必须能走通 —— 我会保证并逐条验证）
+
+▸ 逐步模式：点「▶ 执行本节点」→ 出结果 → 你审视 → 改 or 继续
+             （可设"断点"：跑到某节点自动停）
+```
+
+### 5.2 每个节点的结果展示 + 纠正（核心）
+
+| 节点类型 | 产物形态 | 你怎么审视/纠正 |
+|:--|:--|:--|
+| **文本类**（剧本/提示词/台词/字幕） | 原文显示在节点里 | **直接编辑**；不满意可「🔄 重生成」（可加"修改意见"再生成） |
+| **音频类**（配音/BGM） | 内嵌播放器 | 听；不满意 → 改参数（音色/语速/情绪）→「🔄 重做」 |
+| **图片类**（参考图/分镜图） | 缩略图预览 | 看；不满意 → 改提示词/换模型 →「🔄 重做」；可「选一张」 |
+| **视频类**（镜头片段） | 内嵌播放器 | 看；不满意 → 改提示词/换镜头 →「🔄 重做」；可「换一版」多出几条挑 |
+| **决策类**（策略/风格/审核门） | 选项列表 | 直接改选项；审核门可"通过/打回" |
+
+**统一交互**：
+```
+节点卡片
+┌───────────────────────────────┐
+│ 🔊 TTS 合成        [执行] [重做] │
+│ ├ 供应商 [火山▾]  模型 [Cosy▾] │
+│ ├ 情绪 [warm▾]  语速 [1.0]     │
+│ ├ 输入: ← 脚本节点"口播稿"      │
+│ └ 结果: ▶ [播放音频] 3.2s  ✅  │
+└───────────────────────────────┘
+```
+- **未执行的节点**：灰显 + 「▶ 执行」
+- **已执行的节点**：绿标 + 产物预览 + 「🔄 重做」（改配置后重跑，下游自动标记"需重跑"）
+- **全局**：可「从某节点起重跑下游」
+
+### 5.3 导演创作流程的审视点（按你的描述）
+
+```
+① 输入剧本/小说/思路          → 你写（或从资产/素材带入）
+② 剧本创作（导演系统产出分镜）  → **审视**：看分镜表，逐镜头改台词/画面/镜头契约
+③ 逐镜头配置（选特效/角度/模型）→ **审视**：每个镜头有默认配置，你只改不满意的
+④ 编排执行（生成→去AI化→拼接）→ **审视**：每条片段可看/可重做
+⑤ 结果挑选 / 调整              → 选终版 or 重跑某镜头
+```
+
+> 你的原话："每个镜头我不需要手动配，但我要去审视一下现在配的结果；中间要修改就修改，不修改就用默认" ✓ **就是这个设计**。
+
+---
+
+## 六、后端架构
+
+```
+┌── L1 能力层（Capability Registry）── ✅ 已有（25 个），需扩展
+│     capabilities.yaml + 加载器 + /api/ave/capabilities
+│     每个能力：输入输出契约 / 参数 schema / 供应商[] / 默认值 / 实现位置
+│
+├── L2 节点层（Node）── 🟡 部分有（workflows.py 的 15 种节点定义）
+│     Node = 能力引用 + 参数覆盖 + 上下游映射 + 状态(未跑/跑完/失败)
+│
+├── L3 流程层（Template/Process）── 🟡 6 条模板已有，需扩展（+导演创作/人物置换）
+│     Template = 节点 + 连线 + 流程级默认 + 元信息
+│
+├── L4 执行器（Runner）── ❌ **空转，必须重做**
+│     拓扑执行 → 逐节点调能力 → 产物落地 → 状态回写 → 断点/续跑 → 重跑上游
+│     （这是"工作流能真跑"的核心）
+│
+├── L5 资产层（Assets）── ❌ **要重建**（旧 character_registry 只覆盖角色且字段旧）
+│     按你的分类建库 + 生成入口 + 引用机制
+│
+└── L6 接口/UI ── 前端页面 + FastAPI 路由
+```
+
+**执行通道**：
+- 轻任务（解析/规划/合成）→ 本地线程
+- 长任务（可灵生成 / ComfyUI）→ 走 guardd 任务（有任务面板、可停、可重试）
+
+---
+
+## 七、与现有代码的映射（哪些复用、哪些重做）
+
+| 现有资产 | 处置 |
+|:--|:--|
+| `capabilities.yaml`（25 能力） | **复用**（L1 底座）→ 按需扩充 |
+| `workflows.py` 的 6 模板 + 15 节点定义 | **复用结构**（L2/L3）→ 重做执行器 |
+| `workflow.js` 画布 UI（485 行） | **复用**（拖拽 + 节点配置面板）→ 补"产物预览 + 重做" |
+| `scheduler.py` / `scorer.py`（模板引擎） | 参考（筛选模板用） |
+| `composer/*`（去AI化/拼接/变速/转场） | **复用**为能力实现 |
+| `capabilities/kling_video.py`（可灵） | **复用**为能力实现 |
+| `character_registry/`（旧角色库） | **改造**：字段按你的要求重建；补场景/道具/产品 |
+| `character_sheet.py`（定妆照） | **复用**为产出型能力 |
+| `person_swap/`（百炼换人） | **复用** → 包成"人物置换"流程 |
+| `story_director/` + `directors/` | **复用**（导演流程的②环节） |
+| `schemas.py`（统一分镜） | **复用**（导演流程的数据契约） |
+| `video_factory.py`（CLI 老流程） | **改造**：拆成能力 + 流程模板 |
+| `workflows.py` 的 Runner | **重写**（执行器） |
+
+---
+
+## 八、改造计划与**实际进度**（每阶段以"能点、能看结果、能改"验收）
+
+| 阶段 | 内容 | 状态 |
+|:--|:--|:--|
+| **P1 架构对齐** | 本文档定稿 + 旧文档归档 + 菜单按新结构重组 | ✅ **已完成**（`4.10.0`：菜单 4 组 + 20 占位页） |
+| **P2 执行器** | 重写 `WorkflowRunner`：真执行 + 逐节点产物 + 状态 + 重做 | ⏳ **待决策**（编排层 A/B）· 前置调研已完成（15 节点映射表见附录 D） |
+| **P3 节点配置面板** | 每节点全配置暴露（默认值 + 供应商 + 模型 + 参数）+ 替换能力 | ⏳ 属 P2 范围（依赖执行器） |
+| **P4 导演创作补全** | 统一分镜 Schema + 导演可切换 + 分镜编辑 + 一键出片 | ✅ **已完成**（`2607a973b`→`304d7e30e`；实测 3 镜头 **1.9 分钟**出片 / **3.2MB**） |
+| **P5 资产底座** | 按分类建库（角色/场景/道具/产品/音色…）+ 上传/编辑 | ✅ **主体完成**（`2b866c23a` `eebeabcbc` `1aa4651f6`：**10 类资产** + 通用组件；**生成入口待图片模型名确认**） |
+| **P6 流程补齐** | 人物置换 + 6 条老流程逐条通电验证 | ⏳ **待 P2** |
+| **P7 辅助** | 生产记录 + 费用 + 设置 | ✅ **已完成**（生产记录含磁盘持久化 · 费用统计含可灵估算+AI token · 设置含去AI化/输出/渲染） |
+| — | **S1 能力注册表**（25 能力 + 能力库页 + 供应商管理 + 能力试跑） | ✅ **已完成**（`952b39970` `4c6caf2f3`：39 个供应商，密钥状态 18/27 已配） |
+| — | **S2 导演创作**（v5.2 技能入库 + 六模块提示词 + 交付状态三级 + Webhook 验签） | ✅ **已完成**（`82a63f4b3` 起） |
+
+**当前剩余**：**P2（编排通电）** —— 等编排层决策（① 复用 `workflows.py` / ② 装 n8n）后即可开工；「历史操作」页仍为占位（低优先级）。
+
+---
+
+## 九、待你确认（关键，定了才动手）
+
+1. **资产分类的字段**（你说"我给的分类都没有" —— 请再给一次）：
+   - 角色要什么字段？（正面照/多角度/服装变体/表情/音色/年龄/身高…）
+   - 场景/道具/产品各要什么？**产品 vs 道具**怎么区分？
+   - 分类方式（按项目？按类型真人/动漫？按用途主角/配角？）
+2. **菜单是否按本文第二节重组**？（流程/能力/资产/辅助 四大块）
+3. **执行模式默认哪个**？（逐步 or 自动；我建议默认"逐步"，你熟了可切自动）
+4. **阶段优先级**：P2（执行器通电）和 P5（资产重建）你想先做哪个？
+
+---
+
+## 附录 C｜与《导演创作系统说明书 v2.0》的对齐（**重要基准**）
+
+> 用户原始设计文档：`~/Documents/导演创作系统（Director.docx`（829 行，v2.0，2026-10-01 更新）
+> 本节把文档的**逻辑架构**映射到**现有看板**，明确哪些复用、哪些要补 —— **以文档为基准，不再自由发挥**
+
+### C.1 文档的五层架构 → 我们的实现
+
+| 文档层 | 文档原方案 | 我们的现状 | 处置 |
+|:--|:--|:--|:--|
+| **层0 导演控制台** | Appsmith（Docker :80）；页面：分镜编辑/资产库/3D角色/特效库/任务状态/成片预览/参数模板/系统设置 | **Dashboard（:9988）** 已有：导演创作 / 能力库 / 工作流 / 生产记录 / 费用 | ✅ **复用现有看板**（功能更全，不必新装 Appsmith） |
+| **层1 导演层** | 任一导演系统输出统一 Schema | `directors/`（v5.2 + legacy）+ `schemas.py`（14 模型） | ✅ 已完成 |
+| **层2 编排层** | n8n（Docker :5678）：Webhook→读Schema→循环shot→Switch按type分发→等完成→下载→FFmpeg→回调 | `workflows.py`（6 模板 + 15 节点 + 画布）**但执行器空转** | ⚠️ **二选一**（见 C.3） |
+| **层3 能力层** | 远端 API，8 大类每家多供应商（TTS/口播/动作/背景/ComfyUI/3D/特效） | `capabilities.yaml`（25 能力，含多供应商）+ 可灵/video 引擎 | ✅ 骨架已备，供应商待补 |
+| **层4 合成层** | FFmpeg：去AI化 → 帧混合 → 拼接 | `composer/`（de_ai.py + pipeline.py） | ✅ 已完成（**注意**：文档写 `-crf 18`，我们改为 `23` 以控体积） |
+
+### C.2 资产库规范（文档第五节 → 落地基准）
+
+```
+assets/
+├── characters/       角色 2D — reference.png / _side.png / _full.png / lora.safetensors / voice_sample.mp3 / meta.json
+├── characters_3d/    角色 3D — model.glb / model.fbx / texture/ / rig_info.json / meta.json
+├── locations/        场景（AI生成）— reference.png / reference_video.mp4 / meta.json
+├── real_locations/   真实场地 — reference_wide.jpg / _detail.jpg / _light.jpg / reference_video.mp4 / meta.json
+├── products/         产品 — reference_front.png / _angle.png / _detail.png / _in_hand.png / meta.json
+├── props/            道具（结构同 products）
+├── bgm/  sfx/        音频资产
+└── vfx_presets/      特效预设 — bullet_time.yaml / orbit.yaml / slow_motion.yaml
+```
+
+**元数据规范（文档原文）**：
+- **产品**：`id / name / category / must_keep[]（必保特征，如"瓶身标签文字""瓶盖金色边框"）/ reference_images{front,angle,detail,in_hand} / consistency_seed`
+- **3D 角色**：`id / name / source_tool / model_formats[] / rigged / rig_type / reference_2d_id / consistency_seed / created_at`
+- **引用方式**：分镜 Schema 通过 `character_id / character_3d_id / location_id / product_id / props[] / bgm_id / sfx.id / vfx.vfx_id` 引用 → 执行器按 ID 从资产库取文件注入 API
+
+**我们现状**：只有 `character_registry/registry.yaml`（14 角色；字段：description/appearance/personality/voice_style/art_style/bgm_style/reference_images/prompt_template）→ **需按上述结构重建**
+
+### C.3 两个关键决策（等你定）
+
+**决策 1：编排层用哪个？**
+| 方案 | 说明 | 优劣 |
+|:--|:--|:--|
+| **A. 复用现有 workflows.py + 重写执行器** | 已有 6 模板 + 15 节点 + 画布 UI + 节点配置面板；只需把"假执行"换成真执行 | ✅ 不用新装服务 · ✅ 与看板一体 · ⚠️ 执行器要自己写 |
+| **B. 按文档装 n8n（Docker :5678）** | 照文档原方案，n8n 做编排，看板只当控制台 | ✅ n8n 成熟（可视化/重试/日志） · ⚠️ 要装 Docker 服务 + 学 n8n · ⚠️ 与看板两套系统 |
+| **C. 混合** | 看板做控制台 + 流程配置，轻任务本地执行；把"逐镜头生成"这段交给 n8n | 复杂度高 |
+
+**决策 2：控制台用哪个？**
+- **A. 现有 Dashboard（:9988）** ← 建议（已能跑、功能多、Tailscale 可访问）
+- B. 按文档装 Appsmith（:80）—— 要重搭所有页面
+
+### C.4 文档「导演操作流程 12 步」→ 现状对照
+
+| # | 文档步骤 | 现有看板 | 状态 |
+|:--|:--|:--|:--|
+| 1 | 打开浏览器 | :9988 | ✅ |
+| 2 | 分镜编辑页输入故事大纲 | 视频工厂 → 🎬 导演创作 | ✅ |
+| 3 | **选内容类型**（产品广告/个人日记/场景短剧） | — | ❌ **缺** |
+| 4 | **选角色**（2D 参考图 / 3D 绑定模型） | — （Schema 有字段，UI 未暴露） | ❌ **缺** |
+| 5 | **选场景/场地/产品** | — | ❌ **缺** |
+| 6 | 点击生成分镜 | 🚀 生成分镜 | ✅ |
+| 7 | 逐条检查/修改 + **添加特效**（子弹时间/环绕运镜） | 能改文字；**特效面板无** | 🟡 部分 |
+| 8 | 提交任务 | 🎥 生成成片 | ✅ |
+| 9 | 编排层调各 API 生成片段 | 我们的流水线（逐镜头→可灵） | ✅ |
+| 10 | FFmpeg 去AI化 + 拼接 | composer（已修 + 体积优化） | ✅ |
+| 11 | 刷新预览成片 | 进度条 + 成片路径 | ✅ |
+| 12 | 不满意 → **改对应镜头参数** → 重试单条 | 有单镜头重生成，但**不是"改参数重试"** | 🟡 部分 |
+
+**缺的 4 项**：③内容类型 ④选角色 ⑤选场景/产品 ⑦特效面板 ⑫改参数重试
+
+### C.5 文档里的能力清单（供应商维度，能力注册表要照此扩充）
+
+| 模块 | 文档列出的可选供应商 |
+|:--|:--|
+| TTS | Fish Audio / ElevenLabs / Qwen3-TTS |
+| 口播视频 | D-ID / HeyGen / 本地 LongCat |
+| 动作视频 | 可灵 / Wan-Animate-2 / Runway |
+| 背景空镜 | 通义万相 / Sora 2 / 可灵 |
+| ComfyUI | RunningHub / ComfyDeploy / 自建 |
+| 3D 角色 | 混元3D / Autodesk Flow Studio |
+| 特效·子弹时间 | 万兴天幕 / 海螺AI / 可灵 |
+| 特效·运镜 | 可灵（camera_control 六参数 ∈[-10,10]）/ 海螺AI（T2V-01-Director） |
+
+---
+
+## 附录 D｜节点 → 能力映射表（P2 执行器的实施依据）
+
+> 调研结论：`workflows.py` 的 15 种节点定义**只有 UI 元数据**（label/icon/description/default_config/options_map），
+> **没有绑定到真实能力**；`WorkflowRunner` 是空壳。下表把 15 种节点映射到能力注册表里的实现。
+
+| # | 节点类型 | 名称 | 对应能力 | 状态 |
+|:--|:--|:--|:--|:--|
+| 1 | `story_prototype` | 剧本原型 | `script_generate`（LLM 生成） | ✅ ready |
+| 2 | `script` | 脚本输入 | **无执行**（用户输入 / 读文件） | — 透传 |
+| 3 | `script_adaptor` | 剧本改编 | `script_parse` + `script_generate` | ✅ ready |
+| 4 | `strategy` | 策略选择 | LLM 决策 或 参数选择 | 🟡 待明确 |
+| 5 | `tts` | TTS 合成 | `tts_generate`（火山/阿里） | ✅ ready |
+| 6 | `model` | AI 模型 | LLM（DeepSeek）通用调用 | ✅ ready |
+| 7 | `material` | 素材源 | `material_search`（Pexels/万相/兜底） | ✅ ready |
+| 8 | `style` | 风格预设 | **无执行**（参数注入） | — 透传 |
+| 9 | `bgm` | BGM 选择 | `bgm_generate` / `music_select` | ✅ ready |
+| 10 | `character` | 角色 | **资产引用**（无执行，取资产注入） | — 引用 |
+| 11 | `audit_gate` | 审核门 | **人工暂停/继续**（需实现断点机制） | 🟡 待实现 |
+| 12 | `output` | 输出 | `video_concat` + `de_ai` | ✅ ready |
+| 13 | `storyboard` | 分镜规划 | `storyboard_plan`（v5.2/clip/legacy） | ✅ ready |
+| 14 | `prompt_gen` | 分镜提示词 | `prompt_gen`（六模块编译器） | ✅ ready |
+| 15 | `subtitle` | 字幕生成 | `subtitle` | 🟡 partial |
+
+**结论**：
+- **12/15 节点已有现成能力**（ready 或 partial）
+- 4 个是"无执行"节点（`script` 输入 / `style` 参数 / `character` 引用 / `strategy` 决策）→ 执行器**透传**即可
+- 1 个需新机制：`audit_gate`（人工审核门 → 暂停/继续）
+
+**P2 执行器工作量**（已明确）：
+1. 建 `NODE_TYPE → capability_id` 映射（上表）
+2. 执行器：拓扑排序 → 逐节点调能力 → 产物存 run context → 下游按 `{{node.xxx}}` 引用 → 状态回写
+3. 特殊处理：无执行节点透传 · `audit_gate` 暂停 · 失败重试 · 「从某节点起重跑下游」
+4. 前端：节点卡片显示产物预览（文本可编辑 / 音视频可播放）+ 🔄 重做
+
+---
+
+## 附录 E｜P2 实施要点（执行器改动清单 —— 决策后即可开工）
+
+**目标文件**：`05_tools/10_dashboard/workflows.py`（599 行）
+
+**现状（3 处关键代码）**：
+
+| 位置 | 现状 |
+|:--|:--|
+| `WorkflowRunner._execute()`（519 行） | 只做拓扑排序 → 把节点标记 `completed`，**无任何真实执行** |
+| `NODE_DEFINITIONS`（35 行） | 15 种节点**只有 UI 元数据**（label/icon/description/options_map），**未绑定能力** |
+| `start_run()`（510 行） | 起后台线程调 `_execute` ✓ 骨架可用（可直接复用） |
+
+**改动清单（3 步）**：
+
+1. **建映射**：`NODE_TO_CAPABILITY = {node_type: capability_id}` —— 附录 D 已给出 15 项对应（12 项有现成能力）
+2. **写节点执行** `_run_node(node, ctx) -> dict`：
+   - 查映射 → 取能力 → 合并参数（**能力默认 ← 流程覆盖 ← 节点覆盖**）→ 调实现 → 返回产物
+   - **4 个无执行节点**（`script` / `style` / `character` / `strategy`）→ **透传**（直接传上游值）
+   - `audit_gate` → 置 run 状态为 `paused`，等外部 `resume`
+3. **改 `_execute()`**：逐节点调 `_run_node` → 产物存 `run["context"][node_id]` → 下游按 `{{node.xxx}}` 解析 → 状态回写（success/failed/skipped）→ 失败按节点重试配置重试
+
+**后端新接口（3 个）**：
+
+| 接口 | 用途 |
+|:--|:--|
+| `POST /api/workflow/runs/{run_id}/redo/{node_id}` | 单节点重做（改配置后重跑） |
+| `POST /api/workflow/runs/{run_id}/resume` | `audit_gate` 审核通过 → 继续 |
+| `GET /api/workflow/runs/{run_id}/artifacts` | 各节点产物列表（供前端预览） |
+
+**前端配合**（`views/workflow.js` 画布已就绪）：
+- 节点卡片加**状态徽章** + **产物预览**（文本可编辑 / 视频可播放）
+- 「🔄 重做此节点」·「▶️ 从此刻起跑下游」按钮
+
+**可复用**（无需重写）：
+- 能力注册表（`capabilities/`）· 可灵引擎（`kling_video.py`）· 流水线（`composer/pipeline.py`）· 资产库（`assets_manager/`）· 成本统计（`api_costs`）
+
+---
+
+## 附：归档说明
+
+以下文档**已归档**（内容被本文档取代，避免误导后续开发）：
+- `VIDEO_FACTORY_FRAMEWORK.md`（v1 框架：菜单分类有误，见第二节）
+- `VIDEO_FACTORY_ARCHITECTURE.md`（技术细节，已并入本文第六节）
+- `DCS_VIDEO_FACTORY_PLAN.md`（调研 + M1 计划，M1 已完成）
+
+归档位置：`90_archive/video_factory_docs_20261001/`