按卡选活的对照表:什么活该用哪台机、哪个端点。 覆盖高频踩坑点: - H3 的 I2V 看卡不看端口:30113(22GB) 塞 first_frame 必 OOM,要首帧锁图用 A14B, 要台词口型用 30121(64GB) - 30113 一卡一实例 + 4Gi 内存墙,图/视频/A14B 只能串行;连续出图 30 张会崩 - H3 视频固定配方:20 步 / res_multistep+simple / cfg1.0 / 无 LoRA - 两端出图量化档方向相反(30113=int8_convrot, 30121=w4a8),搞反静默出纯色图 - 30121 禁调 /api/free;queue/history 是内存态,实例重启任务静默全丢 - 附 30 秒开工自检(端点/队列/权重三查) install.sh 完整性清单同步;SKILL.md 五条铁律处加引用。
ai-manju — 同事上手指南
一条流水线把剧本做成 AI 漫剧 / 短剧成片:源节拍 → 分镜 → 首帧图 → 图生视频(台词镜走音画同出)→ 配音/字幕 → 缝合 → 归档。 特点是文件驱动、机器可校验、任何一镜可单独重做。工具脚本只用 Python 标准库。
2026-11-19 v1.2.1:新增
align_subtitles.py(字幕按实测发声段对齐,修「字幕与口型错位」)—— h3v3[Audio]的秒数只是设计值,照抄当字幕时间轴会早 0.5–1.5 s。render_native.py新增--ass读对齐后的 ASS。 同时沉淀三条踩坑:静音镜自发吐音需volumedetect核验后静音、包装叠字统一BorderStyle=1免蓝底白字、角标文案勿与对白重复。详见 render.md「字幕对齐」。2026-11-19 v1.2.0 关键变化:补齐原生音画镜的出片闭环。 新增
render_native.py(台词镜专用缝合器:直拼保留原生音轨、烧 ASS 字幕、可选瑕疵遮盖,不叠 TTS / 不加落版 / 保持 576×1024)、fetch_t2i.py(出图脚本被杀后按 pid 从服务端救回单图);修复queue_h3_native.py --check把「被中断/error」误判为"在队"的 bug。 缝合前先分流:台词镜走render_native.py,无音轨镜走render.py,两者不要混。见 references/render.md。2026-11-17 v1.1.0:人物说话的镜头不再事后贴嘴。 走
192.168.1.23:30121(DCU K100 64 GB)的 MiniMax H3fl2va音画同出:首帧锁图 I2V, 画面 / 人声 / 环境音一次出,口型模型内对齐。submit_h3_native.py/queue_h3_native.py/fetch_h3_native.py与 references/native-av.md。Wav2Lip / LatentSync / InfiniteTalk 三条事后贴嘴路线已实测否掉。
1. 安装(一次性)
把本目录放到 ~/.agents/skills/ai-manju/,然后:
cd ~/.agents/skills/ai-manju
chmod +x install.sh
./install.sh # 软链到 ~/.claude/skills、~/.workbuddy/skills、~/.qwenworkcn/skills
./install.sh --check # 随时只读体检
如果不用多端软链,直接把整个 ai-manju/ 目录拷到任一 agent 的 skills/ 下也能用。
依赖(只在配音/渲染阶段需要):
pip install --user imageio-ffmpeg # 静态 ffmpeg;不要 brew 装(macOS 12 + Homebrew 6 有 dav1d bug)
pip install --user edge-tts # 免费免密钥配音;商用授权自行核对微软条款
python3 -V # 脚本本身零第三方依赖
另需准备:内网模型端点可达(模板已预填:台词镜 192.168.1.23:30121,出图/静音镜 192.168.1.30:30113)。开工自检:
for U in 192.168.1.23:30121 192.168.1.30:30113; do
printf "%-24s" "$U"; curl -s --noproxy '*' -m 8 "http://$U/system_stats" | head -c 60; echo
done
明文 HTTP 会被本机代理改写成 text/html,curl 要 --noproxy '*',Python 要 ProxyHandler({})。端点全表见 references/models.md。
⚠️ 两台机器分工(2026-11-17):
30121= DCU K100 64 GB,H3 音画同出 I2V(台词镜)+ 出图 + A14B 全套权重;禁调/api/free(会崩服务)。30113= K8s 2080Ti 22 GB,出图 / A14B / H3 T2V;该卡 I2V 必 OOM。 2026-11-19 实测补:30 实为 RTX 2080 Ti / 23.1 GB 显存(4 GiB 是 cgroup 内存限),出图用int8_convrot但单张约 190s(DCU 23 约 52s,慢 4 倍);连续出图后服务三个端口会整体 Connection refused,台词镜别排这里,回退 30121。 旧 DCU192.168.1.24(30120)仍整机不可达,与 30121 不是一台机;embed-bge(8801)随之下线。
2. 建工作空间
mkdir my-drama && cd my-drama
python3 ~/.agents/skills/ai-manju/scripts/manju.py setup
setup 会建好目录、写入 config/pipeline.json 模板、把 scripts/ 下全部脚本复制到 tools/(含出图救回与两条缝合器)、把模板与 schema 放到 assets/templates/。
接着必须编辑 config/pipeline.json:填 workspace、tts.voice。videoModel / imageModel / textModel / embed 四段已预填内网地址,按需切换(注意:embed 段的 8801 已随 DCU 下线,当前无可用向量服务);cleanup 段配导出后的服务端清理策略(默认 auto: false、requireOwner: true:只清自己发起的任务)。产物文件官方没有删除接口,把技能包 assets/comfyui-manju-cleanup/ 拷到各端点的 ComfyUI/custom_nodes/ 并重启即可启用扩展(不装会自动降级到 deleteApi / commands),详见 models.md §3.4。密钥绝不写进配置 —— LLM 代理走 xop run --secret K=llm_key -- CMD < /dev/null。
之后所有脚本都在工作空间根运行(
cd my-drama)。脚本按MANJU_ROOT→ cwd 向上找config/pipeline.json→ 脚本上级 的顺序定位工作空间。
3. 做一集
# ① 骨架
python3 tools/manju.py init EP01
# ② 填内容(都是 Markdown / JSON,按文件里的提示写)
# projects/EP01/00_brief.md 任务卡:时长、冲突、角色、画风、禁忌
# projects/EP01/10_events.md 源节拍账本:一行一个 E##
# projects/EP01/20_script.md 剧本/旁白全文
# projects/EP01/30_shots.json 分镜表(单一真相源,一镜一行)
# projects/EP01/40_prompts/S01.i2v.txt 逐镜运动提示词原文(静音镜)
# projects/EP01/40_prompts/S01.h3v3.txt 逐镜五段式提示词(台词镜:含秒级台词时间轴)
# ③ 校验:ERROR 必须为 0
python3 tools/manju.py validate projects/EP01/30_shots.json
# ④ 基线资产:内网 H3-Image 出角色锚图 → assets/characters/;HUD/落版用脚本生成
python3 tools/submit_t2i.py --prompt "角色设定长描述..." --out assets/characters/ling.png
python3 tools/make_overlay.py
# ⑤ 配音(**只给无音轨镜/旁白**):生成 vo_NN.mp3 并把实测时长回填 duration
python3 tools/tts.py projects/EP01/30_shots.json
# 台词镜走音画同出,不跑 TTS、不要叠双份人声
# ⑥ 首帧图:内网 H3-Image 出图 → work/EP01/images/Sxx.png(正好是 ⑦ 读取的路径)
python3 tools/submit_t2i.py --ep EP01 --shot S01 --prompt-file projects/EP01/40_prompts/S01.t2i.txt
# 看 [SANITY] 行:ok(...) 才算可用;判 FAIL(纯色图)说明量化档位/端点选错了,别重跑
# (DCU 禁 int8_convrot,K8s-30113 只能用 int8_convrot)
# (也可用宿主 Agent 的图像能力,但会消耗外部积分;出图后审一遍再进 ⑦)
# ⑦ 图生视频:先审首帧,再提交(会消耗算力,先取得授权)
python3 tools/submit_i2v.py projects/EP01/30_shots.json --only S01 # 静音镜,先跑一镜验证
python3 tools/submit_i2v.py projects/EP01/30_shots.json --cleanup # 全量,每镜导出后自动清服务端
# ⑦n 台词镜(音画同出):排队 → 自检 → 取回。单镜约 90 分钟,别挂进程等
python3 tools/queue_h3_native.py --ep EP01 # 排完整集,落盘 prompt_id
python3 tools/queue_h3_native.py --ep EP01 --check # 5 分钟内做一次丢失自检(实例重启会静默清空队列)
python3 tools/fetch_h3_native.py --ep EP01 --status # 只看状态
python3 tools/fetch_h3_native.py --ep EP01 # 取回,顺手检查有没有 aac 音轨
# ⑦b 导出后清理(若没加 --cleanup,或要复核清了什么)
python3 tools/cleanup_comfyui.py --ep EP01 # 预演:逐条打印归属判定 + 将删清单
python3 tools/cleanup_comfyui.py --ep EP01 --apply # 真清(含删后复核)
python3 tools/cleanup_comfyui.py --ep EP01 --apply --free # 整批结束统一释放模型
python3 tools/cleanup_comfyui.py # 不带 --ep:连锚图/集外任务一起清
# (台账写在图片同目录,脚本会递归扫工作空间下所有 t2i_runs.json / a14b_runs.json)
# 显式清某个任务时必须带归属凭证(client_id 在 history 项 prompt[3])
python3 tools/cleanup_comfyui.py --prompt-id <pid> --endpoint http://192.168.1.30:30112 --client-id manju-i2v-ab12cd34 --apply
python3 tools/selftest_cleanup.py # 本地 mock 自检:归属/顺序/复核 26 项断言
# ⑧ 审片:首/中/末联系表;漂移镜截前段(keepSeconds)或换首帧重跑
python3 tools/review.py projects/EP01/30_shots.json --only S13,S15
# ⑨ 字幕对齐(台词镜必做:按实测发声段,别照 [Audio] 设计时间)
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
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
# ⑩ 缝合 + 归档(按路线选脚本,别混)
python3 tools/render_native.py projects/EP01/30_shots.json --ass work/EP01/render_native/ep.ass --mask # 台词镜:直拼+烧对齐字幕
python3 tools/render.py projects/EP01/30_shots.json --name EP01_成片.mp4 # 无音轨镜/旁白镜:TTS配音缝合
python3 tools/manju.py manifest projects/EP01/30_shots.json
# 把成片信息登记到 renders/INDEX.md,计算 sha256
4. 脚本速查
| 脚本 | 作用 | 常用参数 |
|---|---|---|
manju.py |
工作空间入口 | setup / init EPxx / validate <shots> / hash-file <path> / manifest <shots> |
validate_shots.py |
分镜前置校验 | 由 manju.py validate 调用 |
tts.py |
edge-tts 配音 + 时长回填 | <shots.json> |
submit_t2i.py |
内网 H3-Image 文生图(锚图/首帧) | --ep EP01 --shot S01 --prompt-file <p.txt> / --prompt --out --width --height --force |
fetch_t2i.py |
出图脚本被杀后按 pid 从服务端救回单图(含自检) | --pid <pid> --out <png> [--host url] |
submit_i2v.py |
图生视频提交/预检/续跑(A14B,静音镜) | <shots.json> --only S03 --force --cleanup |
submit_h3_native.py |
H3 音画同出单镜(台词镜,64 GB 卡) | --ep EP01 --shot S04 --seconds 7.3 / --length 175 --t2v |
queue_h3_native.py |
整集排队(不等待)+ 丢失自检 | --ep EP01 --only S01a --force --check |
fetch_h3_native.py |
取回已完成产物 + 音轨检查 | --ep EP01 --status --only S04 |
cleanup_comfyui.py |
导出后只清自己发起的任务:归属闸门 + 扩展删产物 + 官方接口删记录 | --ep EP01(不带则连锚图一起清)--shot S03 --apply --prompt-id <pid> --client-id <cid> --purge-input --free |
selftest_cleanup.py |
清理链路自检(本地 mock ComfyUI,29 项断言) | 无参数 |
review.py |
首/中/末审片联系表 | <shots.json> --group 1 --only S13,S15 |
align_subtitles.py |
字幕对齐实测发声段(修口型错位):测 silencedetect 发声段 + 逐句映射重排时间,台词原文不动 |
<shots.json> --dump-segs --init-config <path> --config <cfg> --dry-run --out <ep.ass> --package-out <path> |
render_native.py |
台词镜缝合:直拼保留原生音轨 + 烧 ASS 字幕 + 瑕疵遮盖。台词镜务必配 --ass 用对齐 ASS,否则内置设计时间轴会错位 |
<shots.json> --ass <ep.ass> --mask --name <file.mp4> |
render.py |
无音轨镜缝合:配音、字幕、HUD、落版 | <shots.json> --name <file.mp4> --crop-bottom N |
make_overlay.py |
程序化生成 HUD/落版 | 无参数 |
5. 关键规则(先看再动手)
- 资产先行:锚图/画风先定稿锁只读。I2V 只能"给首帧让它动",首帧决定上限。
- 配音先于剪辑:先量实测时长再回填
duration,禁止加快语速硬塞;改词后删旧vo_NN.mp3重生成。 - 提示词原文留档:
40_prompts/Sxx.i2v.txt一字不改;改词即换哈希、新文件不覆盖旧版。 - 漂移按类型处理:姿态/场景漂移用
keepSeconds截前 1.2–2.5s 慢放;首帧硬伤(乱码文字、畸形手)必须换图重跑。 - 只拼已采用片段:
rejected留作候选;区分「已生成 / 已采用 / 已合成 / 已归集」。 - 生成前必须授权:展示对象、数量、模型、端点、完整提示词、参数、执行次数;"继续"和沉默不算授权。
- 端点不照搬:换模型先查
/system_stats//object_info;DCU(ROCm) 与 K8s(CUDA) 节点图互不通用,明文 HTTP 一律绕代理。详见 models.md。 - 出图后必须看
[SANITY]:submit_t2i.py出图后会自动做 PNG 自检(颜色数 / 亮度 / 标准差)。判ok(...)才算可用;判 FAIL(纯色图 / 全黑)说明量化档位选错(DCU 禁int8_convrot,K8s-30113 只能用int8_convrot),不要重跑——重跑只会再出一张纯色图。先核对 models.md §2.0 的档位表再改端点。自检未通过时脚本自动跳过清理,保留服务端记录与产物当排查证据。 - 导出即清,且只清自己发起的任务:成片拉回本地校验大小后,按台账
clientId+client_id白名单判归属(requireOwner=true时未通过一律拒绝、不调任何删除接口);再用官方标准接口(/api/history、/api/queue的{"delete":[...]})清记录,删后必须复核「删前有→删后无」——200 空 body 是幂等响应,不等于删成功。产物文件官方没有删除 HTTP 路由,优先用自带扩展assets/comfyui-manju-cleanup/的POST /manju/cleanup/purge(只传 pid,服务端反查 history 并二次校验归属),未装则降级cleanup.deleteApi/cleanup.commands。装了扩展要先删文件再删记录(purge 依赖 history 反查)。只清服务端,本地成片/提示词/manifest 保留。用cleanup_comfyui.py(默认预演,--apply才删),或给提交脚本加--cleanup;整批结束再加--free。详见 models.md §3.4。 - 台词不做后期贴嘴:人物说话的画面必须由音画同出的模型生成(H3
fl2va+ 首帧锁图,3012164 GB)。Wav2Lip(96² 糊块)、LatentSync(环境装不下)、InfiniteTalk(78 min / 油画感 / 身份漂移)已实测否掉。见 native-av.md。 - 长任务排队、不挂进程:单镜 90 分钟级,一律「排队 → 落盘 pid → 事后取回」;
queue/history是内存态,实例重启即静默丢任务(实测 7 镜全丢),排完 5 分钟内必须--check自检。
详细规则按阶段读 references/:
- models.md — 内网模型服务与 API 全表(2 视频 / 1 文生图 / LLM / 向量;节点图与两端差异)
- native-av.md — 台词镜头:音画同出(为什么放弃 lip-sync / 节点图 / 五段式提示词 / 时长网格 / 排队取回)
- workflow.md — 七阶段与闸门
- director.md — 导演内核 12 铁律 + 对白写法 + I2V 提示词模板
- storyboard.md — 分镜三角色与连续性
- submit-i2v.md — 提交协议与预检
- render.md — 缝合规格
- review.md — 审片与归档
- pitfalls.md — 踩坑速查,出片前务必扫一遍
配置模板在 assets/:config.template.json、shot.schema.json、policy.template.md(叙事与合规清单)。
6. 换模型 / 换后端
内置 两个视频模型 + 一个文生图,端点与完整节点图见 references/models.md:
| 目标 | 怎么做 |
|---|---|
| 默认 A14B(静音镜) | 直接用 submit_i2v.py;UNET / LORA / CLIP / VAE 常量与负向提示词在脚本顶部,端点与规格在 config/pipeline.json |
| 台词镜(H3 音画同出) | 用 queue_h3_native.py / submit_h3_native.py,读 config.nativeVideoModel;只能在 64 GB 卡(30121)跑,别塞给 2080Ti |
| H3 T2V(只要环境音、无对白) | 不能只改 videoModel.endpoint:采样节点、权重、输出节点都不同,按 models.md §4.3 另写工作流;22 GB 卡上禁 first_frame |
| 出图 | submit_t2i.py 读 config.imageModel;权重名不用填(脚本读端点 /object_info 自动挑);32 对齐、6 步、cfg 1.0 别乱改;出图后看 [SANITY] 行 |
| 非 ComfyUI 后端 | 替换 submit_i2v.py / submit_h3_native.py 的 req() / build(),其余脚本不依赖具体模型 |
五条铁律:换模型先查 /system_stats 和 /object_info;I2V 看卡不看端口(first_frame 只有 64 GB 的 30121 扛得住);DCU(ROCm) 与 K8s(CUDA) 的节点图互不通用;K8s 侧三个端口(30111/30112/30113)是同一个 0.45 实例,共用一张 2080Ti,只能串行提交;出图量化档位不能照搬(ROCm 只能 w4a8、K8s-30113 只能 int8_convrot,搞反了静默出纯色图)。
输出规格、音色、字幕/HUD/落版规则全部集中在 config/pipeline.json,不要在脚本里散落硬编码。
7. 出处与许可
方法论剥离自 Toonflow(MIT),逐字原文存于 references/toonflow/,许可证见 TOONFLOW-LICENSE.txt。本技能的脚本为原创适配,只借协议与规则,不含上游运行时代码。若将来引入上游源码,须重新核对当期许可证。