- 纠正 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 清单同步
214 lines
18 KiB
Markdown
214 lines
18 KiB
Markdown
# 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](references/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](references/render.md)。
|
||
>
|
||
> **2026-11-17 v1.1.0**:人物说话的镜头**不再事后贴嘴**。
|
||
> 走 `192.168.1.23:30121`(DCU K100 64 GB)的 MiniMax H3 `fl2va` **音画同出**:首帧锁图 I2V,
|
||
> 画面 / 人声 / 环境音一次出,口型模型内对齐。`submit_h3_native.py` / `queue_h3_native.py` / `fetch_h3_native.py`
|
||
> 与 [references/native-av.md](references/native-av.md)。Wav2Lip / LatentSync / InfiniteTalk 三条事后贴嘴路线已实测否掉。
|
||
|
||
---
|
||
|
||
## 1. 安装(一次性)
|
||
|
||
把本目录放到 `~/.agents/skills/ai-manju/`,然后:
|
||
|
||
```bash
|
||
cd ~/.agents/skills/ai-manju
|
||
chmod +x install.sh
|
||
./install.sh # 软链到 ~/.claude/skills、~/.workbuddy/skills、~/.qwenworkcn/skills
|
||
./install.sh --check # 随时只读体检
|
||
```
|
||
|
||
如果不用多端软链,直接把整个 `ai-manju/` 目录拷到任一 agent 的 `skills/` 下也能用。
|
||
|
||
依赖(只在配音/渲染阶段需要):
|
||
|
||
```bash
|
||
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`)。开工自检:
|
||
|
||
```bash
|
||
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](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。
|
||
> 旧 DCU `192.168.1.24`(30120)仍整机不可达,**与 30121 不是一台机**;embed-bge(8801)随之下线。
|
||
|
||
---
|
||
|
||
## 2. 建工作空间
|
||
|
||
```bash
|
||
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](references/models.md)。密钥绝不写进配置 —— LLM 代理走 `xop run --secret K=llm_key -- CMD < /dev/null`。
|
||
|
||
> 之后所有脚本都在工作空间根运行(`cd my-drama`)。脚本按 `MANJU_ROOT` → cwd 向上找 `config/pipeline.json` → 脚本上级 的顺序定位工作空间。
|
||
|
||
---
|
||
|
||
## 3. 做一集
|
||
|
||
```bash
|
||
# ① 骨架
|
||
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. 关键规则(先看再动手)
|
||
|
||
1. **资产先行**:锚图/画风先定稿锁只读。I2V 只能"给首帧让它动",首帧决定上限。
|
||
2. **配音先于剪辑**:先量实测时长再回填 `duration`,禁止加快语速硬塞;改词后删旧 `vo_NN.mp3` 重生成。
|
||
3. **提示词原文留档**:`40_prompts/Sxx.i2v.txt` 一字不改;改词即换哈希、新文件不覆盖旧版。
|
||
4. **漂移按类型处理**:姿态/场景漂移用 `keepSeconds` 截前 1.2–2.5s 慢放;首帧硬伤(乱码文字、畸形手)必须换图重跑。
|
||
5. **只拼已采用片段**:`rejected` 留作候选;区分「已生成 / 已采用 / 已合成 / 已归集」。
|
||
6. **生成前必须授权**:展示对象、数量、模型、**端点**、完整提示词、参数、执行次数;"继续"和沉默不算授权。
|
||
7. **端点不照搬**:换模型先查 `/system_stats` / `/object_info`;DCU(ROCm) 与 K8s(CUDA) 节点图互不通用,明文 HTTP 一律绕代理。详见 [models.md](references/models.md)。
|
||
8. **出图后必须看 `[SANITY]`**:`submit_t2i.py` 出图后会自动做 PNG 自检(颜色数 / 亮度 / 标准差)。判 `ok(...)` 才算可用;判 FAIL(纯色图 / 全黑)说明**量化档位选错**(DCU 禁 `int8_convrot`,K8s-30113 只能用 `int8_convrot`),**不要重跑**——重跑只会再出一张纯色图。先核对 models.md §2.0 的档位表再改端点。自检未通过时脚本**自动跳过清理**,保留服务端记录与产物当排查证据。
|
||
9. **导出即清,且只清自己发起的任务**:成片拉回本地校验大小后,按台账 `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](references/models.md)。
|
||
10. **台词不做后期贴嘴**:人物说话的画面必须由**音画同出的模型**生成(H3 `fl2va` + 首帧锁图,`30121` 64 GB)。Wav2Lip(96² 糊块)、LatentSync(环境装不下)、InfiniteTalk(78 min / 油画感 / 身份漂移)已实测否掉。见 [native-av.md](references/native-av.md)。
|
||
11. **长任务排队、不挂进程**:单镜 90 分钟级,一律「排队 → 落盘 pid → 事后取回」;`queue`/`history` 是内存态,实例重启即静默丢任务(实测 7 镜全丢),**排完 5 分钟内必须 `--check` 自检**。
|
||
|
||
详细规则按阶段读 `references/`:
|
||
|
||
- [models.md](references/models.md) — **内网模型服务与 API 全表**(2 视频 / 1 文生图 / LLM / 向量;节点图与两端差异)
|
||
- [native-av.md](references/native-av.md) — **台词镜头:音画同出**(为什么放弃 lip-sync / 节点图 / 五段式提示词 / 时长网格 / 排队取回)
|
||
- [workflow.md](references/workflow.md) — 七阶段与闸门
|
||
- [director.md](references/director.md) — 导演内核 12 铁律 + 对白写法 + I2V 提示词模板
|
||
- [storyboard.md](references/storyboard.md) — 分镜三角色与连续性
|
||
- [submit-i2v.md](references/submit-i2v.md) — 提交协议与预检
|
||
- [render.md](references/render.md) — 缝合规格
|
||
- [review.md](references/review.md) — 审片与归档
|
||
- [pitfalls.md](references/pitfalls.md) — **踩坑速查,出片前务必扫一遍**
|
||
|
||
配置模板在 `assets/`:[config.template.json](assets/config.template.json)、[shot.schema.json](assets/shot.schema.json)、[policy.template.md](assets/policy.template.md)(叙事与合规清单)。
|
||
|
||
---
|
||
|
||
## 6. 换模型 / 换后端
|
||
|
||
内置 **两个视频模型 + 一个文生图**,端点与完整节点图见 [references/models.md](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](https://github.com/HBAI-Ltd/Toonflow-app)(MIT),逐字原文存于 `references/toonflow/`,许可证见 [TOONFLOW-LICENSE.txt](references/toonflow/TOONFLOW-LICENSE.txt)。本技能的脚本为原创适配,只借协议与规则,不含上游运行时代码。若将来引入上游源码,须重新核对当期许可证。
|