|
|
@@ -0,0 +1,141 @@
|
|
|
+# HANDOFF.md — skill-mv 项目交接（下次直接接手）
|
|
|
+
|
|
|
+> 更新：2026-10-14 · 版本 v0.2.0 · 状态：**已挂起（用户指示暂停运行）**
|
|
|
+> 用途：任何数字生命 / 协作者克隆本仓后，按本文即可**零上下文接手，直接做下一步功能**。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 一、一句话现状
|
|
|
+
|
|
|
+纯 AI 视频技能已能从「一句主题」跑到「成片」，**即梦（火山引擎）真实通道已打通**（文生图 / 图生图 / 图生视频 / 动作模仿 / 数字人）。
|
|
|
+两条产线（A 音乐 MV / B 口播短视频）**端到端已跑通**；**AI 音乐 / TTS 两个网关通道未开通**，走「诚实降级 + 可插拔 provider」。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 二、快速接手（3 条命令）
|
|
|
+
|
|
|
+```bash
|
|
|
+git clone https://git.fmode.cn/fmode-13177980648/skill-mv.git
|
|
|
+cd skill-mv
|
|
|
+node bin/fmode-mv.js doctor # 环境自检：node / ffmpeg / 凭据 / 各通道
|
|
|
+node bin/fmode-mv.js providers # 能力现状表（--deep 做真实探活）
|
|
|
+node bin/fmode-mv.js --help # 全部命令
|
|
|
+```
|
|
|
+
|
|
|
+- **零依赖**：纯 ESM，`dependencies: 0`；只要 `node >= 18` + `ffmpeg`。
|
|
|
+- **凭据**：走环境变量 / `fmode-identity.json`，**仓内零硬编码**（见第六节）。
|
|
|
+- 只读诊断命令**不花钱**：`doctor` / `providers` / `version`。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 三、目录结构
|
|
|
+
|
|
|
+```
|
|
|
+bin/fmode-mv.js CLI 入口（song / talk / 各分步命令 / jimeng / doctor / providers / version）
|
|
|
+lib/ 核心库
|
|
|
+ api.mjs 网关调用（chat/image 等）
|
|
|
+ jimeng.mjs 即梦通道（文生图/图生图/图生视频/超清/动作模仿/数字人三步）★核心
|
|
|
+ providers.mjs 可插拔 provider + 能力现状 + ProviderUnavailableError
|
|
|
+ prompts.mjs 作曲填词/分镜/口播稿 的 prompt 模板
|
|
|
+ ffmpeg.mjs 剪辑/混音/字幕/响度归一化
|
|
|
+ sharpness.mjs 图片清晰度择优
|
|
|
+ doctor.mjs 环境自检
|
|
|
+scripts/ 各分步实现（lyrics/storyboard/character-sheet/scene/video/music/tts/lipsync/assemble…）
|
|
|
+ pipeline-a.mjs 产线A 端到端编排
|
|
|
+ pipeline-b.mjs 产线B 端到端编排
|
|
|
+references/ 方法论文档（capability-matrix / jimeng-api / pipeline-a|b / voc-sop / narrative-playbook …）
|
|
|
+templates/ prompt 模板
|
|
|
+assets/ 真跑样例资产（人物四视图/场景/关键帧/视频成片），供直观核验
|
|
|
+out/ 产物与真跑验证日志（*.log / REPORT-*.md 入库，大文件不入库）
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 四、能力矩阵（实测，非推测）
|
|
|
+
|
|
|
+| 通道 | 状态 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| chat（作曲填词/分镜/口播稿） | ✅ 可用 | 走网关 chat |
|
|
|
+| image（文生图） | ✅ 可用 | `gpt-image-2.5-sunburst` |
|
|
|
+| **即梦 jimeng** | ✅ **可用** | 文生图 / 图生图 / 图生视频 V3 720p **¥0.28/秒** / 超清 / 动作模仿 / 数字人 |
|
|
|
+| 剪辑合成 | ✅ 可用 | 本地 ffmpeg（拼接/混音/字幕/卡点/响度归一化 I=-14 LUFS） |
|
|
|
+| AI 音乐 | ❌ 未开通 | `/suno/*` 实测 503；可 `--music your-song.mp3` 自备 |
|
|
|
+| 图生视频（旧网关） | ❌ 未开通 | `/v1/video/generations` 503；**已改即梦** |
|
|
|
+| 唇形驱动 | ❌ 无路由 | **可用即梦数字人 `getOmniHuman` 替代**（代码已实现三步流水线） |
|
|
|
+| TTS 口播配音 | ❌ 未开通 | 网关无 `/v1/audio/speech`；本容器 edge-tts 实测 403 |
|
|
|
+
|
|
|
+**降级承诺**：未开通通道一律抛 `ProviderUnavailableError`（退出码 3）+ 可操作指引；图生视频不可用时自动降级「关键帧 + Ken Burns」，产物名带 `.fallback`。**绝不静默失败、绝不伪造产物。**
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 五、真跑证据（v0.2 实测，可复核）
|
|
|
+
|
|
|
+| 项 | 值 |
|
|
|
+|---|---|
|
|
|
+| 定妆照（3 候选择优） | ¥0.60 |
|
|
|
+| 图生视频（即梦 1 镜） | ¥1.41 |
|
|
|
+| 场景图（无人） | ¥0.20 |
|
|
|
+| 关键帧（有人） | ¥0.22 |
|
|
|
+| **产线A 单次真跑合计** | **≈ ¥2.43** |
|
|
|
+| 成片 | `assets/video/mv-final.mp4`（1280×720 / 18s / H.264 含烧字幕） |
|
|
|
+| 即梦单镜 | `assets/video/shot-01-jimeng.mp4`（832×1120 / 5.04s） |
|
|
|
+
|
|
|
+验证日志全部入库：`out/verify-pipeline-a.log`、`out/verify-pipeline-b.log`、`out/verify-character-sheet.log`、`out/verify-scene.log`、`out/verify-video.log`、`out/verify-providers.log`。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 六、环境与凭据（零硬编码）
|
|
|
+
|
|
|
+| 变量 | 用途 |
|
|
|
+|---|---|
|
|
|
+| `FEME_API_KEY` | 网关 API key（chat/image 等） |
|
|
|
+| `FEME_API_ENDPOINT` | 网关地址（默认 `https://api.fmode.cn`） |
|
|
|
+| `FEME_SESSION_TOKEN` | 即梦通道鉴权（`/api/volcengine/jimeng/*`） |
|
|
|
+| `FEME_USERID` | 个人空间 userid（S3 发布路径） |
|
|
|
+| `FEME_TTS_ENDPOINT` | 可选：外部 TTS 服务 |
|
|
|
+| `--music <file>` / `--voice <file>` | 自备音频绕过未开通通道 |
|
|
|
+
|
|
|
+也可放 `fmode-identity.json`（**已 .gitignore，绝不入库**）。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 七、下一步可直接接手的功能（按优先级）
|
|
|
+
|
|
|
+> 均为**增量**，不影响现有链路；建议仍按「先出工作内容要求+产出要求 → 派 FmodeCode 执行」推进。
|
|
|
+
|
|
|
+1. **【最高价值】AI 音乐通道替代**
|
|
|
+ - 现状：`/suno/*` 503。方向：① 申请开通该通道；② 对接外部音乐生成 API（可插拔 provider 已就绪）；③ 走即梦音频能力。
|
|
|
+ - 落地：新增 `lib/providers/music-<x>.mjs` + 在 `providers.mjs` 注册，`--music` 保留自备兜底。
|
|
|
+
|
|
|
+2. **【最高价值】TTS 口播配音**
|
|
|
+ - 现状：网关无路由 + edge-tts 在部分云环境 403。
|
|
|
+ - 方向：① `FEME_TTS_ENDPOINT` 对接外部 TTS；② 容器内装本地 TTS（如 piper/sherpa）；③ 复用即梦数字人自带配音。
|
|
|
+ - 落地：`scripts/tts.mjs` 加 provider 分支，未配置时保持 `unavailable`。
|
|
|
+
|
|
|
+3. **口腔/唇形**：把 `scripts/lipsync.mjs` 从「未开通」接到**即梦数字人 `getOmniHuman` 三步**（`lib/jimeng.mjs` 已实现 ohIdentify/ohDetect/omniHuman，只需在产线B 编排里串起来）。
|
|
|
+
|
|
|
+4. **产线A 音乐一键替换人声轨**（老板级需求「产线B：把歌曲人声轨换成口播音频 + 人物讲解 + 场景切换」）：写 `scripts/voice-swap.mjs`，用音频对齐 + ffmpeg 混音。
|
|
|
+
|
|
|
+5. **多镜批量 + 成本护栏**：`--limit` / `--budget` 参数，超过预算即停并报告（当前已能单镜试跑）。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 八、已知问题 / 坑（接手必读）
|
|
|
+
|
|
|
+1. **即梦「图片生成 4.0」多图参考合成关键帧**报 `height or width invalid`（¥0，非扣费失败）
|
|
|
+ → 现为**单图参考降级**，已如实标注，未伪造。修法：核对 4.0 尺寸约束或拆分为两次单图调用。
|
|
|
+2. **`.png` 命名瑕疵**：定妆照/场景图部分实为 JPEG 内容而命名 `.png`（工具链小 bug，不影响使用）。
|
|
|
+ → 修法：写图时按 `file` 实际类型定扩展名（`lib/jimeng.mjs` 落盘处）。
|
|
|
+3. **重跑会复用缓存**：`out/character/*`、`work/scene/*`、`work/clips/*` 存在时默认跳过（显示「已存在，跳过」，花费 ¥0.00）——**要真重跑加 `--force`**。若日志显示「成功 0 / ¥0.00」而你以为在真跑，就是命中了缓存，不是 bug。
|
|
|
+4. **`out/` 大文件不入库**（.gitignore：`out/*`，仅放行 `REPORT-*.md` / `verify-*.log` / `git-push.log`）。
|
|
|
+5. **仓库当前为公开**（`fmode-13177980648/skill-mv`，含人像资产）。若需私有化：改私有或迁到 `skill-wangyong`。
|
|
|
+6. **对象存储 key 大小写敏感**：`IGzPRXKpzm` 小写化即 404；发布 key 必须 ASCII（中文 key 被云函数静默拒）。
|
|
|
+7. **CDN 缓存**：同名 key 覆盖后裸链 30 天内回旧内容，须带 `?t=` 或换新 key。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 九、权威核验值（拉取前后对账）
|
|
|
+
|
|
|
+- 远程 `master` = `4929359` · 本地 HEAD = `4929359` · 工作区干净（提交后三者一致）
|
|
|
+- 仓地址：`https://git.fmode.cn/fmode-13177980648/skill-mv`（公开）
|
|
|
+- 资产目录：`https://git.fmode.cn/fmode-13177980648/skill-mv/tree/master/assets`
|
