# 视频工厂 · 使用指南

> 更新: 2026-10-02 · 对应版本 4.11.x
> 架构文档: `PLANS/VIDEO_FACTORY_MASTER.md` · 原始设计: `PLANS/reference/DCS_说明书_v2.0_原文.md`

---

## 一、快速开始（3 步出片）

1. 打开看板 **http://localhost:9988**（如果是旧界面，`Cmd+Shift+R` 硬刷新）
2. 侧边栏 → **🎞️ 视频工厂 · 流程** → 任选一条流程（如「🎙️ 基础口播」）
3. 看到流程步骤链 + 预估成本 → 点 **▶️ 开始** → 画布自动加载模板
4. 把「**镜头数**」设为 **1**（首次试跑，控成本）→ 点 **▶ 运行**
5. 观察节点状态（🟢完成 / 🔵执行中 / 🔴失败 / ⚪跳过）→ 点节点看**产物预览**（视频/音频可直接播放）

---

## 二、流程清单

| 流程 | 模板 | 节点数 | 说明 |
|:--|:--|:--|:--|
| 🎬 导演创作 | （单页） | — | 故事 → 分镜（可编辑）→ 一键出片 |
| 🎭 短剧创作 | `short_drama` | 12 | 完整短剧流程 |
| 🎙️ 基础口播 | `basic_dub` | 5 | 脚本 → TTS → 素材 → BGM → 输出 |
| 🥁 卡点视频 | `beat_sync` | 4 | BGM 卡点 |
| 📖 角色叙事 | `character_narrative` | 8 | 角色 + 旁白 |
| 👤 数字人口播 | `digital_human` | 4 | 需数字人能力（待接入） |
| 🎞️ 口播+混剪 | `hybrid_dub` | 4 | — |
| ➕ 新建流程 | （空白画布） | — | 自己拖节点 |

---

## 三、能力与依赖（配 key 就能用）

| 能力 | 状态 | 依赖 | 备注 |
|:--|:--|:--|:--|
| 🎬 分镜规划 | ✅ | `llm.api_key`（DeepSeek） | 已配 |
| 📝 提示词生成 | ✅ | 同上 | 已配 |
| 🎥 视频生成 | ✅ | `kling.api_key` | 已配（`kling-v3`） |
| 📦 视频合成 | ✅ | 本地 FFmpeg | 含去AI化 |
| **🔊 混流** | ✅ | 本地 FFmpeg | 视频+人声+BGM+字幕 |
| **🎤 TTS 语音** | ⚠️ | `aliyun.api_key` **（欠费）** / `volcano.voice_app_key`（缺 token） | **充值阿里即用** |
| 🔌 素材搜索 | ⚠️ | `pexels.api_key` | 免费申请 pexels.com/api |
| 🎵 BGM 选择 | ✅ | 本地音乐库 | — |
| 💬 字幕生成 | ✅ | 本地 | ASS 格式 |
| 🔄 人物置换 | ⚠️ | `aliyun.api_key`（同 TTS） | 充值即用 |
| 💋 对口型 | ⚠️ | `fal.api_key` | 未配 |

**配置入口**：Dashboard → **⚙️ 服务 → 🔑 API 配置**（每项可「🧪 测试」验证连通性）

---

## 四、常见问题

**Q: 报「阿里百炼账号欠费（Arrearage）」**
→ 阿里云控制台充值（同时解锁 TTS + 人物置换）

**Q: 报「Pexels API Key 未配置」**
→ https://www.pexels.com/api/ 免费申请 → 「🔑 API 配置」填入

**Q: 出片很慢（10+ 分钟）**
→ 可灵服务端排队（高峰期常见），非代码问题。可在「能力试跑」页用预检查看任务状态

**Q: 成片没有声音**
→ 检查流程里是否有 TTS 节点 + TTS 是否成功（阿里欠费会失败）

**Q: 节点显示「跳过」**
→ 该能力尚未接入执行器（如 ComfyUI/特效/3D 角色），或缺少必要上游产物

**Q: 分镜不满意**
→ 「🎬 导演创作」页可逐镜头编辑 + 🔄 单镜头重生成；或换导演（v5.2 / 本地）

---

## 五、省钱的调试技巧

1. **镜头数先设 1**（默认 3）—— 每镜头约 ¥1-3
2. **优先只读**：查任务列表/状态用 GET（不扣费），别反复跑生成
3. **用「🧪 能力试跑」的预检**（dry_run，零费用）：确认供应商/模型/参数/密钥状态后再真跑
4. **复用已有产物**：TTS 音频、字幕文件可跨 run 复用（修改配置只重做必要节点 → 「🔄 重做此节点」）

---

## 六、关键命令（运维）

```bash
# 重启看板（必须用 launchctl，禁止 pkill+nohup）
launchctl kickstart -k gui/$(id -u)/com.agentos.dashboard
curl -s http://localhost:9988/api/health

# 查看运行
curl -s http://localhost:9988/api/workflow/runs | python3 -m json.tool | head -30

# 产物位置
ls ~/workbuddy-agent-os/agent-local/runtime/ave/workflow/<run_id>/

# 出片记录（导演创作页产物）
ls ~/workbuddy-agent-os/agent-local/runtime/ave/renders/
```