Files
ai-manju/SKILL.md
T
rong a8e10b7b17 fix: 字幕按实测发声段对齐 + 静音镜/包装踩坑 (v1.2.1)
- 纠正 render.md/pitfalls.md「按设计时间缩放字幕」错误做法,改为只认实测发声段
- 新增 scripts/align_subtitles.py(泛化对齐工具,配置外置、支持 dump-segs/init-config/dry-run)
- render_native.py 加 --ass 参数,读对齐 ASS 不被内置设计时间轴覆盖
- pitfalls/native-av/README/SKILL 补六条踩坑;install.sh 清单同步
2026-11-19 17:14:14 +08:00

19 KiB
Raw Blame History

name, description, metadata
name description metadata
ai-manju 用文件驱动、可校验、可单镜重做的流水线制作 AI 漫剧 / AI 短剧:从源节拍账本、结构化分镜、逐镜提示词、角色锚图与图生视频,到配音、字幕、HUD 缝合与成片归档。人物台词镜头走音画同出(原生对白口型),不做后期 lip-sync。 Trigger on: "AI漫剧" "漫剧" "AI短剧" "短剧" "分镜" "分镜表" "图生视频" "出片" "配音" "缝合" "镜头表" "口型" "对白" "lip-sync" "manju" "comic drama" "storyboard" "image to video"。
version upstream changelog
1.1.0 Toonflow workflow v2.7.0 (MIT) 方法论,已剥离宿主耦合;原文见 references/toonflow/ 1.1.0 (2026-11-17):新增 H3 音画同出路线(192.168.1.23:30121 / K100 64GB)+ native-av 参考 + queue/fetch 长任务编排;明确禁止事后 lip-sync;补 30121 内存态队列丢失与 /api/free 崩溃两条硬约束。

ai-manju — AI 漫剧流水线

把「剧本 → 分镜 → 首帧图 → 图生视频 → 配音 → 缝合 → 归档」做成文件驱动、机器可校验、任何一镜可单独重做的轻量管线。

定位先行:这是一个编排层,不是一键出片工具,也不部署重型工作台。

  • 本机只做:目录/清单/校验/提示词/ASS 字幕/ffmpeg 缝合。
  • 首帧图:内网 MiniMax H3-Image 文生图 → tools/submit_t2i.py;脚本自动探测权重名,端点或权重变了不用改代码。 也可用宿主 Agent 的图像能力(会消耗外部积分)。
  • 人物说话的镜头 → 走音画同出:192.168.1.23:30121(DCU K100 64 GB)的 MiniMax H3 fl2va, 首帧锁图 I2V + 原生对白/环境音,口型模型内对齐。tools/submit_h3_native.py / queue_h3_native.py / fetch_h3_native.py → references/native-av.md。不要再做事后 lip-sync(三条路线实测全废,理由见该文 §1)。
  • 无声动作镜头 / 批量抽卡:Wan2.2 I2V A14B(4 步、无音轨,tools/submit_i2v.py)。
  • 2080Ti 22 GB 实例 192.168.1.30:30113 仍可用出图与 H3 T2V,但该卡 I2V 必 OOM,台词镜头别往这里塞。
  • 策划阶段可借内网 LLM 代理拆剧本(可选);向量服务 embed-bge 已随旧 DCU 下线,暂无替代。
  • 端点、节点图、0.45/0.38 差异全表见 references/models.md; 部署拓扑、4 GiB 墙、补丁集与 pod 重建后的恢复步骤见部署侧文档 ~/WorkBuddy/2026-11-08-19-43-52/deploy/k8s-nvidia/deploy-as-built.md(不在技能包内,部署与使用刻意分开)。

⚠️ 2026-11-17 服务状态:两台 ComfyUI 0.45 在线,按卡分工。 30113(K8s,2080Ti 22 GB + 4 GiB cgroup)= 出图 / A14B / H3 T2V;30111/30112 是它的别名(旧 deployment 已 scale 0), pod 重建后必须跑 /basedir/apply-multimodal.sh,否则只剩出图能力。 30121(DCU K100 64 GB)= 台词镜主力(H3 音画同出 I2V)+ 出图 + A14B 全套权重;禁调 /api/free(会崩服务)。 旧 DCU 192.168.1.24 整机不可达(30120 / 8801 TCP 均 CLOSED),embed-bge 向量服务随之消失,别与 30121 混为一谈。 开工前先跑下面的健康自检,别照着旧文档连已下线的端点。

何时用

  • 要做一集 AI 漫剧 / 短剧 / 动态漫画,需要可回溯的分镜与提示词资产。
  • 已有剧本,需要拆成逐镜提示词并批量生成、审片、缝合、归档。
  • 需要「改第 3 镜不动其余镜头」的可重做工作流。
  • 不想把提示词、锚图、片段、成片堆在一个目录里靠记忆管理。

先决条件(一次性)

python3 -V                                  # 脚本只用标准库
pip install --user imageio-ffmpeg           # 渲染/审片用的静态 ffmpeg;不要 brew 装
pip install --user edge-tts                 # 配音(免费免密钥)

再准备:① 内网端点可达(台词镜主力 192.168.1.23:30121(64 GB)已预填进 nativeVideoModel;出图/静音动作用 192.168.1.30:30113;30111/30112 是 30113 的别名;旧 DCU 30120 已下线,别与 30121 混);② LLM 代理若要用,密钥走 xop run --secret K=llm_key -- CMD < /dev/null,不落明文。开工自检:

# 台词镜主力(64 GB):必须看到 H3 视频 + H3 图像两套权重
U=192.168.1.23:30121
curl -s --noproxy '*' -m 8 "http://$U/system_stats" | head -c 120; echo
curl -s --noproxy '*' -m 8 "http://$U/object_info/UNETLoader" | python3 -c "
import json,sys
d=json.load(sys.stdin)['UNETLoader']['input']['required']['unet_name'][0]
print(len(d),'models:',d)
assert any('fl2va' in x for x in d), '缺 H3 视频权重 → 台词镜跑不了'
"

# 出图 / 静音动作(22 GB):必须看到 4 个扩散模型(H3 图 / H3 视频 / WAN high+low)
U=192.168.1.30:30113
curl -s --noproxy '*' -m 8 "http://$U/object_info/UNETLoader" | python3 -c "
import json,sys
d=json.load(sys.stdin)['UNETLoader']['input']['required']['unet_name'][0]
print(len(d), 'models:'); [print('  ', x) for x in d]
"
# 少于 4 个 = pod 重建后 /local 软链丢了(不是模型坏了)→ 跑 /basedir/apply-multimodal.sh

⚠️ 内网是明文 HTTP,本机代理会把响应改成 text/html:curl 必须 --noproxy '*',Python 必须 ProxyHandler({})。

快速开始

mkdir my-drama && cd my-drama
python3 ~/.agents/skills/ai-manju/scripts/manju.py setup   # 建目录 + 配置模板 + 复制脚本
# 编辑 config/pipeline.json:填 workspace、tts.voice;端点已预填(台词镜 30121 / 出图与静音镜 30113),按需切换
python3 tools/manju.py init EP01                            # 建一集骨架
# 填 00_brief.md / 10_events.md / 20_script.md / 30_shots.json / 40_prompts/
python3 tools/manju.py validate projects/EP01/30_shots.json # ERROR 必须为 0

之后按七阶段推进。任何会消耗算力或积分的步骤,生成前必须展示清单并取得明确授权——"继续"、沉默、工具失败都不算新授权。

七阶段路由

# 阶段 主要产物 用哪个脚本 / 参考
0 基线资产 角色锚图、画风描述、HUD/落版模板 tools/submit_t2i.py(H3-Image);tools/make_overlay.py;references/models.md §2;references/storyboard.md
1 策划与叙事 00_brief.md、10_events.md、20_script.md assets/policy.template.md;references/director.md
2 分镜中枢 30_shots.json、40_prompts/Sxx.i2v.txt manju.py validate;references/director.md
3 配音先行(仅无音轨镜) work/EPxx/audio/vo_NN.mp3 tools/tts.py;实测时长回填 duration。⚠️ 走音画同出的台词镜跳过此阶段,别叠双份人声
4 出图 / 出视频 work/EPxx/{images,videos}/Sxx_<hash8>.*、videos/native/Sxx.mp4 台词镜:tools/queue_h3_native.py + fetch_h3_native.py(native-av.md);静音镜:tools/submit_i2v.py(A14B);出图:tools/submit_t2i.py;导出后 tools/cleanup_comfyui.py
5 缝合 renders/EPxx_成片.mp4 台词镜(原生音轨):先 tools/align_subtitles.py(字幕对齐实测发声段,别照设计时间)再 tools/render_native.py;无音轨镜:tools/render.py;references/render.md
6 审片与归档 renders/INDEX.md、50_manifest.json tools/review.py;references/review.md

完整闸门与输出契约见 references/workflow.md,字段定义见 assets/shot.schema.json。

内网模型路由(开工前先选)

要什么 用哪个 端点 脚本 / 文档
人物有台词的镜头(首选) MiniMax H3 fl2va 音画同出 I2V(576×1024 / 24fps / 20 步 / 原生 aac 对白) 192.168.1.23:30121(K100 64 GB) tools/queue_h3_native.py + fetch_h3_native.py;必读 native-av.md
角色锚图、分镜首帧 MiniMax H3-Image(30113 用 int8_convrot / 30121 用 w4a8,2048² 起 / 6 步 euler) 192.168.1.30:30113 或 192.168.1.23:30121(权重自动探测) tools/submit_t2i.py;models.md §2 / §4.4
静音动作镜头、批量抽卡 Wan2.2 I2V A14B(832×480 上限 / 81 帧 / 4 步 / 无音轨) 30113(30121 也有同一套权重但要在视频队列后等) tools/submit_i2v.py(已封装);submit-i2v.md
只需环境音、无对白的镜头 MiniMax H3 T2V(w6a8,20 步、无 LoRA,原生 aac 音轨)⚠️ 仅文生视频,别塞 first_frame 30113(22 GB 只能 T2V) 手写节点图;models.md §4.3
拆剧本、扩写提示词 LLM 代理(需 xop 密钥、按 slot 前缀路由) 192.168.1.30:30084 models.md §5.1
设定检索、去重 embed-bge(免密钥,模型名 BAAI/bge-large-zh-v1.5)⚠️ 已下线 192.168.1.24:8801 models.md §5.2

五条铁律:① I2V 看卡不看端口——first_frame 只有 64 GB 的 30121 扛得住,30113(22 GB)塞进去必 OOM; ② 30113 的图 / H3 T2V / A14B 三种模态共用一个实例(1 张 2080Ti + 4 GiB 内存硬限),只能串行,并发必 OOM; ③ 换视频模型不能只改 endpoint,两套节点图/权重/输出节点都不同(H3 走 SamplerCustomAdvanced,WAN 走 KSamplerAdvanced×2 + ModelSamplingSD3); ④ 出图量化档位不能照搬:ROCm(30120/30121)只能 w4a8、K8s-30113 只能 int8_convrot —— 搞反了会静默出纯色图; ⑤ 30121 禁调 /api/free(会崩服务自愈),queue/history 是内存态(实例重启就静默丢任务)。

出图怎么跑(阶段 0 / 阶段 4)

# 权重不用填:脚本读端点 /object_info/UNETLoader 自动挑,端点换了不用改代码
python3 tools/submit_t2i.py --ep EP01 --shot S01 --prompt-file projects/EP01/40_prompts/S01.t2i.txt
python3 tools/submit_t2i.py --prompt "A lone figure on a misty pier, ..." --out assets/characters/ling.png

输出落在 work/EPxx/images/Sxx.png(正是 submit_i2v.py 期望的首帧路径)。 脚本出图后会自动做 PNG 自检(颜色数/亮度/标准差),纯色图判失败、退出码 1、跳过自动清理(保留服务端产物当排查证据):

[SANITY] work/EP01/images/S01.png -> ok(2048x2048, 168733 colors, mean=72.3, std=57.8)

出图成功不等于内容正确 —— 量化档位不对时 ComfyUI 不报错,只是出纯色图。必须看 [SANITY] 行。

台词镜怎么跑(阶段 4 的另一条腿)

# ① 一次排完整集(不等待;单镜 ≈ 90 min,8 镜 ≈ 12 h)
python3 tools/queue_h3_native.py --ep EP01
# ② 随时查(服务端成功一个就能取回一个)
python3 tools/fetch_h3_native.py --ep EP01 --status
# ③ 取回;脚本会顺手检查 mp4 里到底有没有 aac 音轨
python3 tools/fetch_h3_native.py --ep EP01
# ④ 全部取回后先按【实测发声段】对齐字幕(🔴 别照 [Audio] 设计时间,会早 0.5-1.5s)
python3 tools/align_subtitles.py projects/EP01/30_shots.json --dump-segs                  # 看每镜发声段
python3 tools/align_subtitles.py projects/EP01/30_shots.json --init-config work/EP01/align_config.json
#   人工校准 align_config.json 的 ALIGN 段映射(详见 references/render.md「字幕对齐」)
python3 tools/align_subtitles.py projects/EP01/30_shots.json --config work/EP01/align_config.json --dry-run
python3 tools/align_subtitles.py projects/EP01/30_shots.json --config work/EP01/align_config.json \
    --out work/EP01/render_native/ep.ass
# ⑤ 缝合:直拼保留原生音轨 + 烧对齐后的 ASS + 可选瑕疵遮盖
python3 tools/render_native.py projects/EP01/30_shots.json \
    --ass work/EP01/render_native/ep.ass --mask   # --ass 关键,否则会用设计时间轴覆盖对齐字幕

两条缝合路线别混:台词镜(原生 aac 音轨)只能走 render_native.py, 给原生音画镜套 render.py 会叠双份人声、强加落版、强改 720×1280 掉画质。 无音轨镜/旁白镜才走 render.py。出图脚本被杀后的单图救回用 fetch_t2i.py --pid <pid> --out <path>。 详见 references/render.md 与 references/pitfalls.md。

提示词写 projects/EP01/40_prompts/<SHOT>.h3v3.txt(五段式:[Visual]/[Motion]/[Camera]/[Audio]/[Narrative]), 台词按秒级时间轴写进 [Audio],并写 Only <name> speaks。分镜时长必须吸附 17k+5 帧网格(124–362 帧是训练区间)。 台词改了要重排该镜 —— 原生音轨不可编辑。全流程与踩坑见 references/native-av.md。

⚠️ [Audio] 里的秒数只是设计值,用来引导模型出声,不是实际发声时间(H3 会自行调整语速/停顿)。 它可以直接指导生成,但绝不能照搬当字幕时间轴——字幕必须另走 align_subtitles.py 按实测发声段对齐。

十条不能让渡的规则

  1. 资产先行:角色锚图/画风/HUD 先定稿并锁为只读,再进入分镜。
  2. 分镜驱动:30_shots.json 是单一真相源,一镜一行,每个动作映射回 E## 源节拍。
  3. 提示词原文留档:40_prompts/Sxx.i2v.txt(或 .h3v3.txt)一字不改;改词即换哈希、生成新文件,旧版不覆盖。
  4. 配音先于剪辑:先量实测时长再回填 duration,禁止加快语速硬塞。例外:走音画同出的台词镜不跑 TTS,时长由帧数网格决定。
  5. 单镜重做:漂移只重跑/截取该镜,不推倒整条时间线;keepSeconds 可截稳定前段慢放。
  6. 状态诚实:区分「已生成 / 已采用 / 已合成 / 已归集」,不把文件路径当"看过视频"。
  7. 端点不照搬:换模型先查 /system_stats 与 /object_info,按目标服务的 ComfyUI 版本与显卡写节点图;明文 HTTP 一律绕代理,/prompt 一律包 {"prompt": ...} 外层。
  8. 台词不做后期贴嘴:人物说话的画面,必须由音画同出的模型生成(H3 fl2va + 首帧锁图)。 Wav2Lip(96² 贴回)、LatentSync(环境装不下)、InfiniteTalk(78 min 一镜 / 油画感 / 身份漂移)三条路线已实测否掉: 贴嘴的画质上限由 lip-sync 模型决定,不是由你的锚图决定。没有 64 GB 卡时才考虑降级,且要如实说明成片天花板。
  9. 导出即清(只清自己发起的任务):成片拉回本地并校验大小后,必须清掉 ComfyUI 服务端的 history / queue 记录与本次产物文件(output / temp,上传首帧按需)。只清服务端——本地成片、40_prompts/ 提示词原文、50_manifest.json 一律保留。默认走 tools/cleanup_comfyui.py(先 dry-run 再 --apply):先按台账 clientId + client_id 白名单判归属(requireOwner=true 时未通过一律拒绝,不调任何删除接口),再用官方 /api 标准接口批量删记录并删后复核(200 空 body 是幂等响应,不等于删成功)。产物文件官方没有 HTTP 删除接口,优先用技能自带扩展 assets/comfyui-manju-cleanup/ 的 POST /manju/cleanup/purge(只传 pid,服务端从 history 反查文件、二次校验归属、防路径逃逸与跨任务共用),未装则降级 cleanup.deleteApi / cleanup.commands。装了扩展时顺序是「先删文件再删记录」(purge 依赖 history 反查,记录删了就查不到文件名)。两个提交脚本加 --cleanup 可在导出后自动触发;没清成要如实说,不能把「已下载」当「已清理」。见 models.md §3.4。 例外:出图自检未通过(纯色图)时不清服务端 —— 保留 history 与产物当排查证据,脚本已自动跳过。 扫描范围:清理脚本递归扫工作空间下所有 t2i_runs.json / a14b_runs.json(台账写在图片同目录,位置随 --out 变)。不带 --ep 跑一次才能把角色锚图等集外任务一起清掉;只跑 --ep EP01 会漏掉它们。每个任务按台账里记录的实际端点去清,不会清错地方。
  10. 长任务排队、不挂进程:单镜 90 分钟级,一律「排队 → 落盘 pid → 事后取回」。queue/history 都是内存态, 实例一重启排队的任务就静默消失(实测 7 镜全丢),排完 5 分钟内必须做一次 /queue 存在性自检。

审片与漂移处理(核心经验)

I2V 对静止镜头极易脑补动作:人物必抬手/转正,细光必变光柱,节点必增生。

  • 先抽首/中/末帧(tools/review.py 出联系表)判定漂移类型。
  • 姿态/场景漂移 → keepSeconds 截前 1.2–2.5s 稳定段慢放到目标时长,比反复抽卡省时间。
  • 硬伤(首帧带乱码文字被重绘、手部畸形)→ 必须换首帧图重跑,改提示词没用。
  • 正向锁写成可判定状态:"双臂垂在体侧 / 细光保持细线永不宽成走廊 / 双手不触及不跨越",禁止句放最后。

完整清单见 references/pitfalls.md。

目录约定

工作空间/
├── config/pipeline.json        # 模型端点、音色、输出规格(可入库的放这里)
├── config/local.json           # 环境相关,gitignore;密钥不落明文
├── assets/                     # 跨集只读基线:characters/ scenes/ props/ style/ overlay/
├── projects/EPxx/
│   ├── 00_brief.md  10_events.md  20_script.md
│   ├── 30_shots.json             # ★ 单一真相源
│   ├── 40_prompts/Sxx.i2v.txt    # 逐镜提示词原文(台词镜另有 Sxx.h3v3.txt 五段式,并存不覆盖)
│   └── 50_manifest.json          # 产物索引:路径/参数/状态/attempts
├── work/EPxx/
│   ├── images/  videos/  audio/  render/  render_native/  review/  # 可重建产物,不入库
│   └── videos/native/            # 音画同出产物 + _queue_map.json / _h3av_ledger.json
├── renders/INDEX.md              # 成片只留索引,本体不入库
└── tools/                        # setup 复制进来的脚本(含 submit_t2i / fetch_t2i / submit_i2v / submit_h3_native / queue_h3_native / fetch_h3_native / render / render_native / align_subtitles / cleanup_comfyui)

路径解析:所有脚本按 MANJU_ROOT 环境变量 → 从 cwd 向上找 config/pipeline.json → 脚本上级目录 的顺序定位工作空间。因此先 cd 到工作空间根再运行脚本;也可显式设 MANJU_ROOT=/abs/path。

终止规则

最终回复说明:做成了什么、真实文件在哪、哪些内容由谁核验、唯一必要的下一步。生成前展示清单、生成后据实登记,不夸大状态。