---
name: fmode-mv
description: "触发词：做MV/做音乐视频/写歌并出片/口播讲解视频/AI音乐/AI视频/人物参考图/角色多视图。两条产线：AI单曲MV（作曲填词→音乐→人物资产→场景图→关键帧→图生视频→成片）与AI口播/商业短视频（对标→仿写→分镜→人物资产→场景→图生视频→数字人口播→成片）。纯ESM零依赖，即梦通道实测可用。"
version: 0.2.0
author: Fmode (FmodeAgent)
license: MIT
platforms: [linux, macos]
tags: [mv, music, video, ai, ffmpeg, lyrics, storyboard, jimeng, volcengine, character-sheet, img2video, digital-human]
---

# fmode-mv · SKILL

> 纯 AI 视频全流程技能。从一句主题到成片，**全程零实拍**。
> v0.2.0 起接入**即梦（火山引擎）真实通道**，图生视频从「兜底运镜」升级为真 AI 生成。

## 一、这是什么

把「文案 → 分镜 → 人物 → 场景 → 关键帧 → 图生视频 → 成片」整条链路固化成**可复用的技能仓库**。
任何数字生命克隆本仓即可照跑：

```bash
git clone https://git.fmode.cn/fmode-13177980648/skill-mv.git
cd skill-mv
node bin/fmode-mv.js doctor                  # 环境自检
node bin/fmode-mv.js providers               # 看通道现状（jimeng ✅）
node bin/fmode-mv.js song "主题"              # 端到端跑一条 MV
node bin/fmode-mv.js talk "口播主题"          # 端到端跑一条口播视频
```

### 硬约束：纯 AI 生成，不靠实拍

- **所有画面由 AI 生成**（即梦文生图 / 图生图 / 图生视频 / 数字人）。
- **现实拍摄素材最多作参考图 / 参考音**，不得作为成片画面直接使用。
- **绝不静默失败，绝不伪造产物**：通道不可用就如实报错并降级，降级产物一律带 `.fallback` 标记。

## 二、两条产线

两条产线**共用同一套底层模块**（图像 / 视频 / 音频 / 剪辑 / provider 接口），只是编排不同。

### 产线 A · AI 单曲 MV

```
歌曲主题
  → 作曲填词                 [chat ✅]
  → AI 生成音乐              [music ⚠️ 未开通，可自备音频]
  → 人声/伴奏分离             [local ◐]
  → ④ 人物资产多视图          [即梦 ✅]  ← 定妆照→上半身→全身→多视图
  → ⑤ 场景图 → 关键帧         [即梦 ✅]  ← 无人环境 + 多图参考合成
  → ⑥ 图生视频               [即梦 ✅]  ← 首尾帧/首帧，含降级
  → 剪辑合成（卡点+字幕+混音）  [local ffmpeg ✅]
  → out/mv.mp4
```

```bash
fmode-mv song "深夜末班地铁上的城市白领" --genre "city pop" --mood "孤独但温暖" --shots 8
```

### 产线 B · AI 口播 / 商业短视频（VOC-SOP 五阶段）

```
对标文案 → 仿写(10版) → 分镜 → 人物资产 → 场景图/关键帧 → 图生视频 → 数字人口播 → 成片
 [阶段1]     [阶段2]    [阶段3]    [即梦]      [即梦]         [即梦]      [即梦 ¥1/秒]   [ffmpeg]
```

```bash
fmode-mv talk "三分钟讲清楚什么是多租户数据隔离" --duration 90 --shots 8
fmode-mv talk --script work/script.md          # 用现成口播稿
```

> 完整 SOP（含各阶段检测清单、合规/脱敏边界）见 `references/voc-sop-pipeline.md`。

## 三、★ 工序清单（v0.2.0 全部工序）

| # | 工序 | 命令 | 通道 | 状态 |
|---|---|---|---|---|
| ① | 作曲填词 | `lyrics` | chat | ✅ |
| ② | 分镜脚本 | `storyboard` | chat | ✅ |
| ③ | 口播稿 | `talk`（内置） | chat | ✅ |
| **④** | **人物资产多视图** | **`character-sheet`** | **即梦** | **✅ 本版新增** |
| **⑤** | **场景图（无人）→ 关键帧（有人）** | **`scene`** | **即梦** | **✅ 本版新增** |
| **⑥** | **图生视频** | **`video`** | **即梦** | **✅ 本版新增（真通道，非兜底）** |
| ⑦ | 剪辑成片 | `assemble` | local ffmpeg | ✅ |
| ⑧ | 数字人口播 | `jimeng digital-human` | 即梦 | ✅ **替代唇形驱动** |
| ⑨ | 动作模仿 | `jimeng actor` | 即梦 | ✅ |
| ⑩ | 智能超清 | `jimeng upscale` | 即梦 | ✅ |
| — | AI 音乐 | `music` | music | ⚠️ 未开通 → 自备音频 |
| — | TTS 配音 | `tts` | tts | ⚠️ 未开通 → 见下方替代 |
| — | 唇形驱动 | `lipsync` | lipsync | ⚠️ 未开通 → **已改用即梦数字人** |

### 产线 B 的工序映射（VOC-SOP 五阶段 → 命令）

| SOP 阶段 | 命令 |
|---|---|
| 0 准备 / 1 文案获取 | 仓外（需 yt-dlp / Whisper 等）；或用 `talk "主题"` 从零写 |
| 2 脚本仿写 | `templates/copywriting-prompt.md` + `talk` |
| 3 分镜生成 | `storyboard` + `templates/storyboard-prompt.md` |
| 4a 照片生成 | `character-sheet`（人物）+ `scene --scene-only`（场景） |
| 4b 视频生成 | `video` + `templates/video-prompt.md` |
| 4.5 素材修正 | 重跑对应工序加 `--shot <id> --force` |

## 四、★ 能力现状（实测，务必据此预期）

| 环节 | 通道 | 现状 | 说明 |
|---|---|---|---|
| 作曲填词 / 分镜 / 口播稿 | `POST /v1/chat/completions` | ✅ **可用** | `deepseek-v4-flash`、`doubao-seed-2-1-pro` 等 |
| **文生图 / 图生图** | 即梦 `/getText2ImgV3` `/getImgV4` `/getImg2ImgV3` | ✅ **可用** | 实测 ¥0.20/张，1728×2304 PNG 约 200KB |
| **图生视频 720p/1080p/Pro** | 即梦 `/getVideoV3_720p` 等 | ✅ **可用** | 实测 121 帧 5 秒，实扣 **¥1.41**，返回 h264 mp4 |
| **人物动作模仿** | 即梦 `/getActorV2` | ✅ **可用** | ¥0.4/秒（单条最低 ¥3.2） |
| **数字人口播** | 即梦 `/getOhIdentifyMain`→`/getOmniHuman` | ✅ **可用** | ¥1/秒，替代唇形驱动 |
| **智能超清** | 即梦 `/getSuperResolution` | ✅ **可用** | ¥0.4/张 |
| 关键帧（旧 image 通道） | `POST /v1/images/generations` | ✅ 可用 | `gpt-image-2.5-sunburst`；即梦已可替代 |
| AI 音乐 | `POST /suno/submit/music` | ❌ **未开通** | 实测 503 `Task request failed`；请自备音频 `--music your-song.mp3` |
| 图生视频（旧网关） | `POST /v1/video/generations` | ❌ **未开通** | 实测 503 `No available channel`；**已改用即梦图生视频** |
| 唇形驱动 | — | ❌ **未开通** | 网关无该路由；**已改用即梦数字人**替代 |
| TTS 口播配音 | `/v1/audio/speech` | ❌ **未开通** | 网关无该路由；本地 edge-tts 在部分云环境被 403 拦截 |
| 音轨分离 | 本地 | ◐ ffmpeg 相位兜底 / demucs 可选 | 需要真·分离请装 demucs |
| 剪辑 / 合成 | 本地 ffmpeg | ✅ **可用** | 拼接 / 混音 / 字幕 / 卡点 / 响度归一化 |

随时用 `fmode-mv providers`（加 `--deep`）查看最新状态；明细见 `references/capability-matrix.md`。

### 未开通通道怎么处理 —— 本技能的承诺

**绝不静默失败，绝不编造产物。**

- 调用未开通通道 → 抛 `ProviderUnavailableError`，打印**可操作方案**。
- 产线编排里遇到未开通步骤 → **如实标记 `unavailable`**，能兜底的才兜底，并在报告中标出。
- 图生视频整体不可用时 → 自动降级为「关键帧 + Ken Burns 运镜」，产物**文件名带 `.fallback`**。
- `method=3`（首尾帧）失败 → 自动降级 `method=2`（首帧），并在返回值与日志里**留痕 `degraded: true`**。

替代路线：

| 缺失能力 | 立即可用的替代 |
|---|---|
| AI 音乐 | 自备音频 `--music your-song.mp3`；等渠道开通后原样重跑 |
| TTS | 本地 `edge-tts`（`pip install edge-tts`，自动探测）；或 `FEME_TTS_ENDPOINT` 对接外部服务；或 `--voice` 指定现成音频 |
| 唇形驱动 | **即梦数字人**：`fmode-mv jimeng digital-human --ref 人脸图 --audio 配音.mp3`（¥1/秒） |
| 图生视频（旧） | **即梦图生视频**：`fmode-mv video --mode jimeng`（720p ¥0.28/秒） |

## 五、安装与凭据

```bash
git clone https://git.fmode.cn/fmode-13177980648/skill-mv.git
cd skill-mv
npm link            # 可选：全局获得 fmode-mv 命令
fmode-mv doctor
```

**依赖**：

- Node ≥ 18（用内置 `fetch`，**零 npm 依赖**）
- `ffmpeg` / `ffprobe`（`apt-get install -y ffmpeg`）
- 凭据（见下）
- 可选：`demucs`（高质量音轨分离）、`edge-tts`（免费 TTS）、`python3` + `PIL` + `numpy`（人物资产择优，缺失时自动用 ffmpeg 兜底）

### 凭据（零硬编码，运行时读取）

即梦通道需要 **sessionToken**（不是 newapi_token）。按优先级读取：

1. 环境变量 `FMODE_SESSION_TOKEN`
2. `/opt/data/fmode-identity.json` 的 `session_token` 字段

```bash
export FMODE_SESSION_TOKEN=<你的sessionToken>
```

其它可选覆盖项：

| 环境变量 | 作用 | 默认 |
|---|---|---|
| `FMODE_JIMENG_BASE` | 即梦代理基址 | `https://server.fmode.cn/api/volcengine/jimeng` |
| `FMODE_PARSE_BASE` | Parse 基址（读 ImagineWork） | `https://server.fmode.cn/parse` |
| `FMODE_PARSE_APPID` | Parse App ID | `ncloudmaster` |
| `FMODE_CDN_COMPANY` | 七牛上传用的 company ID | `XlTE6uWQEQ` |
| `FMODE_VIDEO_RESOLUTION` | 视频分辨率 | `720p` |
| `FEME_API_TOKEN` | 旧网关（chat / image）凭据 | `/opt/data/fmode-identity.json` 的 `newapi_token` |

> 本技能**不会**把 token 写入任何文件、日志、产物或提交。
> 错误信息里也只出现脱敏后的 token。

## 六、命令速查

| 命令 | 作用 | 通道 |
|---|---|---|
| `fmode-mv song "主题"` | 产线A 端到端 | 全链路 |
| `fmode-mv talk "主题"` | 产线B 端到端 | 全链路 |
| `fmode-mv lyrics "主题"` | 作曲填词 | chat |
| `fmode-mv storyboard --from work/song.json` | 分镜脚本 | chat |
| **`fmode-mv character-sheet --desc "..."`** | **④ 人物资产多视图** | **即梦** |
| **`fmode-mv scene --from work/storyboard.json --character <多视图>`** | **⑤ 场景图 + 关键帧** | **即梦** |
| **`fmode-mv video --from work/storyboard.json`** | **⑥ 图生视频** | **即梦** |
| `fmode-mv keyframe --from work/storyboard.json` | 关键帧单跑（旧 image 通道） | image |
| `fmode-mv jimeng --status/--endpoints/--test` | 即梦通道诊断 | 即梦 |
| `fmode-mv jimeng text2img/img2img/img2video/upscale/actor/digital-human` | 即梦能力直调 | 即梦 |
| `fmode-mv music --from work/song.json` | AI 音乐 | music ⚠️ |
| `fmode-mv separate <audio>` | 人声/伴奏分离 | 本地 |
| `fmode-mv tts --from work/script.md` | 口播配音 | tts ⚠️ |
| `fmode-mv lipsync --probe` | 唇形驱动 | lipsync ⚠️ |
| `fmode-mv assemble --from work/storyboard.json --music a.mp3` | 剪辑成片 | 本地 |
| `fmode-mv providers [--deep]` | 能力现状表 | — |
| `fmode-mv doctor` | 环境自检 | — |
| `fmode-mv version --check` | 三处版本一致性 | — |

每个命令都支持 `--help` 查看完整参数。

### 常用示例

```bash
# ④ 人物资产（最省：只跑定妆照 3 张候选 + 择优，¥0.60）
fmode-mv character-sheet --desc "25岁东亚女性，栗棕色长发，白T+波点裙" --limit 1
# 完整四步（9 张候选，≈¥1.98）
fmode-mv character-sheet --desc "..." --limit 4

# ⑤ 场景图 + 关键帧（≈¥0.42/镜）
fmode-mv scene --from work/storyboard.json --character out/character/4-多视图.png --limit 1

# ⑥ 图生视频（1 镜 5 秒 ≈¥1.41）
fmode-mv video --from work/storyboard.json --limit 1 --resolution 720p
fmode-mv video --from work/storyboard.json --mode still      # 零 API 费用，Ken Burns 兜底

# 数字人口播（替代唇形驱动）
fmode-mv jimeng digital-human --ref out/character/3-全身.png --audio work/audio/voiceover.mp3

# 通道自检（真跑一张图，¥0.20）
fmode-mv jimeng --test
```

## 七、工作流与产物

```
work/                       中间产物（.gitignore 已排除）
├── song.json               作曲填词结果
├── storyboard.json         ★分镜（下游全部消费它）
├── storyboard.md           人读版分镜表
├── script.json / .md       产线B 口播稿
├── audio/                  音乐、人声、伴奏、配音
├── scene/shot-XX.png       场景图（无人，v0.2 新增）
├── frames/shot-XX.png      关键帧（有人，供 video 消费）
├── clips/shot-XX.mp4       视频片段（兜底产物为 shot-XX.fallback.mp4）
├── clips/clips.json        每镜 method / workId / 费用 / 是否降级
├── workids.log             workId 台账（[时间戳] 类型 | workId: xxx | 内容: xxx）
├── lipsync/
└── subtitles.srt
out/
├── character/              ★人物资产（v0.2 新增）
│   ├── 1-定妆照.png … 4-多视图.png
│   ├── candidates/         全部候选（含锐度分数）
│   └── character-sheet.json
├── mv.mp4 / talk.mp4       成片
└── manifest.json           成片清单（含兜底片段数、BPM、音轨）
```

分镜结构见 `templates/storyboard.schema.json`。

## 八、知识库

本仓保留了两套知识，**分工明确**：

### 8.1 提炼文档（`references/`，**先看这里**）

| 文件 | 内容 | 来源 |
|---|---|---|
| `references/capability-matrix.md` | 能力矩阵（实测状态 + 替代方案） | 本仓实测 |
| `references/jimeng-api.md` | **即梦全部端点 + 三段式调用 + 上传 + 费用表 + 参数细节** | `kb-raw/07` + 实测 |
| `references/narrative-playbook.md` | 救猫咪15节拍 / 黄金三秒与嘴替式 / 10种爆款类型 / 人物弧光与冲突 / 前提公式 / 分镜设计 / 首尾帧设计 | `kb-raw/05` |
| `references/voc-sop-pipeline.md` | **VOC-SOP 五阶段** + 各阶段检测清单 + 合规/脱敏边界 | `kb-raw/04` |
| `references/production-evolution.md` | 版本1~6 方法演进 + **23 条踩坑清单** + 成本测算 + 成品案例库索引 | `kb-raw/06` `08` |
| `references/pipeline-a-song-mv.md` | 产线A 逐步命令 + 避坑 | 本仓 |
| `references/pipeline-b-talking.md` | 产线B 逐步命令 + 避坑 | 本仓 |
| `references/prompt-templates.md` | 提示词模板库（人读版） | 本仓 |

### 8.2 原始知识源（`kb-raw/`，**照抄细节时查这里**）

`kb-raw/` 保留了用户交付的原始知识库（约 6.8MB，284 个文件），**未做删改**，
供后续查阅原始脚本、完整案例、长篇文档：

| 目录 | 内容 | 什么时候用 |
|---|---|---|
| `kb-raw/04-SOP工作流/` | 视频脚本生成 / 变装视频生成两套完整 SOP（含 flow 模板与脚本） | 要照抄 SOP 原文、看变装流程 |
| `kb-raw/05-剧本与叙事知识库/` | 《故事》麦基、《救猫咪》Ⅰ/Ⅱ/Ⅲ 全书 + 创作技能包 + dbskill 知识包 | 要读编剧理论原文 |
| `kb-raw/06-制作方法演进/` | 版本1~6 全过程 + 多个真实案例（含脚本、分镜、文案） | 要看某个版本的具体脚本 |
| `kb-raw/07-即梦API工具箱/` | 即梦全部 API 脚本 + `参考文档/`（接口详解、资产生成记录） | 要查参数/端点的原始说明 |
| `kb-raw/08-成品案例库/` | VOC 商业洞察分镜文案、AI 微纪录片制作文档 | 找成品参考格式 |
| `kb-raw/README.md` | 知识库总说明与导航 | 先看这个定位 |

> ⚠️ **`kb-raw/` 内的脚本全部是历史原稿**，含**硬编码 token 与 Windows 绝对路径**，
> **不可直接运行**。它们只作为**参考与出处**存在。
> 要跑这些能力，请用本仓对应的 `fmode-mv` 命令（已改为运行时读凭据 + 参数化路径）。
> 唯一例外：`kb-raw` 里的 token 是用户自己仓库的历史遗留，**不是本仓引入的**；
> 本仓的新增代码（`lib/jimeng.mjs` 等）**不含任何明文凭据**。

## 九、设计要点（改代码前先看）

1. **provider 可插拔**：`lib/providers.mjs` 是唯一通道注册表。
   `image` / `video` 是旧网关通道，`jimeng` 是实测可用的新通道。
   换模型/换端点只需环境变量，**无需改代码**。
2. **人物一致性靠两层锚点**（v0.2 强化）：
   - 第一层：分镜里的 `appearanceAnchor`，逐镜头复述进 `imagePrompt`；
   - 第二层（**更硬**）：`character-sheet` 产出的人物**多视图**，直接作为图生图参考。
   改分镜逻辑时不要删掉任何一层。
3. **场景连续性靠「场景图 → 关键帧」两步法**：
   先生成干净环境（无人），再以「场景图 + 人物多视图」为参考合成关键帧。
   这样背景每镜一致、人物与背景光照不打架。
4. **参数本地预检**：即梦对参数错误是「先收下、后拒绝」（提交返回 200 + workId，
   轮询才报错）。所有尺寸/帧数在 `lib/jimeng.mjs` 里本地卡住，避免白等一轮。
   已知硬约束：`getImgV4` 面积 ≥ 1024²；视频 `frames ∈ {121,145,169,193,217,241}`。
5. **费用全程可视化**：`CostLedger` 在每次调用前打印预估、调用后打印实扣
   （优先采信接口返回的 `usage.cost`）。
6. **卡点用能量包络**：`lib/ffmpeg.mjs` 的 `detectBeats()` 纯 Node 实现，不依赖 aubio。
7. **兜底必须留痕**：所有降级产物带 `.fallback` 后缀或 `status: fallback` / `degraded: true`，
   报告里明说。用户永远能分清哪些是真 AI 生成、哪些是兜底。

## 十、许可

MIT，见 `LICENSE`。

---

**FmodeCode / FmodeAgent** · v0.2.0