Domů Procházet Nápověda
Přihlásit se
fmode-13177980648
/
skill-mv
1
0
Rozštěpit 0
Soubory Úkoly 0 Pull Requesty 0 Wiki
Strom: 25fa48786b
Větve Značky
skill-mv
/
HANDOFF.md

HANDOFF.md 7.8 KB
Historie Surový

HANDOFF.md — skill-mv 项目交接（下次直接接手）

更新：2026-10-14 · 版本 v0.2.0 · 状态：已挂起（用户指示暂停运行） 用途：任何数字生命 / 协作者克隆本仓后，按本文即可零上下文接手，直接做下一步功能。

一、一句话现状

纯 AI 视频技能已能从「一句主题」跑到「成片」，即梦（火山引擎）真实通道已打通（文生图 / 图生图 / 图生视频 / 动作模仿 / 数字人）。 两条产线（A 音乐 MV / B 口播短视频）端到端已跑通；AI 音乐 / TTS 两个网关通道未开通，走「诚实降级 + 可插拔 provider」。

二、快速接手（3 条命令）

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