AI 漫剧流水线技能完整落地:文件驱动、可校验、单镜可重做。 七阶段:基线资产 → 策划叙事 → 分镜中枢 → 配音先行 → 出图/出视频 → 缝合 → 审片归档。 - scripts/: manju.py 编排、submit_t2i/submit_i2v 提交、cleanup_comfyui 清理 - assets/comfyui-manju-cleanup/: ComfyUI 清理扩展,归属校验 fail-closed - references/: models.md 模型节点图全表、workflow/director/storyboard/pitfalls - .gitignore: 排除 __pycache__ 与运行产物
12 KiB
ai-manju — 同事上手指南
一条流水线把剧本做成 AI 漫剧 / 短剧成片:源节拍 → 分镜 → 首帧图 → 图生视频 → 配音 → 字幕缝合 → 归档。 特点是文件驱动、机器可校验、任何一镜可单独重做。工具脚本只用 Python 标准库。
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 # 脚本本身零第三方依赖
另需准备:内网模型端点可达(模板已预填三个 K8s ComfyUI 地址:30111 / 30112 / 30113)。开工自检:
for U in 192.168.1.30:30111 192.168.1.30:30112 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-13:DCU
192.168.1.24整机不可达(30120 / 8801 TCP 均 CLOSED)。 出图改走192.168.1.30:30113;embed-bge 向量服务(8801)随之下线。 DCU 恢复后把config/pipeline.json的imageModel.endpoint改回去即可,权重名不用改(脚本自动探测)。
2. 建工作空间
mkdir my-drama && cd my-drama
python3 ~/.agents/skills/ai-manju/scripts/manju.py setup
setup 会建好目录、写入 config/pipeline.json 模板、把 10 个脚本复制到 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.t2i.txt 逐镜出图提示词原文(用内网 H3-Image 时)
# ③ 校验: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 并把实测时长回填 30_shots.json 的 duration
python3 tools/tts.py projects/EP01/30_shots.json
# ⑥ 首帧图:内网 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 # 全量,每镜导出后自动清服务端
# ⑦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
# ⑨ 缝合 + 归档
python3 tools/render.py projects/EP01/30_shots.json --name EP01_成片.mp4
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 |
submit_i2v.py |
图生视频提交/预检/续跑(A14B) | <shots.json> --only S03 --force --cleanup |
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 |
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。
详细规则按阶段读 references/:
- models.md — 内网模型服务与 API 全表(2 视频 / 1 文生图 / LLM / 向量;节点图与两端差异)
- 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(带原生音轨) | 不能只改 videoModel.endpoint:采样节点(KSampler / SamplerCustomAdvanced)、权重、输出节点、音频清洁全不同,按 models.md §4.2 / §4.3 另写工作流 |
| 出图 | submit_t2i.py 读 config.imageModel;权重名不用填(脚本读端点 /object_info 自动挑);32 对齐、6 步、cfg 1.0 别乱改;出图后看 [SANITY] 行 |
| 非 ComfyUI 后端 | 替换 submit_i2v.py 的 request() / build_workflow(),其余脚本不依赖具体模型 |
四条铁律:换模型先查 /system_stats 和 /object_info;DCU(ROCm) 与 K8s(CUDA) 的节点图互不通用;K8s 侧三个端口(30111/30112/30113)是同一个 0.45 实例,共用一张 2080Ti,只能串行提交;出图端点的量化档位不能照搬(DCU 禁 int8_convrot,K8s-30113 只能用 int8_convrot,搞反了静默出纯色图)。
输出规格、音色、字幕/HUD/落版规则全部集中在 config/pipeline.json,不要在脚本里散落硬编码。
7. 出处与许可
方法论剥离自 Toonflow(MIT),逐字原文存于 references/toonflow/,许可证见 TOONFLOW-LICENSE.txt。本技能的脚本为原创适配,只借协议与规则,不含上游运行时代码。若将来引入上游源码,须重新核对当期许可证。