diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e72f10c --- /dev/null +++ b/.gitignore @@ -0,0 +1,16 @@ +# Python 编译缓存 +__pycache__/ +*.py[cod] +*.so + +# macOS +.DS_Store + +# 技能运行产物(不应入库) +config/local.json +work/ +renders/ +projects/*/40_prompts/*.mp3 +*.mp4 +*.png +!assets/**/*.png diff --git a/README.md b/README.md index e62d5ab..60d57ce 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,173 @@ -# ai-manju +# ai-manju — 同事上手指南 -AI 漫剧流水线技能:剧本→分镜→首帧图→图生视频→配音→缝合→归档 \ No newline at end of file +一条流水线把剧本做成 AI 漫剧 / 短剧成片:**源节拍 → 分镜 → 首帧图 → 图生视频 → 配音 → 字幕缝合 → 归档**。 +特点是文件驱动、机器可校验、任何一镜可单独重做。工具脚本只用 Python 标准库。 + +--- + +## 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 # 脚本本身零第三方依赖 +``` + +另需准备:**内网模型端点可达**(模板已预填三个 K8s ComfyUI 地址:30111 / 30112 / 30113)。开工自检: + +```bash +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](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. 建工作空间 + +```bash +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](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.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 --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 ` / `hash-file ` / `manifest ` | +| `validate_shots.py` | 分镜前置校验 | 由 `manju.py validate` 调用 | +| `tts.py` | edge-tts 配音 + 时长回填 | `` | +| `submit_t2i.py` | **内网 H3-Image 文生图**(锚图/首帧) | `--ep EP01 --shot S01 --prompt-file ` / `--prompt` `--out` `--width` `--height` `--force` | +| `submit_i2v.py` | 图生视频提交/预检/续跑(A14B) | `` `--only S03` `--force` `--cleanup` | +| `cleanup_comfyui.py` | **导出后只清自己发起的任务**:归属闸门 + 扩展删产物 + 官方接口删记录 | `--ep EP01`(不带则连锚图一起清)`--shot S03` `--apply` `--prompt-id --client-id ` `--purge-input` `--free` | +| `selftest_cleanup.py` | 清理链路自检(本地 mock ComfyUI,29 项断言) | 无参数 | +| `review.py` | 首/中/末审片联系表 | `` `--group 1` `--only S13,S15` | +| `render.py` | 缝合、字幕、HUD、落版 | `` `--name ` `--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)。 + +详细规则按阶段读 `references/`: + +- [models.md](references/models.md) — **内网模型服务与 API 全表**(2 视频 / 1 文生图 / LLM / 向量;节点图与两端差异) +- [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(带原生音轨) | **不能只改 `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](https://github.com/HBAI-Ltd/Toonflow-app)(MIT),逐字原文存于 `references/toonflow/`,许可证见 [TOONFLOW-LICENSE.txt](references/toonflow/TOONFLOW-LICENSE.txt)。本技能的脚本为原创适配,只借协议与规则,不含上游运行时代码。若将来引入上游源码,须重新核对当期许可证。 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..721093a --- /dev/null +++ b/SKILL.md @@ -0,0 +1,166 @@ +--- +name: ai-manju +description: >- + 用文件驱动、可校验、可单镜重做的流水线制作 AI 漫剧 / AI 短剧:从源节拍账本、结构化分镜、逐镜提示词、角色锚图与图生视频,到配音、字幕、HUD 缝合与成片归档。 + Trigger on: "AI漫剧" "漫剧" "AI短剧" "短剧" "分镜" "分镜表" "图生视频" "出片" + "配音" "缝合" "镜头表" "manju" "comic drama" "storyboard" "image to video"。 +metadata: + version: "1.0.0" + upstream: "Toonflow workflow v2.7.0 (MIT) 方法论,已剥离宿主耦合;原文见 references/toonflow/" +--- + +# ai-manju — AI 漫剧流水线 + +把「剧本 → 分镜 → 首帧图 → 图生视频 → 配音 → 缝合 → 归档」做成**文件驱动、机器可校验、任何一镜可单独重做**的轻量管线。 + +**定位先行**:这是一个**编排层**,不是一键出片工具,也不部署重型工作台。 +- 本机只做:目录/清单/校验/提示词/ASS 字幕/ffmpeg 缝合。 +- 首帧图:内网 **MiniMax H3-Image 文生图** → `tools/submit_t2i.py`;脚本**自动探测权重名**,端点或权重变了不用改代码。 + 也可用宿主 Agent 的图像能力(会消耗外部积分)。 +- 视频:**两个内网模型**可选 —— Wan2.2 I2V A14B(无音轨、4 步、批量抽卡,`tools/submit_i2v.py` 已封装) + 与 MiniMax H3(**带原生同步音频**,20 步、画质优先,**仅 T2V**:首帧锁图 I2V 在 2080Ti 上会 OOM)。 +- **三者跑在同一个实例上:`192.168.1.30:30113`(K8s,ComfyUI 0.45)。** 换模型只换节点图,不换地址; + 但它是 1 张 22 GB 卡 + 4 GiB 内存硬限,**必须串行**。 +- 策划阶段可借内网 LLM 代理拆剧本(可选);向量服务 embed-bge 已随 DCU 下线,暂无替代。 +- **端点、节点图、0.45/0.38 差异全表见 [references/models.md](references/models.md)**; + 部署拓扑、4 GiB 墙、补丁集与 **pod 重建后的恢复步骤**见部署侧文档 +`~/WorkBuddy/2026-11-08-19-43-52/deploy/k8s-nvidia/deploy-as-built.md`(**不在技能包内**,部署与使用刻意分开)。 + +> ⚠️ **2026-11-13 服务状态**:三个 ComfyUI 已**合并为一个多模态实例**(30113,0.45)。 +> `30111` / `30112` 已通过 Service selector 改指到同一实例(旧 deployment 已 scale 0),**端口照旧可用、调用方零改动**。 +> DCU `192.168.1.24` **整机不可达**(30120 / 8801 TCP 均 CLOSED),**embed-bge 向量服务随之下线**。 +> 30113 的 `/local` 是 emptyDir,**pod 重建后必须跑 `/basedir/apply-multimodal.sh`**,否则只剩出图能力。 +> 开工前先跑下面的健康自检,别照着旧文档连已下线的端点。 + +## 何时用 + +- 要做一集 AI 漫剧 / 短剧 / 动态漫画,需要可回溯的分镜与提示词资产。 +- 已有剧本,需要拆成逐镜提示词并批量生成、审片、缝合、归档。 +- 需要「改第 3 镜不动其余镜头」的可重做工作流。 +- 不想把提示词、锚图、片段、成片堆在一个目录里靠记忆管理。 + +## 先决条件(一次性) + +```bash +python3 -V # 脚本只用标准库 +pip install --user imageio-ffmpeg # 渲染/审片用的静态 ffmpeg;不要 brew 装 +pip install --user edge-tts # 配音(免费免密钥) +``` + +再准备:① 内网端点可达(**主用 `192.168.1.30:30113` 已预填进 `config/pipeline.json`**,图与视频共用;`30111`/`30112` 是同一实例的别名,等价可用;DCU 30120 已下线);② LLM 代理若要用,密钥走 `xop run --secret K=llm_key -- CMD < /dev/null`,不落明文。开工自检: + +```bash +# 主用端点:在线 + 必须看到 4 个扩散模型(H3 图 / H3 视频 / WAN high+low) +U=192.168.1.30:30113 +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:'); [print(' ', x) for x in d] +" +# 少于 4 个 = pod 重建后 /local 软链丢了(不是模型坏了)→ 跑 /basedir/apply-multimodal.sh +``` + +⚠️ 内网是**明文 HTTP**,本机代理会把响应改成 `text/html`:curl 必须 `--noproxy '*'`,Python 必须 `ProxyHandler({})`。 + +## 快速开始 + +```bash +mkdir my-drama && cd my-drama +python3 ~/.agents/skills/ai-manju/scripts/manju.py setup # 建目录 + 配置模板 + 复制脚本 +# 编辑 config/pipeline.json:填 workspace、tts.voice;端点已预填 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/models.md);[references/storyboard.md](references/storyboard.md) | +| 1 | 策划与叙事 | `00_brief.md`、`10_events.md`、`20_script.md` | [assets/policy.template.md](assets/policy.template.md);[references/director.md](references/director.md) | +| 2 | 分镜中枢 | `30_shots.json`、`40_prompts/Sxx.i2v.txt` | `manju.py validate`;[references/director.md](references/director.md) | +| 3 | 配音先行 | `work/EPxx/audio/vo_NN.mp3` | `tools/tts.py`;**实测时长回填 `duration`** | +| 4 | 出图 / 出视频 | `work/EPxx/{images,videos}/Sxx_.*` | `tools/submit_t2i.py` + `tools/submit_i2v.py`(A14B);H3 节点图见 [references/models.md §4](references/models.md);[references/submit-i2v.md](references/submit-i2v.md);**导出后** `tools/cleanup_comfyui.py` | +| 5 | 缝合 | `renders/EPxx_成片.mp4` | `tools/render.py`;[references/render.md](references/render.md) | +| 6 | 审片与归档 | `renders/INDEX.md`、`50_manifest.json` | `tools/review.py`;[references/review.md](references/review.md) | + +完整闸门与输出契约见 [references/workflow.md](references/workflow.md),字段定义见 [assets/shot.schema.json](assets/shot.schema.json)。 + +## 内网模型路由(开工前先选) + +| 要什么 | 用哪个 | 端点 | 脚本 / 文档 | +|---|---|---|---| +| 角色锚图、分镜首帧 | **MiniMax H3-Image**(int8_convrot,2048² 起 / 6 步 euler / ~178s) | **`192.168.1.30:30113`**(权重自动探测) | `tools/submit_t2i.py`;[models.md §2 / §4.4](references/models.md) | +| 静音动作镜头、批量抽卡 | **Wan2.2 I2V A14B**(832×480 上限 / 81 帧 / 4 步 / 无音轨) | **同一个 `30113`** | `tools/submit_i2v.py`(已封装);[submit-i2v.md](references/submit-i2v.md) | +| 带环境音 / 同期声的镜头 | **MiniMax H3 T2V**(w6a8,20 步、**无 LoRA**,原生 aac 音轨)⚠️ **仅文生视频,别塞 `first_frame`** | **同一个 `30113`** | 手写节点图;[models.md §4.3](references/models.md) | +| 拆剧本、扩写提示词 | LLM 代理(需 xop 密钥、**按 slot 前缀**路由) | `192.168.1.30:30084` | [models.md §5.1](references/models.md) | +| 设定检索、去重 | embed-bge(免密钥,模型名 `BAAI/bge-large-zh-v1.5`)⚠️ 已下线 | `192.168.1.24:8801` | [models.md §5.2](references/models.md) | + +**四条铁律**:① 三种模态全在 **30113 一个实例**(1 张 2080Ti + 4 GiB 内存硬限),**只能串行**,并发必 OOM;② 换视频模型**不能只改 `videoModel.endpoint`**,两套节点图/权重/输出节点都不同(H3 走 `SamplerCustomAdvanced`,WAN 走 `KSamplerAdvanced`×2 + `ModelSamplingSD3`);③ 0.45(30113)与 0.38(30111/30112)不能互抄采样节点、`SaveVideo.format`、`--fp16-unet`(30111 必需、30113 禁用);④ **出图量化档位不能照搬**:DCU 禁 `int8_convrot`,K8s-30113 只能用 `int8_convrot` —— 搞反了会静默出纯色图。 + +### 出图怎么跑(阶段 0 / 阶段 4) + +```bash +# 权重不用填:脚本读端点 /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]` 行。** + +## 八条不能让渡的规则 + +1. **资产先行**:角色锚图/画风/HUD 先定稿并锁为只读,再进入分镜。 +2. **分镜驱动**:`30_shots.json` 是单一真相源,一镜一行,每个动作映射回 `E##` 源节拍。 +3. **提示词原文留档**:`40_prompts/Sxx.i2v.txt` 一字不改;改词即换哈希、生成新文件,旧版不覆盖。 +4. **配音先于剪辑**:先量实测时长再回填 `duration`,禁止加快语速硬塞。 +5. **单镜重做**:漂移只重跑/截取该镜,不推倒整条时间线;`keepSeconds` 可截稳定前段慢放。 +6. **状态诚实**:区分「已生成 / 已采用 / 已合成 / 已归集」,不把文件路径当"看过视频"。 +7. **端点不照搬**:换模型先查 `/system_stats` 与 `/object_info`,按目标服务的 ComfyUI 版本写节点图;明文 HTTP 一律绕代理,`/prompt` 一律包 `{"prompt": ...}` 外层。 +8. **导出即清(只清自己发起的任务)**:成片拉回本地并校验大小后,必须清掉 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](references/models.md)。 + **例外**:出图自检未通过(纯色图)时**不清服务端** —— 保留 `history` 与产物当排查证据,脚本已自动跳过。 + **扫描范围**:清理脚本递归扫工作空间下所有 `t2i_runs.json` / `a14b_runs.json`(台账写在图片同目录,位置随 `--out` 变)。**不带 `--ep` 跑一次**才能把角色锚图等集外任务一起清掉;只跑 `--ep EP01` 会漏掉它们。每个任务按台账里记录的**实际端点**去清,不会清错地方。 + +## 审片与漂移处理(核心经验) + +I2V 对**静止镜头**极易脑补动作:人物必抬手/转正,细光必变光柱,节点必增生。 +- 先抽首/中/末帧(`tools/review.py` 出联系表)判定漂移类型。 +- **姿态/场景漂移** → `keepSeconds` 截前 1.2–2.5s 稳定段慢放到目标时长,比反复抽卡省时间。 +- **硬伤**(首帧带乱码文字被重绘、手部畸形)→ 必须换首帧图重跑,改提示词没用。 +- 正向锁写成**可判定状态**:"双臂垂在体侧 / 细光保持细线永不宽成走廊 / 双手不触及不跨越",禁止句放最后。 + +完整清单见 [references/pitfalls.md](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 # 逐镜提示词原文 +│ └── 50_manifest.json # 产物索引:路径/参数/状态/attempts +├── work/EPxx/{images,videos,audio,render,review}/ # 可重建产物,不入库 +├── renders/INDEX.md # 成片只留索引,本体不入库 +└── tools/ # setup 复制进来的 10 个脚本(含 submit_t2i.py / cleanup_comfyui.py / selftest_cleanup.py) +``` + +**路径解析**:所有脚本按 `MANJU_ROOT` 环境变量 → 从 cwd 向上找 `config/pipeline.json` → 脚本上级目录 的顺序定位工作空间。因此**先 `cd` 到工作空间根再运行脚本**;也可显式设 `MANJU_ROOT=/abs/path`。 + +## 终止规则 + +最终回复说明:做成了什么、真实文件在哪、哪些内容由谁核验、唯一必要的下一步。生成前展示清单、生成后据实登记,不夸大状态。 diff --git a/assets/brief.template.md b/assets/brief.template.md new file mode 100644 index 0000000..c0e24cf --- /dev/null +++ b/assets/brief.template.md @@ -0,0 +1,11 @@ +# EP{ep} 任务卡 + +项目: +时长: +镜头数: +核心冲突: +角色: +画风: +禁忌:(从 policy 清单抄结论,必填) + +> 重编不是缩写;每镜必须能回溯到 `10_events.md` 的 E##。 diff --git a/assets/comfyui-manju-cleanup/__init__.py b/assets/comfyui-manju-cleanup/__init__.py new file mode 100644 index 0000000..9283717 --- /dev/null +++ b/assets/comfyui-manju-cleanup/__init__.py @@ -0,0 +1,412 @@ +# -*- coding: utf-8 -*- +"""ComfyUI custom node: manju-cleanup (v1.0.0) + +补齐官方 HTTP API 的唯一缺口:**删除 output/ / input/ / temp/ 里的产物文件**。 +官方 server.py 只有记录删除(POST /history、/queue)与显存释放(POST /free), +DELETE /userdata/{file} 只管 ComfyUI/user/,/api/assets 删的是数据库引用。 + +设计原则("只删自己发起的任务"): + 1. 调用方只传 prompt_id,插件**从服务端 history 自己反查**该 pid 的 outputs, + 绝不接受任意文件路径 —— 不会跨任务、跨用户误删; + 2. history 项 prompt[3]["client_id"] 是本任务的发起凭证,按 client_ids 精确 + 白名单 / owner_prefixes 前缀白名单做归属校验,校验不过一律拒绝; + 3. 文件被其它 history 条目引用(例如共用首帧)时跳过,不做引用计数盲删; + 4. 路径经 realpath 校验必须落在对应类型根目录内,拒绝绝对路径、.. 逃逸、 + 符号链接、目录、NUL 字节; + 5. dry_run 默认开启,只有显式 dry_run=false 才 os.remove; + 6. 可选 MANJU_CLEANUP_TOKEN 环境变量开启鉴权(header X-Manju-Token 或 body.token)。 + +注册方式:写进 PromptServer.instance.routes;官方 add_routes() 会自动复制一份 +"/api" 前缀镜像,所以 /manju/cleanup/* 与 /api/manju/cleanup/* 同时可用(0.38/0.45 实测)。 + +路由: + GET /manju/cleanup/ping 能力探测、根目录、是否要求 token + POST /manju/cleanup/purge 预览/删除(body 见 README 或技能 references/models.md §3.4) + {"pids": ["..."], "client_ids": ["manju-i2v-ab12"], "owner_prefixes": ["manju-"], + "dry_run": true, "purge_input": false, "require_owner": true} + +本模块不负责删 history/queue 记录:那部分继续走官方标准接口,且必须在 purge +之后调用 —— purge 依赖 history 反查产物清单,记录删掉就再也查不到文件名了。 +""" +import logging +import os +import json + +VERSION = "1.0.0" +PREFIX = "/manju/cleanup" +TOKEN_ENV = "MANJU_CLEANUP_TOKEN" +FILE_KEYS = ("images", "videos", "gifs", "audio", "files") +TYPES = ("output", "input", "temp") +MAX_PIDS = 200 + +# ComfyUI 不加载本模块(例如本地单测)时保持可导入:纯逻辑函数零外部依赖。 +NODE_CLASS_MAPPINGS = {} +NODE_DISPLAY_NAME_MAPPINGS = {} +__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS", + "roots_of", "files_of", "client_id_of", "resolve", + "reference_counts", "build_report"] + + +def _folder_paths(): + try: + import folder_paths + return folder_paths + except Exception: + return None + + +def roots_of(folder_paths): + """返回 {type: realpath(root)}。兼容 0.38(无 get_directory_by_type)与 0.45。""" + if folder_paths is None: + return {} + out = {} + fallbacks = {"output": "get_output_directory", + "input": "get_input_directory", + "temp": "get_temp_directory"} + getter = getattr(folder_paths, "get_directory_by_type", None) + for t in TYPES: + p = None + if callable(getter): + try: + p = getter(t) + except Exception: + p = None + if not p: + fn = getattr(folder_paths, fallbacks[t], None) + if callable(fn): + try: + p = fn() + except Exception: + p = None + if p: + out[t] = os.path.realpath(str(p)) + return out + + +def _normalize(f): + if not isinstance(f, dict): + return None + t = str(f.get("type") or "output").lower() + if t not in TYPES: + t = "output" + name = str(f.get("filename") or "") + if not name: + return None + return {"type": t, + "subfolder": str(f.get("subfolder") or "").replace("\\", "/").strip("/"), + "filename": name.replace("\\", "/")} + + +def files_of(item): + """从一条 history 记录抽 (产物, 上传输入)。 + + 产物来自 outputs 节点(SaveImage / SaveVideo / SaveAudio 可能有多个输出节点); + 输入来自 prompt[2] 节点图里的 LoadImage,以及 outputs 里回带的 type=input 源素材。 + """ + outputs, inputs = [], [] + if not isinstance(item, dict): + return outputs, inputs + for node in (item.get("outputs") or {}).values(): + if not isinstance(node, dict): + continue + for key in FILE_KEYS: + for f in (node.get(key) or []): + n = _normalize(f) + if n: + (inputs if n["type"] == "input" else outputs).append(n) + prompt = item.get("prompt") + graph = prompt[2] if isinstance(prompt, list) and len(prompt) > 2 \ + and isinstance(prompt[2], dict) else {} + for node in graph.values(): + if not isinstance(node, dict): + continue + ct = str(node.get("class_type") or "") + if "LoadImage" not in ct and "ImageLoader" not in ct: + continue + name = (node.get("inputs") or {}).get("image") + if isinstance(name, str) and name: + sub, _, base = name.replace("\\", "/").rpartition("/") + n = _normalize({"type": "input", "subfolder": sub, + "filename": base or name}) + if n: + inputs.append(n) + seen = set() + + def uniq(seq): + r = [] + for f in seq: + k = (f["type"], f["subfolder"], f["filename"]) + if k not in seen: + seen.add(k) + r.append(f) + return r + return uniq(outputs), uniq(inputs) + + +def client_id_of(item): + """history 项里 client_id 的位置在内存态与 HTTP 序列化态不同,两种都要兼容: + * 内存态原始布局:[extra_data, number, prompt] → extra_data 在 [0] + * HTTP 序列化布局:[number, prompt_id, prompt, extra_data, [...]] → extra_data 在 [3] + 先查已知位置;都查不到再退化到在整条记录里递归找第一个含 client_id 的 dict + (client_id 只会出现在 extra_data,不会误命中 workgraph 节点)。 + """ + p = item.get("prompt") if isinstance(item, dict) else None + if isinstance(p, (list, tuple)): + for idx in (3, 0): + if len(p) > idx and isinstance(p[idx], dict) and "client_id" in p[idx]: + return str(p[idx].get("client_id") or "") + r = _find_client_id(item) + return str(r) if r else "" + + +def _find_client_id(o): + """递归找第一个含 client_id 的 dict 的值(退化兜底)。""" + if isinstance(o, dict): + if "client_id" in o: + return o["client_id"] + for v in o.values(): + r = _find_client_id(v) + if r is not None: + return r + elif isinstance(o, (list, tuple)): + for v in o: + r = _find_client_id(v) + if r is not None: + return r + return None + + +def resolve(roots, f): + """(绝对路径, 错误原因)。realpath 后必须仍在对应类型根目录内。""" + t = f.get("type") + if t not in roots: + return None, "unsupported type %r / 服务端未配置该目录" % t + sub, name = f.get("subfolder") or "", f.get("filename") or "" + if not name: + return None, "empty filename" + if os.path.isabs(name) or os.path.isabs(sub): + return None, "absolute path refused" + if "\x00" in name or "\x00" in sub: + return None, "NUL byte refused" + rel = os.path.normpath(os.path.join(sub, name)) + if rel in (".", "..") or rel.startswith(".." + os.sep) or os.path.isabs(rel): + return None, "path escape refused" + base = os.path.realpath(str(roots[t])) + full = os.path.realpath(os.path.join(base, rel)) + if full != base and not full.startswith(base.rstrip(os.sep) + os.sep): + return None, "outside %s root" % t + return full, "" + + +def reference_counts(history, roots): + """{绝对路径: set(引用它的 pid)}。用于跳过被别的任务共用的文件。""" + counts = {} + for pid, item in history.items(): + if not isinstance(item, dict): + continue + outs, ins = files_of(item) + for f in outs + ins: + full, err = resolve(roots, f) + if err: + continue + counts.setdefault(full, set()).add(str(pid)) + return counts + + +def _owned(cid, client_ids, prefixes, require_owner): + if cid and cid in client_ids: + return True, "client_id 精确匹配" + if cid and any(cid.startswith(p) for p in prefixes if p): + return True, "client_id 前缀白名单匹配" + if not require_owner: + return True, "调用方关闭归属校验(不推荐)" + return False, ("client_id=%r 不在白名单;require_owner=true 且未给可用凭证" + % cid) + + +def build_report(history, roots, pids, client_ids=(), prefixes=(), + dry_run=True, purge_input=False, require_owner=True): + """核心逻辑,纯函数 + os.remove,便于离线单测。 + + history: {pid: item} 服务端内存态历史(dict 或 History 对象取出的底层 dict) + roots: {type: realpath} 由 roots_of() 得到,单测可传临时目录 + """ + client_ids = set(str(x) for x in (client_ids or ()) if x) + prefixes = tuple(str(x) for x in (prefixes or ()) if x) + pids = [str(p) for p in (pids or ()) if p][:MAX_PIDS] + refs = reference_counts(history, roots) + # 只有「归属校验通过」的 pid 才算本次任务集合;未归属的 pid 仍然是别人, + # 它引用的文件必须判为 shared,绝不能因为出现在请求里就被当成可删。 + owned_pids = set() + for pid in pids: + it = history.get(pid) + if isinstance(it, dict) and _owned(client_id_of(it), client_ids, + prefixes, require_owner)[0]: + owned_pids.add(pid) + + rep = {"ok": True, "version": VERSION, "dry_run": bool(dry_run), + "purge_input": bool(purge_input), + "owner_check": {"require": bool(require_owner), + "client_ids": sorted(client_ids), + "prefixes": list(prefixes), + "credentials": bool(client_ids or prefixes)}, + "roots": roots, "pids": {}, + "summary": {"dry-run": 0, "deleted": 0, "missing": 0, "shared": 0, + "refused": 0, "skipped-input": 0, "error": 0}, + "warnings": []} + + for pid in pids: + item = history.get(pid) + entry = {"exists": bool(item), "client_id": "", "owned": False, + "owner_reason": "", "files": []} + rep["pids"][pid] = entry + if not isinstance(item, dict): + entry["owner_reason"] = "history 无此 pid(记录已被删/重启/未执行完),拒绝删文件" + rep["warnings"].append("%s: history 不存在,未删任何文件" % pid) + continue + cid = client_id_of(item) + entry["client_id"] = cid + entry["owned"], entry["owner_reason"] = _owned( + cid, client_ids, prefixes, require_owner) + outs, ins = files_of(item) + candidates = [(f, True) for f in outs] + [(f, purge_input) for f in ins] + for f, enabled in candidates: + row = dict(f) + row["bytes"] = 0 + full, err = resolve(roots, f) + if err: + row["status"], row["reason"] = "refused", err + elif not entry["owned"]: + row["status"], row["reason"] = "refused", "归属校验未通过:" + \ + entry["owner_reason"] + elif not enabled: + row["status"], row["reason"] = "skipped-input", \ + "purge_input=false,上传素材默认保留" + else: + others = refs.get(full, set()) - owned_pids + if others: + row["status"] = "shared" + row["reason"] = "被其它任务引用,跳过:%s" % ", ".join( + sorted(others)[:3]) + elif os.path.islink(full): + row["status"], row["reason"] = "refused", "符号链接拒绝删除" + elif not os.path.isfile(full): + row["status"], row["reason"] = "missing", "文件已不存在" + else: + try: + row["bytes"] = os.path.getsize(full) + except OSError: + pass + if dry_run: + row["status"], row["reason"] = "dry-run", "预演,未删除" + else: + try: + os.remove(full) + row["status"], row["reason"] = "deleted", "" + except OSError as e: + row["status"], row["reason"] = "error", str(e) + rep["summary"][row["status"]] = rep["summary"].get(row["status"], 0) + 1 + entry["files"].append(row) + rep["ok"] = rep["summary"].get("error", 0) == 0 + return rep + + +def token(): + return os.environ.get(TOKEN_ENV, "") + + +def _authorized(request, body): + want = token() + if not want: + return True + got = request.headers.get("X-Manju-Token") or \ + (body.get("token") if isinstance(body, dict) else None) + return got == want + + +def _history_dict(): + """兼容 dict 版与新版 History 包装对象的 prompt_queue.history。""" + try: + from server import PromptServer + q = getattr(PromptServer.instance, "prompt_queue", None) + h = getattr(q, "history", None) + except Exception: + return {} + if h is None: + return {} + if isinstance(h, dict): + return h + for attr in ("history", "items"): + v = getattr(h, attr, None) + if isinstance(v, dict): + return v + if callable(v): + try: + return dict(v()) + except Exception: + pass + return {} + + +def _body_list(body, key, alt=None): + v = body.get(key, body.get(alt) if alt else None) + if isinstance(v, str): + return [v] + if isinstance(v, (list, tuple)): + return list(v) + return [] + + +def register(): + """把两条路由写进官方 routes 表;不在 ComfyUI 运行时安静跳过(便于单测)。""" + try: + from aiohttp import web + from server import PromptServer + routes = PromptServer.instance.routes + except Exception as e: + logging.warning("[manju-cleanup] 未注册 HTTP 路由(非 ComfyUI 运行时):%s", e) + return False + + @routes.get(PREFIX + "/ping") + async def ping(request): + return web.json_response({ + "ok": True, "version": VERSION, + "roots": roots_of(_folder_paths()), + "token_required": bool(token()), + "history_size": len(_history_dict()), + "max_pids": MAX_PIDS, + "note": "files are resolved from server-side history by prompt_id only", + }) + + @routes.post(PREFIX + "/purge") + async def purge(request): + try: + body = await request.json() + except Exception: + body = {} + if not isinstance(body, dict): + body = {} + if not _authorized(request, body): + return web.json_response({"ok": False, "error": "unauthorized"}, status=401) + pids = _body_list(body, "pids", "prompt_ids") + if not pids: + return web.json_response({"ok": False, "error": "pids required"}, status=400) + rep = build_report( + _history_dict(), roots_of(_folder_paths()), pids, + client_ids=_body_list(body, "client_ids"), + prefixes=_body_list(body, "owner_prefixes", "prefixes"), + dry_run=bool(body.get("dry_run", True)), + purge_input=bool(body.get("purge_input", False)), + require_owner=bool(body.get("require_owner", True))) + rep["requested"] = len(pids) + return web.json_response(rep) + + logging.info("[manju-cleanup] v%s registered: GET/POST %s/ping|purge " + "(/api prefix mirrored by ComfyUI add_routes)", VERSION, PREFIX) + return True + + +try: + register() +except Exception as _e: # 不让插件加载失败拖垮 ComfyUI 启动 + logging.warning("[manju-cleanup] register failed: %s", _e) diff --git a/assets/config.template.json b/assets/config.template.json new file mode 100644 index 0000000..fa76324 --- /dev/null +++ b/assets/config.template.json @@ -0,0 +1,122 @@ +{ + "_readme": "复制为工作空间的 config/pipeline.json 后填写。带 {{}} 的字段必须改;其余按需调整。JSON 不支持注释,_ 开头的字段都是说明,脚本会忽略。", + "_models": "端点、节点图、API 用法见技能包 references/models.md;部署拓扑与恢复见部署侧文档 deploy/k8s-nvidia/deploy-as-built.md(不在技能包内)。2026-11-13 起图与两种视频都跑在同一个 ComfyUI 0.45 实例上;30111/30112/30113 三个端口指向它(Service selector 改指),调用方零改动。所有地址都是明文 HTTP,调用方必须绕过本机代理。", + "workspace": "{{你的工作空间名}}", + "output": { + "width": 720, + "height": 1280, + "fps": 30, + "vcodec": "libx264", + "acodec": "aac", + "pix_fmt": "yuv420p" + }, + "ffmpeg": { + "binary": "", + "_binary_hint": "留空则运行时用 imageio_ffmpeg.get_ffmpeg_exe()。如需显式指定,先运行 python3 -c 'import imageio_ffmpeg; print(imageio_ffmpeg.get_ffmpeg_exe())'", + "_install": "pip install --user imageio-ffmpeg(静态版)。macOS 12 + Homebrew 6 有 dav1d Ruby bug,不要 brew 安装", + "_watermark": "若源视频有水印,render.py --crop-bottom 60 用 crop 去带;本链路 I2V 输出通常无水印,默认 0,不要白裁画面。不要用 drawbox" + }, + "videoModel": { + "name": "wan2.2-i2v-a14b", + "endpoint": "http://192.168.1.30:30113", + "width": 432, + "height": 768, + "frames": 81, + "fps": 16, + "steps": 4, + "experts": "双专家", + "nominalSeconds": 5.06, + "probe": "按服务端 /system_stats 启动参数预检,不按 RAM 硬挡", + "forbidden": "不要 --force-fp16(fp8 权重升 fp16 会崩);不要跨 prompt 传 conditioning;分辨率面积不要超 832x480(22G 显存墙)", + "_note": "tools/submit_i2v.py 只适配这个 A14B 双专家节点图;默认端点 30113(0.45)与 30112(0.38)都能跑,图里含 ModelSamplingSD3(shift=5)。切到 MiniMax H3 不能只改 endpoint——H3 的采样节点、权重、输出节点全都不同,见 references/models.md §4.3", + "_otherVideoModel": "MiniMax H3(带原生音频):同一个 http://192.168.1.30:30113(ComfyUI 0.45,主用);回退 http://192.168.1.30:30111(0.38,需 --fp16-unet);DCU http://192.168.1.24:30120(0.45)2026-11-13 实测整机不可达。20 步 / res_multistep+simple / 无 LoRA。0.45 实测 320x192x22 帧,0.38 上 960x544x33 帧通过。禁 turbo LoRA(NaN 全黑);与 A14B、出图共用同一实例,只能串行", + "_serial": "30113 是 1 张 22GB 卡 + 4GiB cgroup 内存硬限的单实例:出图、H3 视频、WAN 视频三者互为并发冲突,必须串行提交", + "_recovery": "pod 重建后 /local(emptyDir) 的权重软链会丢,表现为 UNETLoader 只剩 1 个模型 → 容器内执行 sh /basedir/apply-multimodal.sh(幂等)。见部署侧 deploy-as-built.md §6" + }, + "imageModel": { + "name": "minimax-h3-image", + "endpoint": "http://192.168.1.30:30113", + "width": 2048, + "height": 2048, + "steps": 6, + "seed": 42, + "prefix": "H3IMG", + "timeout": 3600, + "_note": "tools/submit_t2i.py 读本段。宽高必须 32 对齐,2048² 起,16MP 最佳;6 步 / cfg1.0 / euler+simple 是蒸馏模型推荐值,不要加步数。", + "_weightAuto": "权重名**不用填**:脚本提交前读端点 /object_info/UNETLoader 自动挑(DCU=w4a8 / K8s-30113=int8_convrot)。端点换权重不用改代码。", + "_endpoints": "K8s http://192.168.1.30:30113(ComfyUI 0.45,int8_convrot,在线,默认)/ DCU http://192.168.1.24:30120(0.45,w4a8,2026-11-13 实测整机不可达)。节点图两套完全一致,只有权重名不同。", + "_k8sNote": "30113 跑在 4Gi cgroup 硬限里(MEM4G 补丁集 22 处 + 显存换入换出),单次出图约 178s。它是单实例多模态:出图、H3 视频、WAN 视频共用一个 pod,只能串行。pod 重建后要跑 /basedir/apply-multimodal.sh 恢复视频权重软链。详见 models.md §2.1 与部署侧 deploy-as-built.md。", + "_promptFile": "给 --ep/--shot 时默认读 projects//40_prompts/.t2i.txt,与 .i2v.txt 运动提示词分开留档", + "_sanity": "出图后脚本会自检 PNG(颜色数/亮度/标准差),纯色图判失败并跳过自动清理 —— H3-Image 量化档位不对时会静默出纯色图。" + }, + "textModel": { + "endpoint": "http://192.168.1.30:30084", + "slot": "qwen", + "model": "qwen3.8-flash", + "_secret": "API Key 用 xop 注入:xop run --secret K=llm_key -- CMD < /dev/null。密钥不落明文,不要写进本文件。", + "_route": "必须按 slot 前缀://v1/chat/completions。直连 /v1/chat/completions 会报『上游 v1 不存在或已停用』。可用 slot:qwen / deepseek / minimax / glm,模型清单见 GET /v1/models", + "_use": "阶段 1 拆剧本、扩写出图提示词;不参与出图出片,可选" + }, + "embed": { + "endpoint": "http://192.168.1.24:8801", + "model": "BAAI/bge-large-zh-v1.5", + "_note": "免密钥,OpenAI 兼容 /v1/embeddings(1024 维)。模型名写 bge-large-zh 会 404。另有 /v1/rerank、/v1/score。可选", + "_status": "⚠️ 2026-11-13 实测 192.168.1.24 整机不可达(8801 / 30120 TCP 均 CLOSED),该向量服务随 DCU 一起下线。当前无向量服务;语义检索类需求先降级为关键词/人工检索,需要时换用别的内网 embedding 端点并改这一行。" + }, + "cleanup": { + "auto": false, + "minBytes": 100000, + "apiBase": "/api", + "nodeApi": "", + "clientIds": [], + "ownerPrefixes": ["manju-"], + "requireOwner": true, + "token": "", + "deleteApi": "", + "commands": { + "http://192.168.1.30:30112": "KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong exec $(KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong get pods -l app=comfyui-wan-h3image -o jsonpath='{.items[0].metadata.name}') -c comfyui -- sh -c \"cd {root} && rm -f -- {files} {temp_files}\"", + "http://192.168.1.30:30111": "KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong exec $(KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong get pods -l app=comfyui-wan-h3image -o jsonpath='{.items[0].metadata.name}') -c comfyui -- sh -c \"cd {root} && rm -f -- {files} {temp_files}\"", + "http://192.168.1.30:30113": "KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong exec $(KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong get pods -l app=comfyui-wan-h3image -o jsonpath='{.items[0].metadata.name}') -c comfyui -- sh -c \"cd {root} && rm -f -- {files} {temp_files}\"" + }, + "command": "", + "outputRoot": "/comfyui/output", + "inputRoot": "/comfyui/input", + "purgeInput": false, + "free": false, + "_rule": "生成并导出成功后必须清理 ComfyUI 服务端的记录与产物,且只清「自己发起的任务」。两个提交脚本支持 --cleanup(显式)/ --no-cleanup(本次跳过);auto=true 则每次导出后自动清。独立命令默认 dry-run,真清需 --apply:python3 tools/cleanup_comfyui.py --ep EP01 --apply", + "_owner": "归属三层凭证:① 本地台账的 promptId 只可能是本技能提交的任务;② 提交脚本用 client_id=manju-i2v-*/manju-t2i-* 并把 clientId 写进台账,ComfyUI 会把它持久化在 history 项 prompt[3]['client_id'];③ 清理时按「台账 clientId 精确匹配 > ownerPrefixes 前缀白名单」判归属,未通过一律拒绝、不调用任何删除接口(fail-closed)。老台账没有 clientId 的任务,把那些 client_id 加进 clientIds 才会被清;requireOwner 别改 false。", + "_extension": "官方没有任何删除 output/ 产物文件的 HTTP 路由,所以技能自带扩展 assets/comfyui-manju-cleanup/:整目录拷到各端点的 ComfyUI/custom_nodes/ 并重启进程,即自动获得 GET /manju/cleanup/ping 与 POST /manju/cleanup/purge(官方 add_routes 会镜像出 /api 前缀)。nodeApi 留空则脚本自动探测;扩展只按 pid 从服务端 history 反查产物、二次校验 client_id、检查路径逃逸与跨任务共用引用,不接受任意文件路径。可选环境变量 MANJU_CLEANUP_TOKEN 开启鉴权,对应把 token 填这里。部署状态:DCU 30120 已实装并实测 ping 200(但该机 2026-11-13 起不可达);K8s 三个端点均未装,走下面的 commands 降级模板;K8s 的 ConfigMap manju-cleanup-node 已创建,但 patch Deployment 会触发 rollout、清空所有人的内存态 history,需人工确认后再做(命令见 models.md §3.4)。", + "_standardApi": "记录删除仍走官方标准接口:GET /api/history/ 抽产物清单与 client_id → POST /api/history {\"delete\":[pid,...]} + POST /api/queue {\"delete\":[pid,...]} 批量删 → GET /api/history/ + /api/queue 复核「从有到无」→ 整批结束 POST /api/free {\"unload_models\":true,\"free_memory\":true}。apiBase 留 \"/api\";脚本先探 /api/system_stats,老版本不支持时自动回退无前缀。", + "_order": "装了扩展时顺序变了:预览 purge(dry_run=true) → purge(dry_run=false) 删服务端文件 → 官方 POST /api/history|/queue 删记录 → 复核 → /free。purge 依赖 history 反查文件名,必须先删文件再删记录;反序会永远查不到产物。没装扩展时保持旧顺序(先抽清单 → 删记录 → 复核 → 删文件)。", + "_200EmptyBody": "官方这些 POST 一律返回 200 空 body 且幂等:删不存在的 pid 也返回 200。绝不能把 200 当「删除成功」,脚本删后会复核;GET /history/ 的 {} 还有「排队/执行中/不存在」三义,所以判据是删前有、删后无。禁用 {\"clear\":true}(会清掉别人的任务)。", + "_community": "扩展没装时自动降级:① 装了 comfyui_extra_api(DELETE /comfyapi/v1/output-images/{filename})或 ComfyUI-api-tools(DELETE /api-tools/v1/images/output/{filename}),把 deleteApi 填成 comfyui_extra_api / api-tools,脚本优先走标准 DELETE(只管不带子目录的图片);② 否则按端点在 commands 里配 shell 模板删文件。两条降级路线都仍然受归属闸门约束。", + "_noHttpDelete": "DELETE /userdata/{file} 只管 ComfyUI/user/,DELETE /api/assets/{id} 要 --enable-assets(现网实测 503)且删的是数据库引用,都不能删 output/ 里的 mp4/png。没配模板也没装扩展时脚本只打印精确清单,绝不假装已删。", + "_freeHint": "free 只设队列 flag,真正卸载发生在下一个队列循环。整批做完统一调用一次即可,不要每镜调用——4Gi 环境下重新加载模型要几分钟。命令行加 --free 可临时触发。", + "_commandsExample": "默认已配好 K8s 三条(30113 主用 / 30111 / 30112):动态取 pod 名 + KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong + kubectl exec rm,outputRoot=/comfyui/output,实测 /comfyui/output 可写(软链到 PVC /basedir/output)。DCU 30120 已装扩展,走 HTTP purge,不需要模板;若哪天要给它配,用 ssh + docker exec comfyui-h3,output 根 /home/ComfyUI/output。已有工作空间若把 cleanup.commands 覆盖成 {},需删掉该键以用默认值或手工补回模板。要连上传首帧一起删,在模板里另加 cd {input_root} && rm -f -- {input_files}。", + "_placeholders": "{files}=output 产物(含 subfolder,逐个 shell 转义),{temp_files}=temp,{input_files}=上传首帧(仅 purgeInput=true 时非空),{root}=outputRoot,{input_root}=inputRoot。模板里 {root} 自带转义,不要再包一层引号。", + "_purgeInputHint": "上传的首帧图可能被多个镜或别人共用,默认只列不删;扩展会做跨任务引用计数,被别的 pid 引用的文件判 shared 并跳过。确需删时设 purgeInput=true,并在模板里另加一段 cd {input_root} && rm -f -- {input_files}。", + "_localKeep": "清理只针对服务端。本地已导出的成片、40_prompts/ 提示词原文、30_shots.json、50_manifest.json 一律保留;台账默认只移除 promptId 并记 cleanedAt,独立命令加 --purge-ledger 才删整条。", + "_selftest": "部署前后可用 python3 tools/selftest_cleanup.py 自检:mock ComfyUI 验证归属拒绝、dry-run 零副作用、扩展优先级、删后复核、锚图台账扫描,29 项断言。", + "_scanScope": "清理脚本递归扫工作空间下所有 t2i_runs.json / a14b_runs.json —— 台账写在 os.path.dirname(out),位置随输出路径变(--ep 出图落 work//images/,裸 --out 出的锚图落图片同目录如 assets/characters/)。**不带 --ep 跑一次**才能把锚图等集外任务一起清掉。每个任务的实际端点取自台账的 endpoint 字段,不靠配置猜。" + }, + "tts": { + "engine": "edge-tts", + "voice": "zh-CN-YunjianNeural", + "keyRequired": false, + "licenseNote": "免费免密钥不等于可商用;商用前自行核对微软条款" + }, + "subtitle": { + "source": "30_shots.json 的 line 字段(完整旁白)", + "wrap": "按标点折 1–3 行,标点不落单", + "note": "不交给生成模型烧字" + }, + "hud": { + "variants": ["横排", "竖排"], + "rule": "全片文字标注只出现一次(一横一竖),不要每个镜头都标" + }, + "outro": { + "elements": ["光环", "光束", "星点"], + "motion": "zoompan 缓推", + "note": "用 make_overlay.py 程序化生成,零积分" + } +} diff --git a/assets/events.template.md b/assets/events.template.md new file mode 100644 index 0000000..98e04d0 --- /dev/null +++ b/assets/events.template.md @@ -0,0 +1,6 @@ +# EP{ep} 源节拍账本 + +一行一个 E##,30–60 字,只写影响主线的动作,不复述整段对话。 +每个会改变剧情状态的提示词句子都必须映射回这里的 E##。 + +- E01|待填写:谁做了什么 → 造成什么结果 → 情绪 → 预估秒数 diff --git a/assets/policy.template.md b/assets/policy.template.md new file mode 100644 index 0000000..bdb159f --- /dev/null +++ b/assets/policy.template.md @@ -0,0 +1,26 @@ +# 叙事与合规清单(模板) + +复制为项目根或 `projects/EPxx/` 下的实际清单,逐条填写。**生成前必须过一遍**,结论写进 `00_brief.md` 的「禁忌」栏。 + +## 项目专属(每次必须重写) + +| 项 | 本项目填写 | +|---|---| +| 不出现的现实项目名 / 机构名 | | +| 不出现的政治符号 / 敏感标识 | | +| 不出现的真实品牌 / logo / 水印 | | +| 原著中需整章避开的部分 | | +| 是否允许派生内容回灌知识库 | □ 否(默认) □ 是,目标:____ | +| 固定角色与音色 | | + +## 通用硬约束(不可删) + +- **重编不是缩写**:改写保留源节拍,不把长段压成梗概;每个改变剧情状态的句子都要映射回 `E##`。 +- **不补前史**:原文给「手里已拿着」就从该状态开始,不补拿容器、开盖、取出的过程。 +- **不出现可识别的真实人物肖像**(除非获得授权)。 +- **生成阶段不烧字幕 / 文字 / UI 叠字**,文字一律留给后期。 +- **商用前核对**:TTS 音色授权、AI 生成内容标识要求、素材版权。 + +## 闸门 + +生成前展示:对象与数量、模型、完整提示词、实际参考、规格、执行次数,取得明确授权。「继续」/ 沉默 / 工具失败都不构成新的授权。 diff --git a/assets/prompts.template.md b/assets/prompts.template.md new file mode 100644 index 0000000..f868cfe --- /dev/null +++ b/assets/prompts.template.md @@ -0,0 +1,22 @@ +Sxx|E##|时长:X.XXs|模型:{{模型名}}|{{宽}}x{{高}} / {{帧数}}帧 / {{fps}}fps / {{步数}}-step + +[首帧锚] +逐张写清 refs 中的参考图路径与用途;不要编造画布句柄 + +[首帧锁定] +人物站/坐/朝向/画面左右 · 持物 · 关键道具位置 · 机位距离与高度 · 前中后景 + +[画面] +一句可见画面,不写抽象情绪;情绪从动作偏差泄露 + +[轻运动] +呼吸 / 光点流动 / 单一缓推,任选其一;禁止大幅肢体动作、快速转身、多人换位 + +[正向锁] +写**可判定状态**:双臂垂在体侧 / 手始终低垂 / 细光保持细线 / 双手不触及不跨越 / 不转身 / 不变走廊 + +[文字锁] +无字幕、无额外屏幕文字、无后期叠字、无水印;实体文字保持参考资产,不新增、不改写、不重绘 + +[Avoid] +只写本镜真实风险的 2–4 条;禁止项放最后强调 diff --git a/assets/script.template.md b/assets/script.template.md new file mode 100644 index 0000000..1812318 --- /dev/null +++ b/assets/script.template.md @@ -0,0 +1,5 @@ +# EP{ep} 剧本 / 旁白 + +待填写。旁白全文逐字写入 `30_shots.json` 的 `line`,配音阶段按实测时长回填 `duration`。 + +写完做一次**唯一性检查**:`len(lines) == len(set(lines))`,且本表与 `30_shots.json` 逐字一致。 diff --git a/assets/shot.schema.json b/assets/shot.schema.json new file mode 100644 index 0000000..e53a54b --- /dev/null +++ b/assets/shot.schema.json @@ -0,0 +1,58 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "xv shot list", + "type": "object", + "required": ["episode", "targetDuration", "shots"], + "properties": { + "episode": { "type": "string", "pattern": "^EP[0-9]{2}$" }, + "brief": { "type": "string" }, + "targetDuration": { "type": "number", "exclusiveMinimum": 0 }, + "tolerance": { "type": "number", "default": 3.0 }, + "spec": { "type": "object" }, + "model": { "type": "object" }, + "shots": { + "type": "array", + "minItems": 1, + "items": { "$ref": "#/definitions/shot" } + } + }, + "definitions": { + "shot": { + "type": "object", + "required": ["shotId", "eventIds", "visual", "duration", "status"], + "properties": { + "shotId": { "type": "string", "pattern": "^S[0-9]{2}$", "description": "镜号,全表唯一" }, + "eventIds": { + "type": "array", + "items": { "type": "string", "pattern": "^E[0-9]{2}$" }, + "minItems": 1, + "description": "映射回 10_events.md 的源节拍 E##,禁止无源新增动作" + }, + "scene": { "type": "string" }, + "shotType": { "enum": ["大特写", "特写", "近景", "中景", "全景", "远景"] }, + "subject": { "type": "string", "description": "拍摄主体,供段间衔接三条件校验" }, + "angle": { "type": "string", "description": "正面/侧面/背面/过肩/俯视/仰视,含大致角度" }, + "visual": { "type": "string", "description": "画面描述,不可为空" }, + "line": { "type": "string", "description": "台词或旁白原文,逐字不改" }, + "duration": { "type": "number", "exclusiveMinimum": 0 }, + "pad": { "type": "boolean", "description": "duration 超过模型标称时长时须置 true(tpad clone 补足)" }, + "characters": { "type": "array", "items": { "type": "string" } }, + "refs": { "type": "array", "items": { "type": "string" }, "description": "assets/ 相对路径,首帧锚图等" }, + "motion": { "type": "string", "description": "轻运动:呼吸/转头/镜头缓推;避免大幅肢体动作" }, + "voice": { "type": "string", "description": "有 line 必填,固定音色" }, + "promptFile": { "type": "string", "description": "40_prompts/ 下的提示词原文文件" }, + "promptHash": { "type": "string", "description": "提示词内容 sha256 前 8 位" }, + "continuity": { + "type": "object", + "properties": { + "relation": { "enum": ["continuous", "partial", "reset"] }, + "initialState": { "type": "string", "description": "本段绝对初始状态,禁止写『延续上一段』" }, + "endState": { "type": "string" } + }, + "required": ["relation"] + }, + "status": { "enum": ["planned", "prompted", "generated", "adopted", "rejected"] } + } + } + } +} diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..d4edd39 --- /dev/null +++ b/install.sh @@ -0,0 +1,107 @@ +#!/usr/bin/env bash +# ai-manju 安装 / 体检:把技能接入各 agent 的 skills 目录 +# ./install.sh 建软链(已正确则跳过;遇到实体目录不覆盖) +# ./install.sh --check 只读体检,不改任何文件 +set -uo pipefail + +HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +NAME="ai-manju" +CHECK=0 +[ "${1:-}" = "--check" ] && CHECK=1 + +echo "技能源:$HERE" +echo + +# 1) 完整性 +ok=1 +for f in SKILL.md scripts/manju.py scripts/submit_i2v.py scripts/submit_t2i.py scripts/cleanup_comfyui.py \ + scripts/selftest_cleanup.py scripts/render.py assets/config.template.json assets/shot.schema.json \ + assets/comfyui-manju-cleanup/__init__.py references/pitfalls.md references/models.md; do + if [ ! -f "$HERE/$f" ]; then echo "✗ 缺少 $f"; ok=0; fi +done +[ "$ok" = 1 ] && echo "✓ 技能包完整" +[ "$ok" = 0 ] && exit 1 + +# 2) 依赖(只提示不强制:setup/validate/manifest 不需要这些) +python3 -V 2>/dev/null || echo "⚠ 未找到 python3(脚本必需)" +if python3 -c 'import imageio_ffmpeg' 2>/dev/null; then + echo "✓ imageio-ffmpeg(渲染/审片)" +else + echo "⚠ 缺 imageio-ffmpeg:pip install --user imageio-ffmpeg(不要 brew 装)" +fi +if python3 -c 'import edge_tts' 2>/dev/null; then + echo "✓ edge-tts(配音)" +else + echo "⚠ 缺 edge-tts:pip install --user edge-tts(仅配音阶段需要)" +fi +echo + +# 3) 软链。技能包在 ~/.agents/skills/ 下时用相对软链,便于整体搬迁;否则用绝对路径 +realpath_of() { python3 -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "$1" 2>/dev/null; } +STD="$HOME/.agents/skills/$NAME" +if [ "$(realpath_of "$HERE")" = "$(realpath_of "$STD")" ]; then + TARGET="../../.agents/skills/$NAME" + echo "链接方式:相对软链(遵循单一真相源 ~/.agents/skills/)" +else + TARGET="$HERE" + echo "链接方式:绝对软链(技能包不在 ~/.agents/skills/ 下)" +fi +echo + +rc=0 +found=0 + +# --check 追加:语法 / JSON / 清理链路自检(只读,不写技能包) +if [ "$CHECK" = 1 ]; then + if python3 - "$HERE" <<'PY' +import ast, json, pathlib, sys +root = pathlib.Path(sys.argv[1]) +for p in sorted(root.rglob("*.py")): + ast.parse(p.read_text(encoding="utf-8"), filename=str(p)) +for p in sorted(root.rglob("*.json")): + json.loads(p.read_text(encoding="utf-8")) +PY + then + echo "✓ Python 语法 / JSON 全部合法" + else + echo "✗ 存在语法错误或非法 JSON" + rc=1 + fi + if python3 "$HERE/scripts/selftest_cleanup.py" >/dev/null 2>&1; then + echo "✓ 清理链路自检通过(扩展 + 归属 + 顺序 + 复核)" + else + echo "✗ 清理链路自检失败,手动跑:python3 scripts/selftest_cleanup.py" + rc=1 + fi +fi + +for d in "$HOME/.claude/skills" "$HOME/.workbuddy/skills" "$HOME/.qwenworkcn/skills"; do + [ -d "$d" ] || continue + found=1 + link="$d/$NAME" + if [ -L "$link" ]; then + if [ "$(realpath_of "$link")" = "$(realpath_of "$HERE")" ]; then + echo "✓ 已就位 $link -> $(readlink "$link")" + else + echo "⚠ 指向他处 $link -> $(readlink "$link")(未改动,请手动处理)" + fi + elif [ -e "$link" ]; then + echo "✗ 冲突:$link 是实体,未覆盖;请备份后删除再运行" + rc=1 + elif [ "$CHECK" = 1 ]; then + echo "+ 待建立 $link -> $TARGET" + else + mkdir -p "$d" + ln -s "$TARGET" "$link" + echo "+ 已建立 $link -> $TARGET" + fi +done +[ "$found" = 0 ] && echo "⚠ 未发现任何 agent 的 skills 目录;请手动把本技能目录放入对应位置" + +echo +if [ "$CHECK" = 1 ]; then + echo "(--check 只读体检完成,未改动任何文件)" +else + echo "安装完成。新开一个 agent 会话即可被识别;也可用 triagent-sync --skills-agents 同步。" +fi +exit "$rc" diff --git a/references/director.md b/references/director.md new file mode 100644 index 0000000..27e7028 --- /dev/null +++ b/references/director.md @@ -0,0 +1,69 @@ +# 导演内核(与模型无关的规则) + +从 Toonflow `workflow/SKILL.md` PART A 剥离的执行规则。上游原文逐字留档在 [toonflow/toonflow-workflow-director.md](toonflow/toonflow-workflow-director.md)(MIT),条款号 A0.1 / A2 / A5 / A8 / A11.4 / A12 沿用,需要原文时按号查。**本文件只做适配,不改写原文。** + +## 参数覆盖表(去画布化) + +| 项 | 画布型工具(上游) | 本管线 | +|---|---|---| +| 单段上限 | Seedance ≤15s / ≤30s | 取 `config/pipeline.json` 的 `frames/fps`(A14B 默认 81@16 ≈ 5.06s);超出需 `pad:true` 用 `tpad=stop_mode=clone` 补 | +| 参考绑定 | `{{node/image-xxxx}}` 画布句柄 | `refs` 中的 `assets/` 相对路径;**禁止编造句柄** | +| 状态载体 | 画布节点 / MCP 工具 | `30_shots.json` 一行一镜 + `50_manifest.json` | +| 提示词外壳 | A9.1 资产标识 + A9.2 Objective 九字段 | 下方「I2V 提示词模板」:首帧锚 + 轻运动 + 锁 + 避免 | +| 授权 | 宿主 `askUser` | 阶段闸门:展示清单后等明确确认 | +| 校验 | LLM 按 A11 勾选 | `manju.py validate` 机器前置 + 本文件规则人工复核 | + +A9.2 的 `Objective / Immutable locks / Preserve / Avoid` 语义保留,但不照搬英文九字段外壳。 + +## 十二条铁律 + +1. **只导演,不编剧**(A0.1):禁止新增 / 删除 / 替换 / 改归属 / 改顺序五类改动。AI 上一轮自行补的内容**永远不能升级成剧情事实**(事实优先级:用户最新指令 > 原始剧情 > 已确认资产 > AI 旧输出)。 +2. **不补前史**(A0.1.4):原文给「手里已拿着」就从该状态开始,不补「拿容器 → 开盖 → 取出」。模糊身份保持抽象。 +3. **全量节拍**(A2):先建 `E01…E##` 源节拍账本登记在 `10_events.md`,所有原子节拍保留,不能只挑转折点。每个会改变剧情状态的句子必须映射回 `E##`。 +4. **时长诚实**(A2.3 / A3.2):按自然语速估对白 + 必要停顿 + 串行动作;**禁止加快语速、删词、吞句尾**塞时长。严格冲突时标注冲突,不删剧情。 +5. **每段自包含**(A5):模型看不到上一段画面。首帧锁(站/坐、画面左右、身体朝向、持物、道具位置、机位高度、前中后景)逐段重写;`initialState` 写绝对状态,禁止「同上 / 延续上一段」。 +6. **站位双层**:世界坐标(相对门/桌/窗,与机位无关)+ 画面坐标(随机位重述)。画面左右可因合法换机位变化,**世界位置不能偷搬**(A5.4 不越轴不等于机位不能换)。 +7. **段间衔接**(A7.3):相邻两镜至少满足一项——主体类型不同 / 景别差 ≥2 档 / 角度差 ≥90°。不满足时只调下一段首镜的摄影属性,不动剧情事实。 +8. **连续性先判关联**(A8.1):`continuous` / `partial` / `reset` 三选一。无关段不强行继承位置;`partial` 只继承持续状态(服装破损、伤势、道具剩余量)。道具状态链查「持有人/位置/数量/开合/液面/损耗」,**没拍到 ≠ 消失**。 +9. **文字锁**(A1.3 / A12.17):字幕、标题、UI 叠字、水印留给后期;实体资产文字保持参考外观,不新增/改写/重绘。 +10. **生成稳定性预检**(A11.4):3+ 主体大幅移动、精细手部接触叠复杂运镜、镜面反射复制人物、多张参考争夺同一维度、提示词自相矛盾 → 标记高风险,按「删无关控制 → 简化摄影机 → 关键接触完整可见 → 降景深冲突 → 定向 Avoid」降复杂度。**不以稳定为由删剧情**。 +11. **单次修正**(A11.2 / A12.19):失败项一次性汇总,只做一轮集中结构修正,再单次抛光;禁止 A11 ↔ A12 递归。 +12. **版本与事实分离**(stateAndDelivery):确认绑定独立快照;提示词版本与结果版本分开,改文字不代表旧视频由新文字生成;`generating` ≠ 完成;文件路径 ≠ 看过视频。 + +## I2V 提示词模板(写进 `40_prompts/Sxx.i2v.txt`) + +```text +Sxx|E##|时长:X.XXs|模型:{{模型名}}|{{宽}}x{{高}} / {{帧数}}帧 / {{fps}}fps / {{步数}}-step + +[首帧锚] + + +[首帧锁定] +人物站/坐/朝向/画面左右 · 持物 · 关键道具位置 · 机位距离与高度 · 前中后景 + +[画面] +<一句可见画面,不写抽象情绪;情绪从动作偏差泄露> + +[轻运动] +呼吸 / 光点流动 / 单一缓推,任选其一;禁止大幅肢体动作、快速转身、多人换位 + +[正向锁] +<可判定状态:人物绝对位置 · 道具持有与数量 · 视线 · 细光保持细线 · 双手不触及> + +[文字锁] +无字幕、无额外屏幕文字、无后期叠字、无水印;实体文字保持参考资产,不新增、不改写、不重绘 + +[Avoid] +<只写本镜真实风险的 2–4 条:身份漂移、多余手指、场景脑补、几何融化…> +``` + +**模板内不放变量**:角色/画风的固定描述段放 `assets/style/`,逐字复用不改写;变量只在 `30_shots.json`。 + +## 输出契约与闸门 + +必须产出:`10_events.md`(E## 账本)、`30_shots.json`(一镜一行)、`40_prompts/Sxx.i2v.txt`(逐条原文)、`50_manifest.json` 初始索引。写完跑 `manju.py validate`,ERROR 清零才进下一阶段。 + +- 不消耗算力、不写未授权文件、不把提示词当作已生成的成片。 +- 生成前展示:对象与数量、模型、完整提示词、实际参考、规格、执行次数,取得明确授权。 +- 交付区分「已生成 / 已采用 / 已合成 / 已归集」。 +- 遵守项目 `policy` 清单(叙事禁忌、授权、知识库回灌)。 diff --git a/references/models.md b/references/models.md new file mode 100644 index 0000000..bf17024 --- /dev/null +++ b/references/models.md @@ -0,0 +1,701 @@ +# 内网模型服务与 API 用法 + +> **本技能是编排层**:出图、出视频都调内网 HTTP 端点。本文是端点、节点图与调用约定的**唯一真相源**。 +> 2026-11-11 逐条实机核对;**2026-11-13 重核并合并为单实例**(`/system_stats`、`/object_info`、三种模态实跑验证)。 +> 部署拓扑、4 GiB cgroup 限制、补丁集与 pod 重建后的恢复步骤,见部署侧文档 +> `~/WorkBuddy/2026-11-08-19-43-52/deploy/k8s-nvidia/deploy-as-built.md`。 +> 所有地址都是**内网明文 HTTP**;本机代理会把响应改写成 `text/html`,调用**必须绕过代理**(见 §3.2)。 + +--- + +## 0. 服务地图:1 个多模态实例 + 2 个回退端点 + 2 个辅助 + +> ⚠️ **2026-11-13 重大变更:三个 ComfyUI 已合并为一个实例。** +> **`192.168.1.30:30113`(ComfyUI 0.45.0)一个端点同时提供 H3-Image 文生图、H3 视频(带音轨)、Wan2.2 I2V。** +> 能力差异只取决于**权重 + 节点图**,不取决于容器:0.45 核心自带 `MiniMaxH3` / `MiniMaxH3Image` / +> `Wan21` / `Wan22` 与 `nodes_wan.py` / `nodes_minimax_h3.py`,权重挂在共享 NFS 上按需软链。 +> 部署拓扑、4 GiB 内存硬限、补丁集与**pod 重建后的恢复步骤**见部署侧文档 +> `~/WorkBuddy/2026-11-08-19-43-52/deploy/k8s-nvidia/deploy-as-built.md`。 + +| 能力 | 模型 | 端点 | ComfyUI | 音轨 | 状态 | +|---|---|---|---|---|---| +| **文生图** | MiniMax H3-Image(int8_convrot) | **`http://192.168.1.30:30113`** | 0.45.0 | — | ✅ **主用** | +| **视频①** | MiniMax H3(w6a8,**原生同步音频**) | **同一个 `30113`** | 0.45.0 | ✅ aac | ✅ **T2V 主用**(20 步 / 无 LoRA);⚠️ I2V 见下方警告 | +| **视频②** | Wan2.2 I2V A14B(双专家 + 4-step LoRA) | **同一个 `30113`** | 0.45.0 | ❌ | ✅ **主用**(4 步 / 两段式) | +| 回退·视频 | H3 / WAN | `http://192.168.1.30:30111` / `:30112` | **0.45.0** | H3 ✅ | **已并入 30113**(Service selector 改指),端口照旧可用、调用方零改动 | +| 回退·文生图 | MiniMax H3-Image(w4a8) | `http://192.168.1.24:30120` | 0.45.0 | — | ⚠️ DCU 整机不可达 | +| 文(辅助) | `ipass-all` LLM 代理(OpenAI 兼容) | `http://192.168.1.30:30084` | — | — | 运行中,需 API Key | +| 文(辅助) | `embed-bge` 向量化 / rerank | `http://192.168.1.24:8801` | — | — | ⚠️ 已下线(随 DCU 一起挂) | + +> 🔴 **2026-11-14 实机复核:H3 视频在 2080Ti 上只有 T2V(文生视频)可用。** +> `MiniMaxH3ImageToVideo` 一旦带 `first_frame` / `last_frame`(首帧锁图 I2V),节点会执行 `vae.encode()` +> 并把 video VAE 一路持有到采样期,TE 14.96 G + VAE 4.97 G 焊死在 22 GB 卡上,UNET 只能部分加载, +> 采样阶段必 `CUDA out of memory`(实测干净态重放仍复现,降分辨率/帧数无效)。 +> **11-13 验证通过的权威配方是 T2V,无 `first_frame`**:`api/wan22_h3_api.json` / `gen_video.py --kind h3`。 +> 需要首帧锁图 → 走 **Wan2.2 I2V A14B**(§1)或 DCU K100 64G(§4.2,整机当前不可达)。 +> 详见本文 §4.3 与部署侧 `~/WorkBuddy/2026-11-08-19-43-52/deploy/k8s-nvidia/deploy-as-built.md` §8。 + +**一卡一实例**:30113 独占 1 张 2080 Ti(22 GB,`nvidia.com/gpu: 1`)并受 4 GiB cgroup 内存硬限, +**所有请求只能串行**,并发必 OOM(exit 137)。`30111` / `30112` 现在是同一实例的别名,**同样只能串行**。 + +**版本差异仍然存在,不要照搬**:DCU 是 ROCm、K8s 是 CUDA。K8s 侧 0.38 核心已于 2026-11-13 下线 +(三个端口现已统一为 0.45),但 **DCU(ROCm)与 K8s(CUDA)之间**的采样节点、`SaveVideo.format`、内存补丁、 +量化档位仍不通用。跨端点复用工作流前先查 `/system_stats` 的版本。 + +> **2026-11-13 起:三个端口全部指向同一个 0.45.0 实例。** +> 旧的 `comfyui-wan-h3` / `comfyui-wan-a14b` deployment 已 scale 到 0, +> 两个旧 Service 的 selector 改指 `app=comfyui-wan-h3image`, +> NodePort 30111 / 30112 **保持不变** —— 调用方零改动,但自动获得 0.45 的全部能力。 +> 实测三个端口的 `/system_stats` 均为 `0.45.0`、1060 个节点。 + +> **节点层面 30113 是旧 30112 的严格超集**(实机核对): +> 旧 30112 共 964 个节点、30113 共 1060 个,**30112 没有任何独有节点**; +> 30113 多出的 96 个全是 0.45 新增(Breeze / HeyGen / Kling / Flux3 / Bria 等)。 +> 6 个共有节点的签名差异**全部是「30113 多一个可选参数」**(如 `CreateVideo.chroma_subsampling`), +> 向后兼容。**所以旧工作流可原样使用**,已用生产工作流实测通过。 + +--- + +## 1. 两个视频模型怎么选 + +| 维度 | H3(视频①) | Wan2.2 A14B(视频②) | +|---|---|---| +| 定位 | 有声音、画质优先、环境音/对白镜头 | 静音动作镜头、批量抽卡、快速迭代 | +| 端点 | **30113**(0.45,主用);30111/30112 已并入同一实例 | **30113**(0.45,主用);30112 已并入同一实例 | +| 输入 | **2080Ti 上仅 T2V 验证通过**;`first_frame` 图生视频会 OOM(见 §0 警告 / §4.3) | **图生视频为主**(I2V 模型,给首帧最佳),也能纯文生 | +| 音轨 | **原生同步音频**,提示词里写 `overall_soundscape:` / `non_diegetic_music:` | 无,需后期用 `tts.py` + `render.py` 混音 | +| 安全规格 | 30113 实测 **320×192 / 22 帧 / 20 步**;0.38 上 960×544 / 33 帧通过;DCU 1344×768 / 24 帧 | **832×480 / 81 帧(4n+1)/ 4 步 / 16 fps** | +| 单段时长 | 22 帧 @24fps ≈ 0.9 s;0.38 的 33 帧 ≈ 1.6 s | 81 帧 @16fps ≈ 5 s | +| 实测耗时 | 30113 上 20 步含冷加载约 7–10 min(其中加载占 4–7 min) | 4 步,明显快;同样含冷加载 | +| 采样接口 | **0.45(CUDA):`SamplerCustomAdvanced`**(无 SigmaShift);0.45(ROCm/DCU):`KSampler`+`MiniMaxH3SigmaShift`;0.38:`SamplerCustomAdvanced` | `WanImageToVideo` → `ModelSamplingSD3(shift=5)` → `KSamplerAdvanced` ×2(双专家接力) | +| 禁用项 | **turbo LoRA**(合进 w6a8 量化权重 → 画面全 NaN)、`int8_convrot`(DCU 黑屏) | 超分辨率/帧数 → CUDA OOM;`--force-fp16` → 崩溃 | + +**决策树** + +``` +镜头需要原生环境音/同期声? → H3 T2V(30113,20 步、无 LoRA) +要用已有首帧/锚图驱动生成视频? → A14B I2V(30113);**不要给 H3 塞 first_frame**,2080Ti 上必 OOM +只要画面、要快速抽卡/批量出静音片段? → A14B(30113,同一实例,4 步) +要出角色锚图或分镜首帧? → H3-Image(30113,见 §2) +``` + +> 三者现在**同一个端点、同一个容器**,切换模型只是换节点图,不换地址;但共享一张 22 GB 卡与 4 GiB 内存, +> **必须串行**。H3 的音频是模型生成的**整体声场**,不是指定台词的配音。角色对白仍走阶段 3 的 `tts.py`; +> 两者在 `render.py` 里注意别叠成双份。 + +--- + +## 2. 文生图:MiniMax H3-Image(出锚图与首帧) + +> **2026-11-13 实测更新**:原默认端点 DCU `192.168.1.24:30120` **整机已不可达**(30120 / 8801 两个端口 TCP 均 CLOSED)。 +> 当前可用的是 K8s `192.168.1.30:30113`,而且它**同时承担 H3 视频与 WAN I2V**(见 §0)。 +> 两端**节点图完全一致**,只有权重名不同 —— 脚本已改成自动探测权重,换端点不用改代码。 + +### 2.0 两个端点怎么选 + +| 端点 | ComfyUI | DiT 权重 | 状态 | 备注 | +|---|---|---|---|---| +| **`192.168.1.30:30113`** | 0.45.0 | `minimax_h3_image_pruned_int8_convrot.safetensors` | ✅ **在线(默认,唯一主用)** | 4 GiB cgroup 硬限 + MEM4G 补丁集;单次 1024²≈178s、2048²≈208s;**同一实例兼跑两种视频,请求要串行** | +| `192.168.1.24:30120` | 0.45.0 | `minimax_h3_image_pruned_w4a8.safetensors` | ❌ 2026-11-13 实测整机不可达 | 同一台还托管着 LLM 代理(30084)与 embed-bge(8801),**那两个辅助服务也一起没了** | + +**节点图两套完全一样**,照搬不会错;只有 `UNETLoader.unet_name` 不同: + +| 端点 | `unet_name` | 为什么不能换 | +|---|---|---| +| DCU 30120 | `..._w4a8.safetensors` | **不要用 int8_convrot** —— gfx928 上 convrot 的 `rint` 有 bug → NaN → 纯黑图 | +| K8s 30113 | `..._int8_convrot.safetensors` | **没有 w4a8** —— w4a8 的 CUDA 加速路径要求 sm_80,2080Ti 是 sm_75 跑不了 | + +> ⚠️ 这两条规则方向相反,**千万别照搬**。 +> 另一个坑:2080Ti(sm_75)无原生 bf16,ComfyUI 会退回 fp32 把未量化层撑大。 +> 30113 靠 `should_use_bf16()` 补丁放开了软件模拟 bf16 —— **绝不能改成 fp16**: +> fp16 动态范围仅 ±65504,H3-Image 的 adaln/timestep 缩放会溢出成 inf → NaN → 出图全黑。 + +### 2.1 K8s 30113 的运行约束(与 DCU 完全不同) + +30113 跑在**租户 4Gi cgroup 硬限、无 swap**里,是当前**唯一的主用端点**(图 + H3 视频 + WAN)。几条必须知道的: + +| 项 | 值 | +|---|---| +| 启动参数 | `--cache-none --reserve-vram 1.0 --disable-pinned-memory --disable-cuda-malloc`(**禁 `--fp16-unet`**) | +| 内存墙 | TE(14.96GB) 与 DiT(19.5GB) 共存于 22GB 卡,必须「换入换出」;靠 MEM4G 补丁集(14 处,7 族)解决 | +| 显存账 | TE 14960MB → 卸载后 8MB(延迟 GC 打破引用环 + VRAM 换回 mmap 视图) | +| 耗时 | 1024²≈178s;视频 20 步约 7–10 min(**其中 4–7 min 是冷加载**) | +| 串行 | **一个 pod 一张卡**;图、H3 视频、WAN 全在这一个实例里,**三者互为并发冲突** | +| 恢复 | `/local` 是 emptyDir,**pod 重建后必须跑 `/basedir/apply-multimodal.sh`**,否则只剩出图能力(见部署侧 `deploy-as-built.md` §6) | +| 清理 | **未装** `manju-cleanup` 扩展 → 走 `cleanup.commands` 的 `kubectl exec` 降级模板(已默认配好) | + +出图端点 `output` 根是 `/comfyui/output`(软链到 PVC `/basedir/output`),与 30111/30112 一致, +`cleanup.commands` 已默认带 `http://192.168.1.30:30113` 这条模板。 + +### 2.2 参数与提示词 + +| 项 | 值 | +|---|---| +| DiT | 见 §2.0 端点表(权重名随端点变,脚本自动探测) | +| CLIP | `qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors`(与视频共用),`type="minimax"` | +| VAE | `minimax_h3_image_vae_fp16.safetensors`(1.1G,optional 入参) | +| 核心节点 | `MiniMaxH3ImageConditioning`(输出 `CONDITIONING` + `LATENT`)→ `KSampler` → `VAEDecode` → `SaveImage` | +| 采样 | **6 步 / cfg 1.0 / euler + simple**(蒸馏模型,加步数无益) | +| 分辨率 | 宽高 **32 对齐**,2048² 起;**16 MP(4096² / 5472×3072)效果最好**,低于 4 MP 发软 | +| 速度 | DCU 上 16 MP 约 40 s/step;30113 上 1024²/2048² 各 6 步 = 170/208 s | +| 提示词 | **一段长英文描述**(构图+材质+光线+镜头),不是关键词堆砌;官方用 qwen3.5-9b 扩写,本机没装,手写或走 LLM 代理 | +| 参考图编辑 | optional `images`(`image_1`…,提示词用 `` 指代)——**本环境未验证,别当已支持** | + +### 2.3 出图后必须自检(2026-11-13 加入) + +H3-Image 在**量化档位不对**时会**出图成功但内容是纯黑/纯色**: +ComfyUI 侧 `status.completed=True`、`outputs` 有文件、**不报任何错**。 +不自检就会把废图当成品记进台账,等审片才发现。 + +`tools/submit_t2i.py` 现在每次出图后自动做 PNG 自检(零依赖,解 IHDR + IDAT 采样像素): + +``` +[SANITY] work/EP01/images/S01.png -> ok(2048x2048, 168733 colors, mean=72.3, std=57.8) +``` + +判定规则:颜色数 ≤ 8 判「单色」;亮度标准差 < 3.0 判「纯色」。 +**自检不通过时脚本退出码为 1,且跳过自动清理** —— 保留服务端 history 与产物当排查证据。 + +### 2.4 脚本用法 + +```bash +# 权重不用填:脚本读端点 /object_info/UNETLoader 自动挑(w4a8 / int8_convrot) +python3 tools/submit_t2i.py --ep EP01 --shot S01 --prompt-file 40_prompts/S01.t2i.txt +python3 tools/submit_t2i.py --prompt "A lone figure on a misty pier, ..." --out assets/characters/ling.png +python3 tools/submit_t2i.py --ep EP01 --shot S03 --width 4096 --height 4096 --force +``` + +落到 `work/EPxx/images/Sxx.png`——正是 `submit_i2v.py` 期望的首帧路径,阶段 0 / 阶段 4 由此闭环。 + +--- + +## 3. ComfyUI 通用 API(30111 / 30112 / 30113 三个端口指向同一实例) + +### 3.1 端点表(新版标准路径带 `/api` 前缀) + +官方 master 的 `add_routes()` 会把每个 `@routes.*` 自动复制一份 `/api` + 原路径,源码注释明确 +"Currently both the old endpoints without prefix and new endpoints with prefix are supported"。 +**优先用 `/api` 前缀**(官方文档与 ComfyUI Cloud 都用这个),无前缀是等价别名。 +先 `GET /api/system_stats` 探测,不可用自动回退无前缀。现网 0.38 / 0.45 三条线都实测 `/api/history`、`/api/queue`、`/api/free` 可用。 + +| 方法 | 路径 | 用途 / 返回 | +|---|---|---| +| GET | `/api/system_stats` | 存活、ComfyUI 版本、`system.argv` 启动参数、设备与显存。**换模型/换版本先打这个** | +| GET | `/api/object_info/{class_type}` | 该节点的 required / optional 入参、输出类型。节点字段对不上就查这里 | +| POST | `/api/upload/image` | multipart,字段 `image`(文件)+ `overwrite=true` → `{"name": "..."}`,填进 `LoadImage` | +| POST | `/api/prompt` | body `{"prompt": {节点图}, "client_id": "..."}` → `{"prompt_id", "node_errors"}` | +| GET | `/api/history/{prompt_id}` | 轮询:`status.completed`、`status.messages`(含 `execution_error`)、`outputs` | +| GET | `/api/history` | 全量历史(网络超时后确认任务是否已提交) | +| GET | `/api/view?filename=&subfolder=&type=output` | 下载图片/视频二进制 | +| GET | `/api/queue` | `queue_running` / `queue_pending`,提交前确认空闲 | +| POST | `/api/interrupt` | 中断当前执行,可带 `prompt_id` | +| POST | `/api/history` | `{"delete": [pid, ...]}` **批量**删生成记录。**`{"clear": true}` 会清掉全部任务,禁用** | +| POST | `/api/queue` | `{"delete": [pid, ...]}` 删队列残留 | +| POST | `/api/free` | `{"unload_models": true, "free_memory": true}` 设队列 flag,下一个队列循环才真正卸载模型/释放显存 | +| POST | `/api/jobs/{id}/cancel`、`/api/jobs/cancel` | 新版标准:运行中的任务中断、待执行的出队,返回 `{"cancelled": bool}`;已完成/未知 ID 是幂等空操作 | +| DELETE | `/userdata/{file}` | **只删 `ComfyUI/user/` 下的用户数据**(workflows / settings),与 `output/` 无关 | +| DELETE | `/api/assets/{id}` | 需 `--enable-assets`;删的是 asset 数据库引用,不是 output 文件。现网实测 503 `SERVICE_DISABLED` | + +三个删除类 POST 一律返回 **200 空 body**(别用 `json.loads()` 去解),而且是**幂等**的: +实机验证 `POST /api/history {"delete":["不存在的 uuid"]}` 照样返回 200 空 body。所以 + +- **不能把 200 当「删除成功」**,必须删后再 `GET /api/history/` 复核「删前有 → 删后无」, + 并查 `/api/queue` 确认该 pid 不在 running / pending; +- `GET /history/{pid}` 的 `{}` 有**三义**(排队中 / 执行中 / 不存在,外加 `MAXIMUM_HISTORY_SIZE=10000` + 淘汰旧记录),单看 `{}` 什么也断定不了,判据必须是删前删后的对比; +- `history` 是**内存态**(Pod 重启即失),`output/` 文件在 PVC / 宿主盘上是持久的 —— + **「记录没了、文件还在」是最常见的残留形态**。 + +`/prompt` 返回的 `node_errors` 必须判空;`prompt_id` 只代表**已接受**,不代表开始渲染,更不代表完成。 + +### 3.2 八个必踩的坑 + +1. **`/prompt` 必须包一层 `{"prompt": ...}`**。仓库里的 `*.json` 工作流多是**裸节点图**,直接 `curl -d @xx.json` 会 400。 +2. **绕过本机代理**:Python 用 `urllib.request.build_opener(urllib.request.ProxyHandler({}))`;curl 加 `--noproxy '*'`。否则明文 HTTP 被改写成 `text/html`。 +3. **轮询判据**:`status.completed` + `outputs` 同时满足才算完成;先扫 `status.messages` 里的 `execution_error`。 +4. **网络超时 ≠ 未提交**:重试前先查 `/history/{pid}`,否则会重复消耗算力。 +5. **惰性加载**:空闲不占显存,首次提交要 1–3 分钟(H3-K8s 冷启动更久,约 3–4 分钟),别误判成挂了。 +6. **串行提交**:30113 一个实例同时承担图与两种视频,受 4Gi cgroup 硬限且无 swap,**并发必 OOM(exit 137)**。 +7. **200 空 body ≠ 删除成功**:见 3.1。删完必须复核,报告里要区分「已确认(删前有→删后无)」与「幂等 200,删前就无此记录」。 +8. **官方删不了 `output/` 文件**:`DELETE /userdata/{file}` 只管 `user/` 目录,`/api/assets` 默认关闭且管的是数据库引用。社区只有两条路:装自定义节点补标准 `DELETE` 路由,或在服务端文件系统上精确删(见 3.4)。 + +### 3.3 最小提交骨架(可直接复制) + +```python +import json, time, urllib.parse, urllib.request + +COMFY = "http://192.168.1.30:30113" # 图 / H3 视频 / WAN 全在这一个实例;30111/30112 是它的别名 +opener = urllib.request.build_opener(urllib.request.ProxyHandler({})) # 必须 + +def get(path, timeout=30): + return json.loads(opener.open(COMFY + path, timeout=timeout).read()) + +def post(path, payload, timeout=60): + req = urllib.request.Request(COMFY + path, data=json.dumps(payload).encode(), + headers={"Content-Type": "application/json"}) + return json.loads(opener.open(req, timeout=timeout).read()) + +assert get("/system_stats")["devices"] # 健康检查 +graph = {...} # 节点图,见 §4 +r = post("/prompt", {"prompt": graph, "client_id": "manju-t2i-demo"}) +if r.get("node_errors"): + raise RuntimeError(r["node_errors"]) +pid = r["prompt_id"] + +while True: + h = get("/history/" + urllib.parse.quote(pid)) + if pid in h: + item = h[pid] + if any(m[0] == "execution_error" for m in item["status"].get("messages", [])): + raise RuntimeError(item["status"]["messages"]) + if item["status"].get("completed") and item.get("outputs"): + f = next(x for out in item["outputs"].values() + for k in ("images", "videos", "gifs") for x in out.get(k, [])) + q = urllib.parse.urlencode({"filename": f["filename"], + "subfolder": f.get("subfolder", ""), + "type": f.get("type", "output")}) + open("out.bin", "wb").write(opener.open(COMFY + "/view?" + q, timeout=300).read()) + break + time.sleep(5) +``` + +产物落在服务端 `/home/ComfyUI/output/`(DCU,宿主机同路径)或 `/comfyui/output/`(K8s),用 `/view` 拉回,不要去猜路径。 + +### 3.4 生成后清理:清掉 ComfyUI 记录与产物(必做) + +**为什么必须做**:`/view` 下载的只是副本。服务端 `output/` 里的 mp4 / png、`input/` 里上传的首帧、以及 `history` 里的整段节点图与提示词**都还在**。DCU 的 `/home/ComfyUI/output` 与 K8s 的 PVC 是持久存储,不会随任务结束消失;而 `history` 只是内存态(Pod 重启即没),所以**记录没了文件还在**是最常见的残留。 + +#### 只删「自己发起的任务」:归属模型(本版本核心) + +现网 `history` 是**全局共享**的:`30112` 上 151 条里绝大多数是别人的任务,`30120` 上 23 条的 `client_id` 也各不相同(该机已下线,数据为下线前实测)。ComfyUI 把 `client_id` 持久化在 history 项 `prompt[3]["client_id"]`(0.38 / 0.45 实机核对都成立),这就是归属凭证。 + +| 层 | 凭证 | 作用 | +|---|---|---| +| 1 | 本地台账 `promptId` | 只有本技能提交的任务才会写进 `a14b_runs.json` / `t2i_runs.json`,天然是「自己发起」的白名单 | +| 2 | 台账 `clientId` | 两个提交脚本改用 `manju-i2v-` / `manju-t2i-` 提交并把 `clientId` 写进台账;清理时 `GET /api/history/` 读回 `client_id` 精确比对 | +| 3 | 服务端二次校验 | 扩展在服务端再判一次 `client_id ∈ clientIds ∪ ownerPrefixes`;`requireOwner=true` 且无凭证时 **fail-closed,一律拒绝** | + +未通过归属的 pid 会从删除列表里剔除:既不调 `POST /api/history`,也不调 `POST /api/queue`,更不删文件。老台账没记 `clientId` 的历史任务,把那些 `client_id` 加进 `cleanup.clientIds`(或调整 `ownerPrefixes`)才会被清。**禁用 `{"clear": true}`**。 + +#### 官方没有删产物的接口 → 用扩展补上 + +官方 `server.py` 只有记录删除与显存释放;`DELETE /userdata/{file}` 只管 `ComfyUI/user/`,`/api/assets` 删的是数据库引用且现网 503。**本技能自带扩展 `assets/comfyui-manju-cleanup/`**:整目录拷到 `ComfyUI/custom_nodes/` 并重启进程即可。它注册到 `PromptServer.instance.routes`,官方 `add_routes()` 会自动镜像出 `/api` 前缀(master 源码逐行核对),所以带不带前缀都能用。 + +| 路由 | 作用 | +|---|---| +| `GET /manju/cleanup/ping` | 探活、返回 output/input/temp 根目录、是否要求 token | +| `POST /manju/cleanup/purge` | `{"pids":[...], "client_ids":[...], "owner_prefixes":[...], "dry_run":true, "purge_input":false, "require_owner":true}` | + +扩展**只接受 pid**,自己从服务端 `history` 反查该 pid 的 outputs/inputs,绝不接受任意文件路径;再校验 `client_id` 归属、`realpath` 必须落在对应根目录(拒绝绝对路径 / `..` / 符号链接 / 目录),并做跨任务引用计数(被别的 pid 引用的文件判 `shared` 跳过)。`dry_run` 默认 `true`,可选环境变量 `MANJU_CLEANUP_TOKEN` 开鉴权(对应 `cleanup.token`)。它**不删 history/queue 记录** —— 那部分继续走官方标准接口。 + +#### 社区怎么弄的(2026-11-12 核实) + +| 来源 | 结论 | +|---|---| +| 官方 `server.py`(master) | `post_history` / `post_queue` 支持 `clear` 与 `delete` 列表,逐项调 `delete_history_item` / `delete_queue_item`,一律 `web.Response(status=200)`;`post_free` 只 `set_flag("unload_models" / "free_memory")`;`/api` 前缀路由是自动复制的,**没有任何删磁盘文件的路由** | +| 官方文档 `docs.comfy.org/.../comms_routes` | 路由表列了 `POST /history`(清除/删除历史项)、`POST /queue`、`POST /free`、`DELETE /userdata/{file}`(删用户数据文件) | +| ComfyUI Cloud API 文档 | `POST /api/history {"delete":[...], "clear":true}`、`DELETE /api/assets/{id}`(云端,删数据库记录 + 存储内容);说明 `/api` 前缀是官方方向 | +| Runflow《Every ComfyUI API Endpoint》 | "History accumulates without bound. Periodically clear it with POST /history in long-lived deployments" | +| ArcReel 一手调研 | `GET /history/{pid}` 的 `{}` 三义、`MAXIMUM_HISTORY_SIZE = 10000` 淘汰旧记录,判完成不能只看 `{}` | +| 社区自定义节点 | `comfyui_extra_api` 提供 `DELETE /comfyapi/v1/output-images/{filename}`;`ComfyUI-api-tools` 提供 `DELETE /api-tools/v1/images/output/{filename}`。都是**补上官方缺失的删文件路由** | +| **本技能扩展** | `manju-cleanup` 不走「按文件名删」的路子,而是按 `pid + client_id` 从服务端 history 反查产物,天然带归属与防误删;见上节 | +| 社区通用做法 | 没装节点时,服务端脚本 / cron 定期清 `output/`;缺点是会误删别人**还没导出**的产物 | + +**现网实机核实**(三个端点 `0.38.0` / `0.45.0`): + +| 能做的(标准接口) | 不能做的 | +|---|---| +| `GET /api/system_stats` 探前缀 | ❌ 没有删除 `output/` 文件的 HTTP 路由 | +| `GET /api/history/` 抽产物清单 | ❌ `DELETE /history/` 实测 **405**(官方只支持 POST 带 body) | +| `POST /api/history {"delete":[...]}` 批量删记录 | ❌ `DELETE /userdata/{file}` 只管 `ComfyUI/user/`,不管 `output/` | +| `POST /api/queue {"delete":[...]}` 删队列残留 | ❌ `/api/assets` 实测 **503 SERVICE_DISABLED**,要 `--enable-assets` 且删的是数据库引用 | +| `POST /api/free {...}` 释放模型显存 | ❌ `{"clear": true}` 会误删别人的任务,禁用 | +| 删后 `GET /api/history/` + `/api/queue` 复核 | ❌ 200 空 body **不等于删除成功**,删不存在的 pid 也是 200 | +| `GET /api/history/` 读 `prompt[3]["client_id"]` 判归属 | ❌ 官方删除接口**不带任何归属校验**:谁都能 `{"delete":[别人的 pid]}`,所以必须客户端先拦 | +| 扩展 `GET /api/manju/cleanup/ping` / `POST .../purge` | ❌ 扩展装了才可用;未装时脚本自动降级 | + +**顺序铁律(装了扩展时,与旧版不同)**: +`GET /api/history/` 抽产物清单 + `client_id` → **归属闸门**(不归属的直接剔除,绝不进删除列表) +→ `POST /manju/cleanup/purge {"dry_run":true}` 服务端预览 +→ `POST /manju/cleanup/purge {"dry_run":false}` 删服务端文件 +→ 批量 `POST /api/history` + `POST /api/queue` 的 `{"delete": [...]}` +→ **复核** `GET /api/history/` 变成 `{}` 且 `/api/queue` 里不再出现该 pid +→ 整批结束 `POST /api/free`。 + +**为什么换成「先删文件再删记录」**:purge 依赖 history 反查文件名,记录一删就永远查不到产物了。旧版的「先抽清单 → 删记录 → 复核 → 删文件」只在**没装扩展**的降级路线里保留(那时清单由客户端自己抽)。少了复核就是把幂等 200 当成真删了。 + +**工具**:`tools/cleanup_comfyui.py`,零依赖、绕代理、默认 dry-run、自动探测 `/api` 前缀与扩展并回退。报告里每条任务都打印 `✅ 自己的任务 / ⛔ 拒绝(非本人任务)`、`client_id` 与归属理由。 + +**扫描范围**:脚本**递归扫工作空间下所有 `t2i_runs.json` / `a14b_runs.json`**,而不是只认固定路径 —— 因为 `submit_t2i.py` 把台账写在 `os.path.dirname(out)`,台账位置随输出路径变: + +| 出图方式 | 台账落点 | +|---|---| +| `--ep EP01 --shot S01` | `work/EP01/images/t2i_runs.json` | +| 裸 `--out assets/characters/ling.png` | `assets/characters/t2i_runs.json`(**跟图片同目录**) | + +漏扫后者的后果是**角色锚图产物永远留在服务端**(2026-11-13 实测漏洞,已修 + 已加回归断言)。因此**不带 `--ep` 跑一次**可以把锚图与集外任务一起清掉。 + +每个任务的**实际端点取自台账里的 `endpoint` 字段**(而非配置里的全局值),锚图与首帧不在同一端点时也不会清错地方。 + +```bash +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:连锚图/集外任务一起清 +python3 tools/cleanup_comfyui.py --ep EP01 --shot S03 --apply --purge-input +python3 tools/cleanup_comfyui.py --prompt-id --endpoint http://192.168.1.30:30112 \ + --client-id manju-i2v-ab12cd34 --apply # 显式任务必须给归属凭证 +``` + +两个提交脚本支持 `--cleanup`(导出后自动清)、`--no-cleanup`(本次跳过);`config.cleanup.auto = true` 可设为默认自动。 +钩子只清该镜的记录与产物,**不会每镜 `/free`** —— 4Gi 环境下重新加载模型要几分钟,整批归档后统一释放一次才对。 + +**文件怎么删:扩展优先,两条降级路线兜底** + +1. **扩展(推荐)**:装了 `manju-cleanup` 的端点,脚本自动探测 `/api/manju/cleanup/ping` 并走 `purge`;`cleanup.nodeApi` 可显式指定前缀。服务端逐文件返回 `deleted / dry-run / missing / shared / refused / skipped-input / error`,脚本原样打印,不会含糊地说「已清理」。 +2. **社区 DELETE 插件**:`cleanup.deleteApi` = `comfyui_extra_api` / `api-tools`,只管不带子目录的图片。 +3. **文件系统模板**:`cleanup.commands` 按端点配 shell 模板,`{files}` 逐个 `shlex.quote`。没配就只打印精确清单、**绝不假称已删**。三条路线都受归属闸门约束。 + +**部署扩展**(DCU 30120 已实装并验证;K8s 当前选择不重启,下面的 patch 命令留作以后要改用 HTTP 接口时再执行,**目前未执行**): + +```bash +# ── DCU 30120(已实装):宿主 /home/ComfyUI 是 bind mount,重启容器即持久生效 +# client/push.sh 与 client/remote.sh 是项目里的 xop+sshpass 辅助脚本(凭据不落明文); +# 也可以换成自己的 scp / ssh。__P__ 由 remote.sh 在本地展开为 sudo 密码。 +bash client/push.sh assets/comfyui-manju-cleanup/__init__.py /tmp/manju_cleanup_init.py +bash client/remote.sh 'echo __P__ | sudo -S -p "" mkdir -p /home/ComfyUI/custom_nodes/comfyui-manju-cleanup && echo __P__ | sudo -S -p "" cp /tmp/manju_cleanup_init.py /home/ComfyUI/custom_nodes/comfyui-manju-cleanup/__init__.py' +bash client/remote.sh 'echo __P__ | sudo -S -p "" docker restart comfyui-h3' +curl -s --noproxy '*' http://192.168.1.24:30120/api/manju/cleanup/ping # 实测 200 + +# ── K8s 30113(ComfyUI 根 /comfyui-0.45);30111 / 30112 是同一实例的别名,根目录相同 +# custom_nodes 在镜像内,用 ConfigMap 单文件挂载 +export KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong # 本机默认 context 是 orbstack,不是这个集群 +kubectl -n wuguirong create configmap manju-cleanup-node \ + --from-file=__init__.py=assets/comfyui-manju-cleanup/__init__.py # 已创建,无副作用 +for d in comfyui-wan-h3 comfyui-wan-a14b; do + kubectl -n wuguirong patch deploy "$d" --type=json -p='[ + {"op":"add","path":"/spec/template/spec/containers/0/volumeMounts/-","value":{"name":"manju-cleanup","mountPath":"/comfyui/custom_nodes/comfyui-manju-cleanup/__init__.py","subPath":"__init__.py","readOnly":true}}, + {"op":"add","path":"/spec/template/spec/volumes/-","value":{"name":"manju-cleanup","configMap":{"name":"manju-cleanup-node"}}} + ]' +done +# 30113 的 ComfyUI 根是 /comfyui-0.45,挂载路径要跟着变(此条未在现网验证) +kubectl -n wuguirong patch deploy comfyui-wan-h3image --type=json -p='[ + {"op":"add","path":"/spec/template/spec/containers/0/volumeMounts/-","value":{"name":"manju-cleanup","mountPath":"/comfyui-0.45/custom_nodes/comfyui-manju-cleanup/__init__.py","subPath":"__init__.py","readOnly":true}}, + {"op":"add","path":"/spec/template/spec/volumes/-","value":{"name":"manju-cleanup","configMap":{"name":"manju-cleanup-node"}}} +]' +# ⚠ patch 会触发 rollout(Pod 重建):history 是内存态,重启会清掉**所有人**的记录。 +# 而且 30113 的 rollout 会重建 /local(emptyDir)→ 权重软链全部丢失,必须重跑 +# /basedir/apply-multimodal.sh 才能恢复视频能力。只在队列空闲且明确确认后执行; +# 当前未执行,K8s 走下面的 kubectl exec 降级模板。 +curl -s --noproxy '*' http://192.168.1.30:30111/api/manju/cleanup/ping +python3 tools/selftest_cleanup.py # 本地 mock 自检,26 项断言 +``` + +**现网选择:K8s 不重启,走 `kubectl exec` 降级模板**(归属闸门照常生效、零重启、零副作用)。三条模板已作为默认值写进 `assets/config.template.json` 与 `cleanup_comfyui.py` 的 `DEFAULT_CLEANUP`,`setup` 生成的工作空间直接可用。 + +> **2026-11-13 更新**:三个端口现在都指向同一个 pod,**三条模板的 pod 选择器必须统一成 `app=comfyui-wan-h3image`**。 +> 旧模板用 `app=comfyui-wan-a14b` / `app=comfyui-wan-h3` 找 pod——那两个 deployment 已 scale 到 0, +> 会取到**空 pod 名**导致 `kubectl exec` 报错。 + +```json +"commands": { + "http://192.168.1.30:30112": "KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong exec $(KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong get pods -l app=comfyui-wan-h3image -o jsonpath='{.items[0].metadata.name}') -c comfyui -- sh -c \"cd {root} && rm -f -- {files} {temp_files}\"", + "http://192.168.1.30:30111": "KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong exec $(KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong get pods -l app=comfyui-wan-h3image -o jsonpath='{.items[0].metadata.name}') -c comfyui -- sh -c \"cd {root} && rm -f -- {files} {temp_files}\"", + "http://192.168.1.30:30113": "KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong exec $(KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong get pods -l app=comfyui-wan-h3image -o jsonpath='{.items[0].metadata.name}') -c comfyui -- sh -c \"cd {root} && rm -f -- {files} {temp_files}\"" +}, +"outputRoot": "/comfyui/output", +"inputRoot": "/comfyui/input" +``` + +三条模板已在现网用「删不存在文件」实测 rc=0。已有工作空间若把 `cleanup.commands` 覆盖成 `{}`,删掉该键(用脚本默认值)或手工补回模板才生效。要连上传首帧一起删,在模板里另加 `cd {input_root} && rm -f -- {input_files}`。 + +> **30113 的特殊性**:主用端点**没有装** `manju-cleanup` 扩展(且它是 4 GiB cgroup 硬限的单实例,patch rollout 会重建 `/local`、丢权重软链,重启成本最高),所以**必须**走 `commands` 模板这一条降级路线;`cleanup_comfyui.py` 会自动探测到扩展不存在并降级,不会卡住。 + +**`cleanup` 段关键字段**(完整默认配置见 `assets/config.template.json`): + +| 字段 | 默认值 | 说明 | +|---|---|---| +| `requireOwner` | `true` | 归属校验失败一律拒绝、不调任何删除接口 | +| `clientIds` / `ownerPrefixes` | `[]` / `["manju-"]` | 补老台账没记 `clientId` 的任务 / 前缀白名单 | +| `nodeApi` | `""` | 自动探测 `/api/manju/cleanup`,探测不到就降级 | +| `commands` | 30113 / 30111 / 30112 三条 `kubectl exec` 模板 | 见上,K8s 不重启也能删产物(30113 是主用那条) | +| `outputRoot` / `inputRoot` | `/comfyui/output` / `/comfyui/input` | K8s Pod 内路径 | +| `deleteApi` / `token` | `""` | 社区 DELETE 插件 / 扩展鉴权,现网都未启用 | +| `free` | `false` | 整批结束加 `--free` 才释放模型 | + +| 占位符 | 含义 | +|---|---| +| `{files}` / `{temp_files}` | `output` / `temp` 产物,含 `subfolder`,逐个 shell 转义 | +| `{input_files}` | 上传的首帧图,仅 `purgeInput=true` 时非空 | +| `{root}` / `{input_root}` | 服务端 output / input 根,自带转义,**模板里别再包引号** | + +DCU 30120 已装扩展、走 HTTP purge,不用配模板;要给它配兜底才用 `ssh` + `docker exec comfyui-h3`,output 根 `/home/ComfyUI/output`。K8s 的 pod 名由模板动态查,不用手填 ``。上传首帧可能被多个镜共用,默认**只列不删**;扩展会做跨任务引用计数,被别的 pid 引用的一律判 `shared` 跳过。 + +**清理边界(别越界)**:只清服务端、只清自己发起的任务。本地已导出的成片、`40_prompts/` 提示词原文、`30_shots.json`、`50_manifest.json` 一律保留;台账默认只移除 `promptId` 并记 `cleanedAt`,`--purge-ledger` 才删整条。导出闸门会拦下「本地成片缺失或小于 `minBytes`」的条目,防止**没导出就把服务端证据清了**;归属闸门会拦下台账无 `clientId` 且 `client_id` 不在白名单的条目,防止**把别人的任务当自己的清掉**。只按 `prompt_id` 精确删,禁用 `{"clear": true}`。 + +--- + +## 4. 各模型 API 用法 + +### 4.1 Wan2.2 A14B(视频②,`submit_i2v.py` 已封装) + +**优先用现成脚本**,不要手写工作流: + +```bash +python3 tools/submit_i2v.py projects/EPxx/30_shots.json # 全部 +python3 tools/submit_i2v.py projects/EPxx/30_shots.json --only S03 # 单镜重做 +``` + +端点取 `config/pipeline.json → videoModel.endpoint`,**默认 `30113`(0.45,主用)**;填 `30112` 也完全等价——三个端口指向同一个实例。 + +工作流要点(脚本内 `build_workflow()`):双专家各跑 2 步,`UNETLoader` 用 `weight_dtype="default"`(文件原生 fp8), +`CLIPLoader` 的 `type="wan"`,`WanImageToVideo` 接 `start_image`,两个分支各挂 **`ModelSamplingSD3 shift=5`**, +`SaveVideo` 用 `format="auto"`。 +常量:`wan2.2_i2v_{high,low}_noise_14B_fp8_scaled.safetensors` + `wan2.2_i2v_lightx2v_4steps_lora_v1_{high,low}_noise.safetensors` + `umt5_xxl_fp8_e4m3fn_scaled.safetensors` + `wan_2.1_vae.safetensors`。 + +**2026-11-13 实测**(30113):480×480 / 17 帧 / 4 步 → h264 mp4 87 KB,17 帧全部互异(17k–27k 种颜色)。 +**迁移验证**:把 30112 上一条**生产工作流原样**(16 节点,432×768 / 81 帧 / 双专家 / lightx2v LoRA) +提交到 30113,成功出片 —— 证明 30112 → 30113 无需改工作流。 + +| 0.45 与 0.38 的差异(照搬会退化,但不会报错) | 0.45(30113) | 0.38(30112) | +|---|---|---| +| `ModelSamplingSD3 shift=5` | **必需**(官方模板如此) | 同样需要;旧版脚本漏挂,画面会发软/漂移 | +| `UNETLoader.weight_dtype` | `default`(用文件原生 fp8) | 同为 `default` 可用;写 `fp8_e4m3fn` 会多一次转换 | +| `SaveVideo.format` | `auto` / `mp4` / `mkv` / `webm` / `mov` 均合法 | `auto` / `mp4` / `mkv` / `webm` | +| 串行 | 与 H3、出图共用同一实例 | 与 30111 共用同一张卡 | + +项目仓库里还有个通用客户端(不在本技能内):`deploy/k8s-nvidia/api/submit.py --model 14b --prompt "..." --image frame.png --out clip.mp4`。 +⚠️ 该脚本**默认值仍指向已下线的 5B 档**,必须显式 `--model 14b`。 + +### 4.2 MiniMax H3 视频 on DCU(0.45.0,`KSampler` 路线) + +```python +P = "A serene mountain lake at sunrise, slow cinematic drift. overall_soundscape: soft wind, distant birds. non_diegetic_music: calm ambient piano." +g = { + "1": {"class_type":"UNETLoader","inputs":{"unet_name":"minimax_h3_fl2va_pruned_w6a8.safetensors","weight_dtype":"default"}}, + "2": {"class_type":"CLIPLoader","inputs":{"clip_name":"qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors","type":"minimax"}}, + "3": {"class_type":"VAELoader","inputs":{"vae_name":"minimax_h3_video_vae_fp16.safetensors"}}, + "4": {"class_type":"VAELoader","inputs":{"vae_name":"minimax_h3_audio_vae_fp32.safetensors"}}, + "5": {"class_type":"MiniMaxH3SigmaShift","inputs":{"model":["1",0],"shift_video":12.0,"shift_audio":3.0}}, + "6": {"class_type":"MiniMaxH3ImageToVideo","inputs":{"clip":["2",0],"vae":["3",0],"prompt":P, + "width":768,"height":448,"length":124}}, # 图生视频加 "first_frame":["LoadImage",0] + "7": {"class_type":"KSampler","inputs":{"model":["5",0],"seed":42,"steps":20,"cfg":1.0, + "sampler_name":"res_multistep","scheduler":"simple","positive":["6",0], + "negative":"","latent_image":["6",1],"denoise":1.0}}, + "8": {"class_type":"VAEDecode","inputs":{"samples":["7",0],"vae":["3",0]}}, + "9": {"class_type":"VAEDecodeAudio","inputs":{"samples":["7",0],"vae":["4",0]}}, + "12": {"class_type":"H3AudioClean","inputs":{"audio":["9",0]}}, # ★ ROCm 必需 + "10": {"class_type":"CreateVideo","inputs":{"images":["8",0],"fps":24,"audio":["12",0]}}, + "11": {"class_type":"SaveVideo","inputs":{"video":["10",0],"filename_prefix":"H3_out","format":"auto"}}, +} +``` + +- **`H3AudioClean` 是自写节点**(`/home/ComfyUI/custom_nodes/H3AudioClean.py`):ROCm 下音频 VAE 输出混 NaN,AAC 编码器会拒收。**只有 DCU 线要插**,CUDA 线上这个节点不存在,照搬会 `class_type not found`。 +- **0.45 的 `SaveVideo.format` 传 `"auto"`**:它是 `COMFY_DYNAMICCOMBO_V3`,传 `"video/h264-mp4"` 会被静默丢弃并报缺参数。 +- 必须用本地 `MiniMaxH3*` 节点,云端 `MinimaxHailuo03*` 需登录授权,不可用。 + +### 4.3 MiniMax H3 视频 on K8s(0.45 @30113 主用;30111/30112 为同一实例别名) + +> ⚠️ **此配方只适用于 T2V(纯文生视频)。** 不要照 §4.2 的说明往 `MiniMaxH3ImageToVideo` +> 里加 `first_frame` / `last_frame`:2080Ti 22 GB 上 I2V 会 `CUDA out of memory`(2026-11-14 +> 干净态重放复现,见 §0 警告)。首帧锁图请用 Wan2.2 I2V A14B 或 DCU 线。 + +**主用 `30113`(0.45)**。节点图与 DCU 完全不同:**不带 `MiniMaxH3SigmaShift`**,走 +`SamplerCustomAdvanced` + `BasicGuider` / `BasicScheduler` / `RandomNoise`。同一张图在 `30111`(0.38)上也能跑。 + +已实测(30113):20 步 / 320×192 / 22 帧 / 带 aac 音轨 / 22 帧全部互异(37k–42k 种颜色)。 + +```python +P = ("A neon-lit rainy alley at night, a motorcycle rolls slowly toward camera. " + "overall_soundscape: rain on asphalt, distant traffic. non_diegetic_music: low synth drone.") +g = { + "2": {"class_type":"CLIPLoader","inputs":{"clip_name":"qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors","type":"minimax","device":"default"}}, + "3": {"class_type":"VAELoader","inputs":{"vae_name":"minimax_h3_video_vae_fp16.safetensors"}}, + "4": {"class_type":"VAELoader","inputs":{"vae_name":"minimax_h3_audio_vae_fp32.safetensors"}}, + "5": {"class_type":"UNETLoader","inputs":{"unet_name":"minimax_h3_fl2va_pruned_w6a8.safetensors","weight_dtype":"default"}}, + "7": {"class_type":"MiniMaxH3ImageToVideo","inputs":{"clip":["2",0],"vae":["3",0],"prompt":P, + "width":320,"height":192,"length":22}}, # ⚠️ 保持 T2V:加 first_frame 会在 2080Ti 上 OOM + "8": {"class_type":"BasicGuider","inputs":{"model":["5",0],"conditioning":["7",0]}}, + "9": {"class_type":"KSamplerSelect","inputs":{"sampler_name":"res_multistep"}}, + "10": {"class_type":"BasicScheduler","inputs":{"model":["5",0],"scheduler":"simple","steps":20,"denoise":1.0}}, + "11": {"class_type":"RandomNoise","inputs":{"noise_seed":1}}, + "12": {"class_type":"SamplerCustomAdvanced","inputs":{"noise":["11",0],"guider":["8",0], + "sampler":["9",0],"sigmas":["10",0],"latent_image":["7",1]}}, + "13": {"class_type":"VAEDecode","inputs":{"samples":["12",0],"vae":["3",0]}}, + "14": {"class_type":"VAEDecodeAudio","inputs":{"samples":["12",0],"vae":["4",0]}}, + "15": {"class_type":"CreateVideo","inputs":{"images":["13",0],"audio":["14",0],"fps":24,"bit_depth":8,"color_space":"sRGB"}}, + "16": {"class_type":"SaveVideo","inputs":{"filename_prefix":"video/h3","format":"auto","video":["15",0]}}, + "17": {"class_type":"SaveImage","inputs":{"images":["13",0],"filename_prefix":"h3/frame"}}, # 抽帧自检用 +} +r = post("/prompt", {"prompt": g}) # 别直接 -d @裸 json +``` + +- **参数固定为 20 步 / `res_multistep` + `simple` / cfg 1.0 / 无 LoRA**。这是唯一稳定出画面的组合。 +- **不要加 `first_frame` / `last_frame`**:`nodes_minimax_h3.py:155-179` 在该分支执行 `vae.encode()`, + video VAE 被 conditioning 持有到采样期,TE 14.96 G + VAE 4.97 G 无法卸载 → 采样 OOM。 + 这套 4 GiB + 22 处 MEM4G 补丁的低显存方案**只在 T2V 上验证过**,I2V 是未覆盖的回归。 +- `SaveImage` 保留:验证空白帧靠的就是逐帧数颜色;0.38 上只挂 `CreateVideo` 会报 `Prompt has no outputs`。 +- 尺寸:0.45 实测 320×192 / 22 帧;0.38 实测 960×544 / 33 帧。更大规格在 0.45 未验证,从小往上加。 + +| 项 | **0.45(30113 主用;30111/30112 为同一实例别名)** | 0.38(已下线,历史数据) | DCU 0.45(30120,⚠️ 已下线) | +|---|---|---|---| +| 采样 | `SamplerCustomAdvanced` + `BasicGuider/BasicScheduler/RandomNoise` | 同左 | `KSampler` + `MiniMaxH3SigmaShift` | +| SigmaShift | **不要挂** | 不要挂 | 必需(`shift_video=12 / shift_audio=3`) | +| 音频清洁 | **不需要**(CUDA 音频正常,节点不存在) | 不需要 | 必须 `H3AudioClean` | +| 输出 | `SaveVideo format="auto"`(`mp4`/`mkv`/`webm`/`mov` 也合法) | `format="auto"` 或 `"mp4"`+`codec="h264"` | `format="auto"` | +| 启动参数 | **禁 `--fp16-unet`**(会毁掉 H3-Image 的 bf16 路径) | 必须 `--fp16-unet`(否则算 NaN) | `--use-pytorch-cross-attention` | +| 内存 | 4 GiB 硬限 + MEM4G 补丁集 | 4 GiB 硬限 + 0.38 版补丁 | 64 G 全驻,无墙 | +| turbo LoRA | **禁用**(合进 w6a8 → 全 NaN) | 同样禁用 | — | +| 实测规格 | 320×192 / 22 帧 / 20 步 | 960×544 / 33 帧 / 20 步 | 1344×768 / 24 帧 | + +### 4.4 H3-Image 文生图(首帧/锚图) + +```bash +# 技能脚本:读 config/pipeline.json 的 imageModel,输出到 work/EPxx/images/Sxx.png +# 权重不用填 —— 脚本读端点 /object_info 自动挑(DCU=w4a8 / K8s-30113=int8_convrot) +python3 tools/submit_t2i.py --ep EP01 --shot S01 --prompt-file 40_prompts/S01.t2i.txt +python3 tools/submit_t2i.py --prompt "A lone figure on a misty pier, ..." --out assets/characters/ling.png +``` + +等价节点图(API 格式)——**两个端点通用,只有 unet_name 不同**: + +```python +g = { + "1": {"class_type":"UNETLoader","inputs":{"unet_name":"<按端点选,见 §2.0>","weight_dtype":"default"}}, + "2": {"class_type":"CLIPLoader","inputs":{"clip_name":"qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors","type":"minimax","device":"default"}}, + "3": {"class_type":"VAELoader","inputs":{"vae_name":"minimax_h3_image_vae_fp16.safetensors"}}, + "4": {"class_type":"MiniMaxH3ImageConditioning","inputs":{"clip":["2",0],"vae":["3",0], + "prompt":PROMPT,"width":2048,"height":2048}}, # vae / images 是 optional + "5": {"class_type":"ConditioningZeroOut","inputs":{"conditioning":["4",0]}}, + "6": {"class_type":"KSampler","inputs":{"model":["1",0],"seed":42,"steps":6,"cfg":1.0, + "sampler_name":"euler","scheduler":"simple","positive":["4",0],"negative":["5",0], + "latent_image":["4",1],"denoise":1.0}}, + "7": {"class_type":"VAEDecode","inputs":{"samples":["6",0],"vae":["3",0]}}, + "8": {"class_type":"SaveImage","inputs":{"images":["7",0],"filename_prefix":"H3IMG"}}, +} +``` + +实机 `/object_info` 核对(**30113 与 DCU 签名一致**):`MiniMaxH3ImageConditioning` required = `clip, prompt, width, height`;optional = `vae, images`;输出 = `CONDITIONING, LATENT`。宽高 `step=32`、`max=16384`,`0` 表示按参考图/默认 2048。 + +> ⚠️ 出图成功 ≠ 内容正确。量化档位不对时会静默出纯色图 —— 跑完必须看自检输出(见 §2.3)。 + +--- + +## 5. 辅助模型 API(策划、扩写、检索) + +### 5.1 LLM 代理 `ipass-all`(阶段 1 拆剧本 / 扩写提示词) + +OpenAI 兼容,**需要 API Key**,用 xop 注入,密钥不落明文: + +```bash +# 列模型(返回 x_ipass_upstreams,含 slot 路由表) +xop run --secret K=llm_key -- bash -c 'curl -s --noproxy "*" -m 10 \ + -H "Authorization: Bearer $K" http://192.168.1.30:30084/v1/models' < /dev/null + +# 对话:必须按 slot 前缀路由 +xop run --secret K=llm_key -- bash -c 'curl -s --noproxy "*" -m 60 \ + -X POST http://192.168.1.30:30084/qwen/v1/chat/completions \ + -H "Authorization: Bearer $K" -H "Content-Type: application/json" \ + -d "{\"model\":\"qwen3.8-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"把这段戏拆成 8 个镜头\"}]}"' < /dev/null +``` + +| slot 路径 | 可用 model | 实测 | +|---|---|---| +| `/qwen/v1/chat/completions` | `qwen3.8-flash` | ✅ 通(有 `reasoning_content`,`max_tokens` 别给太小) | +| `/deepseek/v1/...` | `deepseek-flash`, `deepseek-v4-pro` | ✅ 通 | +| `/minimax/v1/...` | `MiniMax-M3`, `MiniMax-M3.1-Flash` | ✅ 通(响应带 ``) | +| `/glm/v1/...` | `GLM-5.3-Flash` | ⚠️ 曾报周/月用量上限,按 `/v1/models` 的 `x_ipass_upstreams` 看状态 | + +> **坑**:直连 `http://192.168.1.30:30084/v1/chat/completions` 一律报 `model_not_found / 上游 v1 不存在或已停用`——它按 **slot 前缀**分流,`/v1/models` 只是聚合视图。模型名也必须写该 slot 下的准确 id。 + +### 5.2 `embed-bge`(向量化 / rerank,免密钥) + +> ⚠️ **2026-11-13:服务已下线** —— `192.168.1.24:8801` TCP CLOSED(随 DCU 整机一起挂)。 +> 下面的调用方式留作恢复后参考;当前**设定检索、去重、语义回填这些环节没有可用的向量服务**, +> 需要的话只能退回纯关键词匹配,或等 DCU 恢复。 + +```bash +curl -s --noproxy '*' -X POST http://192.168.1.24:8801/v1/embeddings \ + -H 'Content-Type: application/json' \ + -d '{"model":"BAAI/bge-large-zh-v1.5","input":"湖面泛起薄雾"}' # 1024 维 +``` + +- 模型名必须是 **`BAAI/bge-large-zh-v1.5`**;写 `bge-large-zh` 会 404 `The model ... does not exist`。 +- 另有 `/v1/models`、`/v1/rerank`、`/v1/score`、`/pooling`、`/health`,都是 POST(除 `/v1/models`、`/health`)。 +- 用途:长剧本按语义检索源节拍、跨集角色设定去重;不参与出图出片。 + +--- + +## 6. 开工前健康自检 + +```bash +# ① 主用端点(30113):在线 + ComfyUI 0.45 + 显存 +U=192.168.1.30:30113 +curl -s --noproxy '*' -m 8 "http://$U/system_stats" \ + | python3 -c "import json,sys;d=json.load(sys.stdin);print('ComfyUI',d['system']['comfyui_version'],'|',d['devices'][0]['name'],'|',round(d['devices'][0]['vram_free']/1048576),'MB free')" + +# ② 能力自检:UNETLoader 必须列出 4 个扩散模型(图 + H3 视频 + WAN high/low) +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] +assert len(d)>=4, '缺权重 -> 跑 /basedir/apply-multimodal.sh(pod 重建后软链会丢)' +" + +# ③ 旧端点(可选,回退用) +for U in 192.168.1.30:30111 192.168.1.30:30112; do + printf "%-24s" "$U" + curl -s --noproxy '*' -m 8 "http://$U/system_stats" | head -c 80; echo +done +# DCU(已下线,留作恢复后检查用)—— 现在跑必然空输出,属预期 +for U in 192.168.1.24:30120 192.168.1.24:8801; do printf "%-24s" "$U"; curl -s --noproxy '*' -m 6 "http://$U/system_stats" | head -c 40; echo; done +``` + +**② 是合并后的关键判据**:只有 1 个 `minimax_h3_image_*` 说明 `/local/models` 的软链没了(pod 重建), +不是模型坏了 —— 跑一次 `/basedir/apply-multimodal.sh` 即恢复,见部署侧 `deploy-as-built.md` §6。 + +再按 §3.2 判一次启动参数:**30113 应有 `--cache-none`,且绝不能有 `--fp16-unet`**(会毁掉 H3-Image 的 bf16 路径 → 全黑图); +30111 则相反,必须有 `--fp16-unet`;30112 上看到 `--force-fp16` 要停手(fp8 升 fp16 撞 4 GiB)。 +容器 `memory.events` 的 `oom_kill` 必须保持 0;若日志出现 `No working comfy-aimdo install detected` 且没打补丁,会退回 legacy 并在 30 秒内 exit 137。 + +--- + +## 7. 硬约束速查(别照搬) + +| 约束 | 归属 | +|---|---| +| 明文 HTTP 必须绕代理 | 全部 | +| `/prompt` 要 `{"prompt": ...}` 外层 | 全部 | +| 串行提交、网络超时先查 `/history` | 全部(30113 承接全部三种模态) | +| **DCU 禁用 int8_convrot**(gfx928 `rint` bug → NaN → 纯黑图) | H3-Image@DCU | +| **K8s-30113 只能 int8_convrot**(无 w4a8,sm_75 跑不了 w4a8 CUDA 路径) | H3-Image@K8s | +| **30113 禁 `--fp16-unet`**(动态范围 ±65504 → adaln 缩放溢出 → NaN → 全黑);必须走 bf16 软件模拟 | 30113 | +| **出图后看自检输出**(`[SANITY]`),纯色图 = 量化档位错,不是提示词问题 | H3-Image | +| 不用 turbo LoRA(合进 w6a8 → 全黑,4 步/6 步都试过) | H3 量化版 | +| 不照搬 `H3AudioClean`(仅 ROCm 需要) | DCU ↔ K8s | +| 不照搬采样节点与 `SaveVideo.format`(动态组合,别传 `video/h264-mp4`) | 0.45 ↔ 0.38 | +| `--force-fp16` 对 A14B 是禁用;`--fp16-unet` **30111 必需、30113 禁用** | K8s | +| 不需要 `ComfyUI-WanVideoWrapper`;不需要 CLIP-Vision 权重(`start_image` 走 VAE) | 30113 | +| **pod 重建后跑 `/basedir/apply-multimodal.sh`**,否则只剩出图能力 | 30113 | +| 分辨率 / 帧数上限:A14B 832×480 / 81 帧;H3 在 0.45 实测 320×192 / 22 帧(0.38 上 960×544 / 33 帧通过) | K8s | +| 任何消耗算力的步骤,生成前展示清单并取得明确授权 | 本技能规则 | + +--- + +## 8. 相关文件 + +| 位置 | 内容 | +|---|---| +| 部署侧 `deploy/k8s-nvidia/deploy-as-built.md` | **单实例部署 as-built**(不在技能包内):拓扑、4 GiB 限制、补丁集、pod 重建恢复、排障 | +| 本技能 `tools/submit_i2v.py` | A14B 图生视频提交器(阶段 4;节点图已对齐 0.45) | +| 本技能 `tools/submit_t2i.py` | H3-Image 文生图提交器(阶段 0 / 4 首帧) | +| 本技能 `references/submit-i2v.md` | 提交协议、预检、哈希命名与授权闸门 | +| 项目 `deploy/k8s-nvidia/REPORT-multimodal.md` | 本次合并的完整排查报告(含误判纠正与验证数据) | +| 项目 `deploy/k8s-nvidia/apply-multimodal.sh` | 权重软链恢复脚本(部署时拷到 `/basedir/`) | +| 项目 `deploy/k8s-nvidia/deployment-multimodal.patch.json` | 追加 initContainer 的持久化补丁 | +| 项目 `deploy/dcu-hygon/H3-USAGE.md` | H3 视频 + H3-Image 节点图与踩坑全文(DCU 线) | +| 项目 `deploy/dcu-hygon/H3-ON-DCU.md` | DCU 部署实录(as-built) | +| 项目 `deploy/k8s-nvidia/H3-ON-2080.md` | H3 on 2080Ti(4Gi 墙补丁 / Dynamic VRAM) | +| 项目 `deploy/k8s-nvidia/A14B-USAGE.md` | A14B 参数表与能力边界 | +| 项目 `deploy/k8s-nvidia/api/wan22_h3_api.json` | H3 实测跑通的裸 workflow(**提交前要包 `prompt`**) | +| 项目 `client/h3_image_gen_k8s.py` | H3-Image 客户端(本技能 `submit_t2i.py` 的原型) | diff --git a/references/pitfalls.md b/references/pitfalls.md new file mode 100644 index 0000000..3f4085e --- /dev/null +++ b/references/pitfalls.md @@ -0,0 +1,79 @@ +# 踩坑速查(跨项目通用) + +## I2V 服务端 + +- **不要 `--force-fp16`**:会把 fp8 权重升成 fp16,是常见崩溃根因;去掉后低内存 cgroup 也稳定。 +- **按启动参数预检,不按 RAM 硬挡**:查服务端 `/system_stats` 的 `argv`,不要凭宿主内存判断能否跑。 +- **跨 prompt 传 conditioning 常被服务端权限封死**:分阶段/接力方案不要做,每段独立、自包含。 +- 网络超时**不能证明任务未提交**;重试前先查状态,避免重复消耗算力。 +- 单段约 5 秒;要更长用 `tpad=stop_mode=clone` 克隆尾帧,清单里标 `"pad": true`。 +- 纯 I2V 服务**没有文生图权重**(`/object_info` 看 `CheckpointLoaderSimple.ckpt_name` 是否为空):首帧必须外部生成。无首帧模式人脸锁不住,别指望用它替代角色锚图省成本。 +- **H3 视频 ≠ 什么都能图生视频**(2026-11-14 实测):`30113` 的 MiniMax H3 在 2080Ti 22 GB 上**只有 T2V 可用**;给 `MiniMaxH3ImageToVideo` 塞 `first_frame` 会走 `vae.encode()` 并把 video VAE 焊住,采样期必 `CUDA out of memory`。`models.md §4.2` 那条「图生视频加 first_frame」只适用于 **DCU 64G**。首帧锁图一律走 Wan2.2 I2V A14B。 + +## 首帧图 + +- 图像生成结果常在右下角带平台水印;`delogo` 在部分静态 ffmpeg 上参数解析异常,改用 `crop=W:(H-70):0:0` 裁掉底部带最稳——不拉伸、不补假像素,I2V 的 `ImageScale crop=center` 会自动居中裁成 9:16。 +- **省额度做法**:三张分镜首帧合并成一次横排三格拼图,本地等分裁切;三格同图还顺带保证角色一致。 +- **拼图切片必须按文件名时间正序**:`ls -1t` 按修改时间倒序会把最后一张当第一张,导致 S01 拿到 S16 的画面。生成名带 ISO 时间戳时,用 `ls -1 /*.png | sort` 正序再每 3 格顺序映射。切完先抽查首/中/尾三类内容再提交。 +- 首帧带可读文字 → I2V 会把它当动态内容重绘成乱码。首帧必须"无文字",文字一律后期烧。 +- 首帧手部畸形(爪状/多余手指)→ I2V 只会继承并放大,**必须换图**,改提示词没用。 + +## 运动提示词 / 漂移 + +- 正向锁要写成**可判定状态**,不要只写否定句:写"双臂垂在体侧 / 手始终低垂 / 细光保持细线 / 双手不触及不跨越 / 不转身 / 不变走廊",并把禁止句放最后强调。 +- 对「几乎静止」的镜头,显式禁止场景补全:`no ceiling / no floor / no perspective vanishing point / no camera movement / never become a bright band`。 +- **Wan2.2 两类高频漂移,正向锁压不住,直接用 `keepSeconds`**: + 1. 静止人物镜——末帧必抬手 / 转正; + 2. 细光分屏镜——细光变光柱、节点增生、双手越界。 + 截前 1.2–2.5s 稳定段慢放到目标时长,慢放反而强化"静止对峙"观感,比反复抽卡省时间。 +- **唯一值得重跑的是硬伤**:首帧乱码文字被重绘、首帧手部畸形——必须换首帧图。 +- 发现漂移只处理该镜,换提示词即换哈希、旧片段不覆盖,留作候选。 + +## 配音 / 字幕 + +- edge-tts 免费免密钥,**商用授权需自行核对微软条款**;免密钥不等于可商用。 +- 先量实测时长再回填分镜 `duration`;不要加快语速硬塞。长句可能超出模型标称时长,用 `pad:true` 让 `tpad=clone` 补足。 +- **旁白唯一性要显式校验**:手写多句时易重复或漏填。加 `len(lines) == len(set(lines))` 断言,并比对剧本表与 `30_shots.json` 的 `line` 逐字一致。改词后必须删除对应 `vo_NN.mp3` 再跑 `tts.py`,否则脚本按文件存在跳过、配音与字幕不一致。 +- 静态 ffmpeg 带 libass,`ass` 滤镜支持 `fontsdir`,中文用系统字体(如 PingFang.ttc)。竖排标注用 ASS 的 `\N` 逐字分行,别让生成模型画文字。 +- **ASS 标点落单**:折行逻辑不要把标点当独立 part;标点直接并入当前行,末尾若只剩标点则并回上一行。 +- **HUD 时间窗按累计 `duration` 算**:绑最后一镜起点 +0.5~2.8s 时,抽帧验收要抽窗口内(如 88s),抽窗口外会误以为 HUD 没烧上。 + +## ffmpeg / 缝合 + +- **不要 brew 装**:macOS 12 + Homebrew 6 有 dav1d Ruby bug。用 `pip install --user imageio-ffmpeg`(静态版)。 +- 去水印用 `crop` + `pad`,**不要 drawbox**(遮罩留痕)。 +- A14B/I2V 视频通常**没有水印**,默认 `--crop-bottom 0`,不要白裁画面。 +- `zoompan` 落版:`d` 取总帧数(2s×30fps=60),`s=720x1280:fps=30` 并补 `format=yuv420p`,才能与主线 concat 一次编码。 +- 缝合顺序:先逐段标准化(裁带 / 居中填充 / 30fps / tpad clone 补足精确时长),再一次 concat + 烧 ASS,避免多次重编码掉画质。 + +## 清单 / 可复现 + +- 提示词每次重写会导致一致性崩且无法复现;固定描述段逐字复用,变量只在 `30_shots.json`。 +- 分镜表不结构化 → 时长、编号、台词全靠记;用 `manju.py validate` 前置拦截。 +- `submit_i2v.py` 与 `manju.py hash-file` 的哈希算法可能不同(前者 `read().strip()`,后者不一定)。预估新哈希要先统一 strip,否则会误以为没换哈希。 +- `manju.py manifest` 保留已有 attempts,扩表时旧记录不会被覆盖;但新提示词哈希全变,脚本按哈希命名会全部 FRESH 重生成,不会误用旧片段。 +- 不做归档 → 第二集找不到第一集设定;`50_manifest.json` 必须保留 attempts 历史。 + +## 配置 / 依赖 + +- 工具脚本**只用 Python 标准库**;配置与清单一律 JSON,避免 YAML 依赖。 +- 路径解析三级回退:`MANJU_ROOT` 环境变量 → cwd 向上找 `config/pipeline.json` → 脚本上级目录。**先 cd 到工作空间根再运行脚本**。 +- 密钥不落明文:端点如需鉴权,走环境变量或密钥工具,不要写进 `config/pipeline.json`。 + +## 生成后清理(ComfyUI 残留) + +- **`/view` 拉回的只是副本**:服务端 `output/` 里的 mp4/png、`input/` 里上传的首帧、以及 `history` 里的节点图与提示词原文全都还在。共享服务上等于把素材留在别人能看到的地方。 +- **标准接口优先**:新版官方路径带 `/api` 前缀(`/api/history`、`/api/queue`、`/api/free`),无前缀是等价别名;脚本先探 `/api/system_stats`,不支持自动回退。 +- **官方删除接口不带任何归属校验**:`POST /api/history {"delete":[pid]}` 谁都能调,而 `30112` 上 151 条历史里绝大多数是别人的任务。必须先读 history 项里的 `client_id` 判归属(台账 `clientId` > `cleanup.clientIds` > `ownerPrefixes`);`requireOwner=true` 时未通过**一律拒绝、不调任何删除接口**。`--prompt-id` 显式清任务要带 `--client-id`。 +- **`client_id` 的位置在内存态与 HTTP 序列化态不同(关键坑,2026-11-12 修)**:ComfyUI 0.38 的 HTTP 序列化布局是 `prompt = [number, prompt_id, graph, extra_data, [...]]`,`client_id` 在 `prompt[3]`;但 **0.45 的内存态**`prompt_queue.history` 是 `prompt = [extra_data, number, graph]`,`client_id` 在 `prompt[0]`。扩展从内存态读,若只查 `[3]` 会在 0.45 上读出空串 → 归属校验全失败、所有任务清不掉。**扩展与客户端都已兼容两种布局**(先查 `[3]`/`[0]`,再退化递归找),改 `client_id_of` 时别再写死 `[3]`。回归测试见 `scripts/selftest_cleanup.py`。 +- **先读后删**:`GET /api/history/` 抽 `outputs` 清单 → 再批量 `POST /api/history {"delete":[...]}` + `/api/queue`。删了就再也查不出服务端留下了什么。 +- **装了扩展时顺序反过来**:`purge` 依赖 history 反查产物文件名,必须**先删文件再删记录**;旧顺序只适用于没装扩展的降级路线。见 [models.md §3.4](models.md)。 +- **200 空 body ≠ 删除成功**:这些 POST 幂等,删不存在的 pid 也返回 200。必须删后复核 `GET /api/history/`(判据是「删前有 → 删后无」)并查 `/api/queue`;`{}` 还有排队 / 执行中 / 不存在三义,单看 `{}` 判不了任何事。 +- **`history` 是内存态、文件是持久态**:Pod 重启后记录自然消失,`output/` 却还在 PVC / 宿主盘上。别把「重启过了」当成「清理过了」。 +- **官方删不了 `output/` 文件**(已核对 `server.py` 与官方文档):`DELETE /userdata/{file}` 只管 `ComfyUI/user/`,`DELETE /api/assets/{id}` 默认 503 且删的是数据库引用。**首选技能自带扩展** `assets/comfyui-manju-cleanup/`:只传 pid,服务端从 history 反查文件、二次校验归属、做路径逃逸与跨任务引用计数;装到 `custom_nodes/` 并重启进程即可,官方 `add_routes()` 自动镜像 `/api` 前缀。降级路线:社区 `comfyui_extra_api` / `ComfyUI-api-tools` 补标准 `DELETE`(配 `cleanup.deleteApi`),或在服务端文件系统上精确删(`cleanup.commands`)。没配模板时脚本只列清单,不要报「已清理」。 +- **扩展只按 pid 反查,不接受任意路径**:这是防误删的关键,别改成「客户端传文件名列表」。它还会把被别的 pid 引用的文件判 `shared` 跳过(共用首帧 / 同名产物);`dry_run` 默认 `true`,`MANJU_CLEANUP_TOKEN` 可开鉴权。 +- **重启 ComfyUI ≠ 清理,而且会清掉别人的记录**:`history` 是内存态,重启后所有人的记录一起消失;扩展此时按 pid 反查不到,返回 `exists=false / owned=false` 并**拒绝**删文件(DCU 2026-11-12 部署重启后实测:23 条 history 归零,purge 对历史 pid 一律拒绝)。所以「重启前的残留产物」只能用 `cleanup.commands` 按文件名清;部署扩展需要重启时,先确认队列空闲并知会同机用户。 +- **`{"clear": true}` 是地雷**:会清掉同一个 ComfyUI 上所有人的任务,只按 `prompt_id` 精确删。 +- **别清错对象**:本地已导出的成片、`40_prompts/`、`30_shots.json`、`50_manifest.json` 是流水线资产,一律保留;导出闸门会拦下本地成片缺失/过小的条目,防止没导出就把证据删了。 +- `outputs` 里可能回带 `type=input` 的源素材(LoadVideo / 预览节点),它和 `output` 不同根,分流处理,别混进 `{files}` 一起 `rm`。 +- **`/free` 别每镜调**:它只设队列 flag,下一个队列循环才卸载;4Gi 环境重新加载模型要几分钟。整批归档后统一 `--free` 一次。 diff --git a/references/render.md b/references/render.md new file mode 100644 index 0000000..5eb237d --- /dev/null +++ b/references/render.md @@ -0,0 +1,45 @@ +# 缝合与导出 + +`tools/render.py` 把已采用片段 + 配音 + ASS 字幕 + HUD 标注 + 落版缝成竖屏成片。 + +## 环境 + +- **ffmpeg 用 `pip install --user imageio-ffmpeg` 的静态版**;脚本运行时调 `imageio_ffmpeg.get_ffmpeg_exe()`。 +- **不要用 brew 装**:macOS 12 + Homebrew 6 有 dav1d Ruby bug。 +- 成片规格从 `config/pipeline.json → output` 读,默认 720×1280 / 30fps / H.264+AAC;全片不混用分辨率与帧率。 + +## 逐段标准化 + +1. **去水印**:仅当源有水印时用 `--crop-bottom 60`(crop 去带 + 居中填充),**不用 drawbox**。本链路 I2V 输出通常无水印,默认 0。 +2. **补足时长**:I2V 约 5 秒画面用 `tpad=stop_mode=clone` 克隆尾帧补足到 `duration`;清单标 `"pad": true`。 +3. **`keepSeconds` 局部修正**:只取前 N 秒稳定段慢放到目标时长(漂移镜用),N 写在 `30_shots.json`。 +4. 统一 30fps + `format=yuv420p`。 + +## 字幕 + +- 取 `line` 完整旁白,**按标点折 1–3 行,标点不落单**;不在生成阶段烧字。 +- 字体用系统中文体(如 PingFang.ttc),通过 `fontsdir` 指定。 +- 竖排文字用 ASS 的 `\N` 逐字分行。 + +## 包装 + +- HUD:横排 / 竖排两种,**全片文字只标一次(一横一竖)**;时间窗按累计 `duration` 计算。 +- 落版:光环 / 光束 / 星点 + `zoompan` 缓推,用 `tools/make_overlay.py` 程序化生成(零积分)。 +- `zoompan` 的 `d` 取总帧数(2s×30fps=60),`s=720x1280:fps=30` 并补 `format=yuv420p`,才能与主线 concat 一次编码。 +- 片头 3 秒内出现核心冲突,不做长片头;转场克制。 + +## 缝合顺序 + +先逐段标准化,再一次 concat(主片 + 落版)并同一步烧 ASS,避免多次重编码掉画质。 + +## 配音先于剪辑 + +`work/EPxx/audio/vo_NN.mp3` 由 edge-tts 生成(音色见 `config/pipeline.json → tts.voice`)。**先量出每句实际时长再回填 `duration`**。若一句说完画面还空 2 秒没事发生,该镜剪短或加动作,不用加快语速硬塞。每角色固定音色并记录参数,避免下一集换声。 + +## 交付 + +- 只拼 `status: adopted` 的片段;`rejected` 另建候选目录,保留旧采用文件与提示词历史。 +- 导出后登记 `renders/INDEX.md`(路径、时长、校验和、生成参数、来源片段),成片本体不入库。 +- 交付文案区分「已生成 / 已采用 / 已合成 / 已归集」。 + +商用前核对音色授权与 AI 生成内容标识要求。 diff --git a/references/review.md b/references/review.md new file mode 100644 index 0000000..f71dc38 --- /dev/null +++ b/references/review.md @@ -0,0 +1,52 @@ +# 审片与归档 + +**文件路径、静帧、工具成功都不证明你看过全片或听过音轨**;无视频读取能力时请用户预览,并如实记录「用户预览采用」与 Agent 未核验项。 + +## 快速审片 + +```bash +python3 tools/review.py projects/EPxx/30_shots.json --group 1 # S01–S09 首/中/末联系表 +python3 tools/review.py projects/EPxx/30_shots.json --only S13,S15 +``` + +联系表输出到 `work/EPxx/review/`。看首/中/末三帧即可判定身份、构图、漂移;判定不了再抽原始尺寸单帧放大。 + +## 图像核验 + +身份、数量、必要视角、服装与物件、环境关系、可读文字。工具返回成功 ≠ 成图符合要求。 + +## 视频核验 + +- 剧情、对白及说话人、OS/VO、身份与在场关系 +- 动作接触、持物与空间连续性、声音 +- 实际穿帮:脸/发型/服装漂移、多余或缺失的肢体与手指、手脸融合、人物或道具穿模、关键道具闪现/消失/复制/换手、尺寸结构突变、包装结构融化、镜面/玻璃/阴影错误复制 +- 输出规格:分辨率 / fps / 编码、音画同步、响度 + +**连续片段先判关联类型**:`continuous` / `partial` 才比较人物世界位置、姿态、朝向、持物与环境;`reset` 只验本段。 + +## 漂移决策树 + +1. 首/中帧好、末帧抬手/转正/变光柱 → `keepSeconds` 截前段(见 [pitfalls.md](pitfalls.md))。 +2. 首帧就有乱码文字 / 畸形手 → 换首帧图重跑,改提示词没用。 +3. 全段稳定 → 直接采用。 +4. 轻微软化(自然眨眼、光点轻微下垂)且不破坏核心约束 → 可接受,不修正。 + +## 采用与下一段依据 + +采用决定记录:片段与剧情范围、采用的生成尝试、拟用区间、**实际结束状态及来源**、已检查/未检查项、后续依赖。 + +连续片段的下一段初始事实必须来自可查看视频、真实接戏帧或用户反馈,**不用计划末态冒充实际末态**。当前结果错误先处理当前段,不把穿帮升级成新剧情。 + +## 归档 + +| 记到哪 | 内容 | +|---|---| +| `50_manifest.json` | 每次尝试的提示词快照、参数、参考、返回与实际文件;采用决定;重做原因 | +| `renders/INDEX.md` | 成片路径、时长、校验和、生成参数、来源片段 | +| `logs/` | 提交与渲染排障日志 | + +归集保留原件;旧交付内容不同时使用新版本目录,避免混入落选素材。默认交付不含发布、上传或清理源文件。 + +## 终止规则 + +最终回复说明:做成了什么、真实文件在哪、哪些内容由谁核验、唯一必要的下一步。全部片段采用、成片合成、目录归集分别据实登记。 diff --git a/references/storyboard.md b/references/storyboard.md new file mode 100644 index 0000000..0b34c33 --- /dev/null +++ b/references/storyboard.md @@ -0,0 +1,33 @@ +# 分镜与审阅(三角色) + +源自 Toonflow `storyboardTeam` 的三角色与最小权限边界。原文见 [toonflow/toonflow-workflow-director.md](toonflow/toonflow-workflow-director.md)。 + +## 三角色 + +| 角色 | 做什么 | 不做什么 | +|---|---|---| +| 导演 | 确认原始剧情、时长、画幅、禁忌;分派编写与审阅;整合交付,标明「用户原始设定 / 创作补充 / 待确认」 | 不把成员结果当用户指令;不编造缺失设定 | +| 编写 | 按 `00_brief.md` 写 `10_events.md` 与 `30_shots.json` 草稿:每镜写剧情目的、可见动作、景别、运动、声音、时长、映射的 `E##` | 不擅自扩大集数或镜头数;不编造素材路径 | +| 审阅 | 核对剧情覆盖、动作可执行性、时长自洽、人物/场景连续;返回「镜号 + 依据 + 最小修改建议」 | 不制造问题;不替用户批准生成;不修改文件;不评价不存在素材的画质 | + +三者共用铁律:**不消耗算力、不写入未授权文件、不夸大事实**。 + +## 连续性核对 + +- 衣着、携带物、受伤状态、情绪变化可追溯到故事或前一镜。 +- 同一空间的相对位置、出入方向、视线、主光方向可理解;跳切或时空变化显式标注。 +- 动作起点终点衔接;相邻镜不得无说明地改变持物手、道具数量、人物位置。 +- 对白、环境声、动作声与画面一致;不为无声设定擅自加对白。 +- **尚无实际图像/视频时只能审阅文字方案**,不能评价不存在素材的画质、口型或运动效果。 + +## 输出 + +1. `10_events.md`:一行一个 `E##`,写「谁做了什么 → 造成什么结果 → 情绪 → 预估秒数」,30–60 字,只写影响主线的动作,不复述整段对话。 +2. `30_shots.json`:一镜一行,字段见 [assets/shot.schema.json](../assets/shot.schema.json)。`eventIds` 必须能回溯到 `10_events.md`。 +3. 审阅结论:按镜号列问题,不写「整体不错」这类无依据结论。 + +跑 `python3 tools/manju.py validate projects/EPxx/30_shots.json` 作为机器前置校验,再进入导演内核写逐镜提示词。 + +## 基线资产 + +角色锚图/画风模板先定稿并锁只读;I2V 只能「给首帧让它动」,首帧质量决定成片上限。HUD 与落版用 `tools/make_overlay.py` 程序化生成,零积分消耗。 diff --git a/references/submit-i2v.md b/references/submit-i2v.md new file mode 100644 index 0000000..8271423 --- /dev/null +++ b/references/submit-i2v.md @@ -0,0 +1,83 @@ +# 图生视频提交与预检 + +**本文只讲 Wan2.2 I2V A14B(视频模型②)。** 内网还有第二个视频模型 **MiniMax H3**(带原生音轨,20 步 / 无 LoRA)——它的采样节点、权重、输出节点与 A14B 完全不同,**不能把本文参数或 `submit_i2v.py` 直接指过去**。端点全表、H3 节点图、文生图与辅助模型 API 见 [models.md](models.md),部署拓扑与恢复见部署侧 `deploy/k8s-nvidia/deploy-as-built.md`。 + +> **2026-11-13 起**:图与两种视频都跑在**同一个实例** `192.168.1.30:30113`(ComfyUI 0.45)。 +> `videoModel.endpoint` 默认已指向它;`30112` / `30111` 与它指向同一个实例(Service selector 改指),任选其一都能跑同一张图。 +> 单实例共享 1 张 22 GB 卡与 4 GiB 内存硬限,**出图/出视频必须串行**。 + +`tools/submit_i2v.py` 默认适配 **Wan2.2 I2V(A14B)双专家 4-step** 工作流。端点、分辨率、帧数、步数全部从 `config/pipeline.json → videoModel` 读取;换模型需另写节点图(不是改 UNET/LORA 常量就够了)。 + +## 参数来源 + +| 项 | 来源 | +|---|---| +| 端点 `HOST` | `config/pipeline.json → videoModel.endpoint` | +| 宽高 / 帧数 / fps / steps | 同上 `videoModel.*` | +| 标称单段时长 | `frames / fps`(默认 81/16 ≈ 5.06s) | +| 运动提示词 | `40_prompts/Sxx.i2v.txt` | +| 首帧图 | `work/EPxx/images/Sxx.png`(或 `refs` 指定路径) | +| 输出 | `work/EPxx/videos/Sxx_.mp4` | + +## 协议(ComfyUI) + +`/upload/image` → `/prompt`(双专家工作流)→ `/history` 轮询 → `/view` 下载。 +明文 HTTP 若被本机代理改写成 `text/html`,脚本已内置 `ProxyHandler({})` 绕过代理。 +完整端点表与最小提交骨架见 [models.md §3](models.md):`/prompt` 必须包 `{"prompt": 节点图}` 外层,裸 workflow 会 400。 + +## 预检(必做) + +1. 服务端 `/system_stats`:确认在线、看 `argv` 有无 `--force-fp16`(有则高风险);记下版本——**30113 是 0.45.0**,`30112` 是 0.38.0。同一张节点图两边都能跑,但 `--fp16-unet` 只有 0.38 需要,0.45 上出现它会毁掉 H3-Image 的 bf16 路径。 +2. `/object_info/UNETLoader`:必须能看到 `wan2.2_i2v_high_noise_14B_fp8_scaled` 与 `low_noise`。**30113 上应共 4 个扩散模型**;只剩 1 个(H3-Image)说明 pod 重建后 `/local` 软链丢了 → 容器内跑 `sh /basedir/apply-multimodal.sh`。 +3. `/queue` 确认空闲:30113 一个实例同时接出图与两种视频,**有排队就先等**,否则会撞 4 GiB 内存墙。 +4. **按启动参数预检,不按 RAM 硬挡**。 +5. 确认提示词哈希与 `a14b_runs.json` 里的旧记录不同,避免误用旧片段。 + +## 踩坑(必读) + +- **不要 `--force-fp16`**:fp8 权重被升成 fp16,是崩溃根因。 +- **必须挂 `ModelSamplingSD3(shift=5)`**:两个专家各挂一个。漏了不会报错,但画面发软、运动漂移(脚本 2026-11-13 已补上)。 +- **`SaveVideo.format` 是动态组合**:取值 `auto` / `mp4` / `mkv` / `webm`(30113 还有 `mov`),传 `video/h264-mp4` 这类组合串会被静默丢弃。 +- **跨 prompt 传 conditioning 被服务端权限封死**:分阶段/接力方案不做,每段自包含。 +- 单段超时:用 `pad:true` + `tpad=stop_mode=clone`,不要在提交端拉长帧数。 +- 网络超时不能证明未提交;重试前先查 `/history`,避免重复消耗算力。 +- 服务端 4 GiB cgroup 下**串行提交**,不要并发;30113 上还要和出图、H3 视频排队。 +- **别把 H3 的东西搬过来**:turbo LoRA、`MiniMaxH3ImageToVideo`、`SamplerCustomAdvanced`、`H3AudioClean` 都属于另一条线。 + 反过来也别把 A14B 的禁忌套到 H3 上:`--fp16-unet` 对 **30111(0.38)必需、对 30113(0.45)禁用**。 +- 首帧图若无外部图像能力,用内网 H3-Image 出:`python3 tools/submit_t2i.py --ep EPxx --shot Sxx --prompt-file 40_prompts/Sxx.t2i.txt`(默认落 `work/EPxx/images/Sxx.png`,正是本脚本读取的路径)。 +- **导出后要清服务端**:`/view` 拉回的 mp4 只是副本,服务端 `output/` 里那份和 `history` 记录还在。见 [models.md §3.4](models.md) 与下方「导出后清理」。 + +## 命名与记录 + +``` +work/EPxx/videos/Sxx_.mp4 +``` + +`promptHash8` = `40_prompts/Sxx.i2v.txt` 内容 `sha256` 前 8 位(脚本用 `read().strip()`,预估哈希要一致)。改提示词即换文件,**旧版不覆盖**,便于对比筛选。 + +每次提交在 `50_manifest.json` 追加一条 attempt:提示词快照、模型与完整有效参数、参考文件与顺序、返回与实际文件、授权范围与剩余次数。**提示词版本与结果版本分开登记**。 + +## 常用命令 + +```bash +python3 tools/submit_i2v.py projects/EPxx/30_shots.json # 全部 +python3 tools/submit_i2v.py projects/EPxx/30_shots.json --only S03 # 只提 S03 +python3 tools/submit_i2v.py projects/EPxx/30_shots.json --only S03 --force # 强制用新哈希重跑 +python3 tools/submit_i2v.py projects/EPxx/30_shots.json --cleanup # 每镜导出后自动清服务端 +``` + +## 导出后清理(必做) + +成片下载成功即触发,不清干净不算这一镜完结: + +```bash +python3 tools/cleanup_comfyui.py --ep EP01 # 预演,看将清哪些记录/文件 +python3 tools/cleanup_comfyui.py --ep EP01 --apply # 真清 +python3 tools/cleanup_comfyui.py --ep EP01 --shot S03 --apply +``` + +也可用 `--cleanup` 让提交脚本导出后自动清,或在 `config/pipeline.json → cleanup.auto` 设 `true`。六条要点:① **只清自己发起的任务**:提交脚本用 `manju-i2v-*` 作 `client_id` 并把 `clientId` 写进台账,清理时按 history 项 `prompt[3]["client_id"]` 精确比对(`cleanup.clientIds` / `ownerPrefixes` 兜底);`requireOwner=true` 时未通过归属**一律拒绝、不调任何删除接口**;② 记录删除走官方 `/api` 前缀标准接口(`/api/history`、`/api/queue`、`/api/free`),脚本会探测并回退;③ **200 空 body 是幂等响应,不等于删除成功**,删后要复核 history 变 `{}`、queue 里不再有该 pid;④ 产物文件官方**没有** HTTP 删除路由,优先用技能自带扩展 `assets/comfyui-manju-cleanup/` 的 `POST /manju/cleanup/purge`(只传 pid,服务端从 history 反查文件、二次校验归属、防路径逃逸与跨任务共用),未装则降级 `cleanup.deleteApi` / `cleanup.commands`;⑤ **装了扩展要先删文件再删记录**(purge 依赖 history 反查),没装扩展才用旧的「先抽清单 → 删记录 → 复核 → 删文件」;⑥ 只按 `prompt_id` 精确删,禁用 `{"clear": true}`。本地成片、提示词原文、manifest 一律不动。整批做完再统一 `--free`。`python3 tools/selftest_cleanup.py` 可本地 mock 自检 26 项断言。详见 [models.md §3.4](models.md)。 + +## 闸门 + +生成前展示:镜号与数量、模型、完整提示词、实际参考、规格、执行次数与预估算力消耗;等明确授权。返回任务 ID 只表示已开始,不宣称完成;完成以真实文件与状态回读为准。额外重试先核对授权是否覆盖。**导出后**再报一次清理结果:每条任务的 `client_id` 归属判定(拒绝的要说明)、history / queue 是否「删前有→删后无」地复核过、服务端产物文件是走扩展 purge 还是降级路线删掉、哪些因未配命令模板而待手工处理。不能把 HTTP 200 空 body 直接说成「已删」,也不能把别人的任务算进清理数。 diff --git a/references/toonflow/TOONFLOW-LICENSE.txt b/references/toonflow/TOONFLOW-LICENSE.txt new file mode 100644 index 0000000..dd6492c --- /dev/null +++ b/references/toonflow/TOONFLOW-LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 HBAI-Ltd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/references/toonflow/toonflow-workflow-director.md b/references/toonflow/toonflow-workflow-director.md new file mode 100644 index 0000000..0cb7413 --- /dev/null +++ b/references/toonflow/toonflow-workflow-director.md @@ -0,0 +1,1406 @@ +--- +name: workflow +description: 在 Toonflow 当前画布中把创意、小说或定稿剧本制作成可查看的文本、图片资产和视频片段,支持复用素材、续作与局部修改。用于实际制作或继续已有项目;明确只要对话文字时不操作画布,讨论或编辑技能本身时不启动制作。 +metadata: + version: "2.7.0" + displayName: 视频制作工作流 + author: Toonflow + github: https://github.com/HBAI-Ltd/Toonflow-app +--- + +# Toonflow 画布制作工作流 + +从用户已有内容接续,把成果放到当前 Toonflow 项目。以本次剧本与真实素材组织制作,不要求用户先补齐一套制片文档。这个包包含所需方法,不依赖原来的多岗位 Skill 组。 + +## 从哪里开始 + +先判断本次交付、已有资料和用户明确限制,沿用已知的时长、风格、画幅、语言与版本。只问影响结果且无法合理判断的缺项。 + +| 已有输入 | 处理方式 | +|---|---| +| 创意或一句话 | 补齐人物目标、阻力和结果,形成可审阅的故事与本次完整剧本 | +| 小说、故事或原著片段 | 确认改编范围,保留原文,追踪事件、人物、对白与未知信息,转成可视听剧本 | +| 已定稿剧本 / 时间轴 + 当前目标是制作、生成、继续或修订视频 | **无论用户是否提到“Seedance”“提示词”或具体模型,都立即进入本文件内嵌的「SEEDANCE EPISODE DIRECTOR · PART A」执行。** 用户未指定模型时,立即锁存 Seedance 路由,并只用一次简短提问确认“Seedance 2.0 还是 2.5”;用户已指定 2.0/2.5 时按对应模型路由。询问模型不得转去画布配置、资产流程或其他提示词方法。 | +| 已定稿剧本 / 时间轴 + 仅要求资产、剧本阅读、诊断或非视频任务 | 只处理用户明确要求的非视频范围;不因为存在定稿剧本就自动生成视频提示词。 | +| Seedance 任务中用户未指定模型 | **必须先确认目标模型。** 只问一次“Seedance 2.0 还是 2.5”;这一步属于 PART A 的 A0 输入判定,不是普通配置询问。用户回答后继续同一个 Seedance 执行态;画幅、分辨率、参考模式、原生音频等执行配置不能替代、绕过或中断该路由。 | +| Seedance 任务中用户已指定 2.0/2.5 | 直接执行 PART A;2.0 走 A9.1、2.5 走 A9.2。 | +| 续集或已有制作 | 读取指定的历史、当前节点和采用记录,确认本次范围,从实际进度继续 | +| 指定一个片段、资产或修改 | 只处理该范围和确实受影响的依赖,不重跑整条链 | + +> **Seedance 提示词生成规则已直接嵌入本 workflow,不是外部 Skill,也不是 workflow 去调用另一个 Skill。** 当任务进入「已确认剧本 → Seedance 2.0/2.5 分段提示词」阶段时,必须直接执行本文件下方的 **「SEEDANCE EPISODE DIRECTOR · PART A」**。该内嵌规则是本 workflow 在 Seedance 提示词生成阶段的最高优先级执行规范:以用户提供的 `SKILL-seedance-episode-director.md` A0–A12 为基线,并合入用户之后明确追加的连续性、生成稳定性与穿帮校验规则;若本 workflow 其他段落、references/methods、storyboard 或旧说明与其冲突,以当前内嵌 PART A 为准。除用户后续明确修改外,不得用其他方法重写、弱化或替换其中的剧情保真锁、目标模型确认规则、分段/时长规则、Reference binding、A9 模板、A11 校验或 A12 单次优化。 + +### Seedance 路由锁存(最高优先级入口规则) + +当同时满足以下两项时,**自动视为 Seedance 任务**,不要求用户必须说出“Seedance”“2.0/2.5”“生成提示词”等触发词: + +1. 当前已有可执行的定稿剧本、时间轴、镜头剧情段、已确认片段文本,或用户明确要求继续已有视频制作; +2. 当前意图是制作视频、生成视频、继续视频、修订视频、准备视频生成、把剧情做成视频,或对即将生成的视频进行配置。 + +一旦命中,立即锁存为 **Seedance 执行态**,并遵守: + +- **先进入 PART A,再处理画布执行配置。** 目标模型本身属于 A0 必要输入,不算画布配置;不得先调用画布读取工具(`getCanvas/findCanvasNodes/getCanvasNodes/getCanvasEdges/getNodeTools`)或节点的 `node:getConfig`、先问 provider/resolution/ratio/mode、先做通用分镜,或先进入其他 prompt 方法再决定是否用 Seedance。 +- 用户没有指定 2.0/2.5 时,**必须在 Seedance 路由已经锁存后,用一次简短提问确认“Seedance 2.0 还是 2.5”**。提问后保持 Seedance 执行态,不退出、不切换到普通 workflow;用户回答模型后立即从 A0 继续执行 PART A。 +- 用户已经指定 2.0/2.5 时,直接把该信息作为 A0 输入;不得再重复询问。 +- **目标模型确认与执行配置询问分开。** 未指定 2.0/2.5 时,先在 A0 内确认目标模型;确认后,若执行层还需要询问画幅、分辨率、生成音频、参考模式、供应商等配置,这些问题只能作为同一个 Seedance 任务的执行参数补充。用户回答后仍处于同一个 Seedance 执行态,不得回到通用 workflow、重新选择提示词方法或跳过 A0–A12。 +- 用户在配置问答中只回复“16:9”“1080p”“开原生音频”“2.5”等短答案时,这些答案视为**当前 Seedance 任务的配置补充**,不是新任务;不得因为这条回复本身没有再次出现“Seedance/提示词”字样而解除锁存。 +- 若用户先问“有什么配置/用什么配置”后再决定,回答配置问题不取消 Seedance 路由;一旦继续制作视频,必须回到/继续 PART A。 +- 只有用户明确把任务改成“不要生成/修订视频提示词,只做资产、剧本创作、咨询或其他非视频工作”,才解除 Seedance 路由锁存。 +- 实际媒体生成阶段若实时节点不支持 A0 已选模型,只能报告真实能力冲突并回到 PART A 的受影响项处理;**不得用配置层的默认模型静默替换 Seedance 路由。** + +**核心:Seedance 是视频制作阶段的导演执行内核,不是只有用户说出某个关键词才触发的可选插件。** + +### Seedance 阶段硬隔离(强制) + +一旦命中上方“Seedance 路由锁存”——即已有可执行剧情输入且当前目标进入视频制作/生成/修订——立即进入**硬隔离执行态**;不要求用户额外说出“Seedance”或“提示词”: + +- 从进入 PART A 到最终提示词输出完成,**只执行本文件内嵌 PART A**,不得再读取或套用 `references/sourceAndScript.md`、`references/methods/*`、任何旧 storyboard/分镜规则或人类教学 references,亦不得从这些文件补第二套分段、时长、镜头、站位、表演、运镜、连续性、声音、Reference binding、模板或 QA 规则。 +- 用户已经给定的剧本、时间轴、角色/场景/道具设定、真实参考节点/资产句柄属于 PART A 的输入,不受本隔离限制。 +- **唯一例外**:PART A 的 A1.2/A4 明确需要“无参考图时补参考资产/必要设计提案”时,才可按需读取 `references/assets.md`、`references/methods/visualDesign.md`、`references/methods/colorAndLight.md`;只取外观/空间/材质/光线设计所需内容,**不得把这些文件中的时长、镜头、表演或叙事方法带回 Seedance 提示词规则**。完成资产/设计提案后立即回到 PART A。 +- Seedance 最终提示词已经按 A11/A12 定稿后,如用户明确要求实际连接参考、写入生成节点或生成/验收媒体,才退出提示词硬隔离,进入 `canvasExecution.md` / `stateAndDelivery.md` 的**执行层**。执行层只能搬运已定稿 prompt、连接真实参考、设置真实模型参数和核验结果,**不得重新改写 PART A 已确定的分段、格式、剧情、站位、表演、运镜或连续性**。 +- 若执行层发现模型真实能力与已定稿 prompt 存在硬冲突,只报告具体能力冲突并回到 PART A 受影响项处理;不得由画布规则自行另造兼容提示词。 + +**目的:Seedance 阶段只有一个导演规则源——本文件内嵌 PART A。优先级声明不能替代硬隔离。** + +**仅在剧本尚未定稿、确实需要创作或改编时**读取[输入与剧本](references/sourceAndScript.md)。一旦进入 Seedance 提示词硬隔离,本条停止生效。 + + + +## Seedance 提示词生成的内嵌执行核心 + +以下内容以用户提供的 `SKILL-seedance-episode-director.md` PART A 为执行基线,并已合入用户后续明确追加的连续性、生成稳定性与穿帮校验要求。**运行时直接执行本节,不再读取、不再调用任何独立 seedance-episode-director Skill。** 本节与 workflow 其他内容冲突时,本节优先。 + +# PART A — 执行规则 +═══════════════════════════════════════════ + +## A0. 输入判定 + +拿到用户输入后,先在心里判定以下事项;能从文本推断就直接执行,除非缺失会导致成片方向根本不同,否则不要问超过 2 个问题: + +1. **目标模型** —— 用户说 2.5 就按单段最长 30s;说 2.0 就按单段最长 15s;**如果用户没说,必须用一次简短提问确认“Seedance 2.0 还是 2.5”后再继续**。该提问属于本 Seedance 任务的 A0 输入判定,提问前后都保持 Seedance 路由锁存;不得因为需要确认模型而转去普通 workflow、画布配置或其他提示词方法。 +2. **总时长要求** —— 用户给了严格总时长(如“55s”)就按 A3 做时长预算;没给则由完整剧情的自然节奏估算总长。 +3. **叙事规模** —— 判断是单场戏、短集,还是 2–3 分钟甚至更长的一整集。 + - 不论多长,**先规划全片,再决定分几批交付**。 + - 分批只是交付容量管理,不等于删剧情,也不等于重新切剧情。 +4. **原始时间码** —— 若用户已给【0–10s】【10–25s】等时间块,把它们视为原剧情节奏/参考时间轴;除非用户明确说“严格锁死”,否则不能机械等同于生成段。 +5. **是否已有资产参考库**(角色图 / 场景图 / 道具图 / 命名标签)? + - 有 → **直接引用**(按 A1.2) + - 无 → 从剧情文本里抽取资产,只登记本集真实出现过的资产;若模型为 2.5 且需要锁定身份,按 A1.2「情况二补充」可先生成参考图。 +6. **画面文字来源** —— 区分“后期字幕/标题”与“场景内实体文字/产品包装文字”,按 A1.3 处理。 + +**核心约束:完整、顺序、可生成。** +- 不丢剧情,不跳过“难拍”节拍。 +- 不重排原剧情先后顺序。 +- 不为了把段数压到理论最少而牺牲自然对白、动作过程或反应时间。 +- 长剧情先建立“全片段表”,再按单批容量切成 Batch 1 / Batch 2 / Batch 3……;每批都保留全局段号。 + +### A0.1 剧情保真锁(最高优先级 · 全流程生效) + +**总纲:只导演,不编剧。** + +本 Skill 可以做:**拆分、合段、计时、镜头化、站位化、把已有动作写得可见、补充不改变剧情事实的物理/摄影执行细节。** + +本 Skill 不可以做:**新增剧情事件、删除剧情事件、替换剧情事件、改变事件先后、改变事件执行者/承受者、改变道具来源或用途、补写用户没有提供的前史/因果、把模糊角色擅自具体化。** + +#### A0.1.1 剧情事实来源优先级 + +发生冲突时,按以下顺序认定“什么才是剧情事实”: + +1. **用户最新一条明确修改指令** +2. **用户当前提供的原始剧情 / 脚本 / 时间轴** +3. **用户明确提供的角色、场景、道具资产设定** +4. **AI 之前生成的提示词、总结、补充说明** + +**AI 自己上一轮补出来的内容永远不能反过来升级成剧情事实。** + +例如:AI 上一版自行补了“角色A先从容器中取出道具A”,但用户原剧情只写“角色A使用道具A”,下一版不得因为“连续性”继续继承这个额外取出动作。 + +#### A0.1.2 五类绝对禁止改动 + +对用户原始剧情中的每个事件,禁止: + +1. **新增**:原文没有“开盖 / 抽纸 / 起身 / 递给 / 回头 / 拿起包装”,不得为了顺畅自行补上。 +2. **删除**:原文已有动作、对白、反应、停顿、空镜,不得为了时长或表演克制删掉。 +3. **替换**:原文是 A 动作,不得改成看起来更合理的 B 动作。 +4. **改归属**:原文写“父母 / 家长 / 成人”时,不得擅自指定为“爸爸”或“妈妈”;谁说、谁做、谁拿、谁被擦都必须保持。 +5. **改顺序 / 改因果**:不得为了产品逻辑、连续性或镜头美感,把后面的行为提前,或为后面的状态补一个原文不存在的前置动作。 + +#### A0.1.3 允许的“具体化”边界 + +只有满足以下条件,才允许把原文动作写得更具体: + +- 具体化内容**直接包含在原动作的物理执行中**; +- 不新增新的剧情决定、道具状态变化或角色关系; +- 删除这条具体描述后,剧情事实完全不变; +- 不要求观众获得一个原文没有的新信息。 + +例如: +- 原文“角色A用道具A擦拭手部” → 可以写“道具A接触掌心并擦过手指”,这是已有动作的可视化。 +- 原文“角色A用道具A擦拭手部” → **不能**写“拿起容器 → 打开容器 → 取出新道具A → 再擦拭”,因为新增了多个剧情事件。 + +摄影机移动、构图、景别、焦点、光线可见结果、已有碰撞对应的拟音,属于技术实现,不视为新增剧情;但它们也不得制造新的剧情事实。 + +#### A0.1.4 不补前史、不追溯来源 + +如果某个时间块开始时,原文已经给出一个状态,就把它当作该节拍的**既定初始状态**。 + +- 原文写“角色A手里已经拿着道具A进入画面” → 直接从“手里已有道具A”开始。 +- 不得因为“道具总要有来源”而自行补“拿容器 / 开盖 / 取出”。 +- 原文写“角色已经站在某位置” → 可以从该位置状态开始;除非原文明确写了起身/走过去,否则不得补完整移动过程。 + +**连续性只维护用户已经定义的状态,不负责替用户补没有写出的前史。** + +#### A0.1.5 模糊信息保持模糊 + +用户没有明确的内容,默认保持原有抽象层级: + +- “父母 / 家长 / 成人 / 工作人员 / 某人”等泛称保持原有抽象层级,不擅自确定身份、性别或人数; +- “一只手”不推断具体左手/右手,除非镜头执行确实需要且不会形成后续剧情事实; +- “拿道具A”不自动推断“从容器中新取出一件”; +- “使用道具A完成动作”不自动推断使用次数、消耗数量或第几件; +- “在旁边”不擅自创造精确空间关系,除非为镜头生成需要给出中性坐标,且不改变剧情。 + +#### A0.1.6 源剧情存在空缺/矛盾时 + +- **空缺**:不自行编桥接剧情;优先用 HARD CUT / 新时间块 / 新段从下一个已知状态开始。 +- **矛盾**:不自行选择一个版本覆盖另一个;按用户最新明确修正优先,否则在全片总览标注“源文本冲突”。 +- **严格总时长与剧情冲突**:允许增加段数或标注时长冲突,不允许删改剧情解决。 + +--- + +## A1. 输出语言与资产命名 + +### A1.1 输出语言(强制) +**默认全中文。** 正式提示词、资产清单、站位说明、表演层、时间轴—— +全部用中文写。 + +**保留原文不译的部分:** +- 对白台词(原文照抄,如「君は?」「何が?」) +- 数值与单位:`15s` `30s` `24fps` `4K` `2–3mm` `180°` `0:00–0:06` +- 光学角度:`29°` `47°` `84°` `107°` +- 技术缩写:`HARD CUT` + +**结构标题规则:** +- Seedance 2.0:结构标题默认中文。 +- Seedance 2.5:最终正式提示词固定使用以下英文字段标题:`Objective`、`Reference binding`、`Immutable locks`、`Target duration`、`Timeline`、`Visual direction`、`Audio direction`、`Preserve`、`Avoid`;字段内容默认仍用中文。 + +**整段英文版例外**:只有用户明确说“给我英文版 / for an international pipeline”时,才把字段内容也改为英文。 + +### A1.2 资产命名与参考标签 + +**分两种情况:** + +**情况一 · 用户已建立参考标签库** +用户在自己管线里用了命名标签(如 `@HERO1V2`、`@林直人_v2`、 +`#老宅客厅` 等)—— +- **直接原样引用**,用户给什么就照抄什么,包括 `@` / `#` / 任何符号 +- 这些标签是**角色/场景/道具的身份参考句柄**, + 对应真实的参考图或已建立的资产库 +- **禁止的是:用上一段的尾帧画面作为站位参考**—— + 站位永远靠绝对坐标在文字里重建(见 A5) + +**情况二 · 用户没有标签库** +- 资产名**不加 @**,只用中文名 +- 清单写:`角色|林直人` `场景|老宅客厅` `道具|梅酒瓶` +- 正文引用:直接写「林直人」「老宅客厅」「梅酒瓶」 +- 同一段多个同类资产:用中文区分「直人杯 / 佐藤杯」 + +**情况二补充 · 无参考库但需要锁定身份时(Seedance 2.5)** + +当目标模型为 2.5、用户既没有标签库也没有参考图,但本段需要锁定角色 / 场景 / 道具身份时: +- 允许先按 Toonflow 资产方法(角色四视图参考板 / 场景主视图 / 道具 2×2 板)生成参考图,再进入 A1.2.1 / A9.2 的 Reference binding; +- 生成的参考图只锁「用户指定或可明确判断」的维度:角色脸 / 发型 / 年龄感 / 体型 / 服装,场景结构与材质,道具主色 / 形态 / 开合结构; +- 参考图不越权控制站位、光线、镜头或额外剧情(同 A1.2.1 的参考图角色分类与冲突处理); +- 仍遵循 A0.1 剧情保真:生成的外观一律视为「设计提案」,不冒充原文事实;不得因此新增剧情事件、道具来源、角色关系或世界规则;参考图中出现原文未提及的人物 / 道具 / 文字,不得自动带入剧情。 + +--- + +### A1.2.1 Seedance 2.5 参考图片绑定(强制) + +当目标模型为 **Seedance 2.5**,且用户提供了角色图、场景图、商品图、道具图、站位图或其他视觉参考时,必须把这些参考图作为正式提示词的一部分绑定到每个相关生成段。 + +**硬规则:** +- 用户提供的真实图片节点 / 参考句柄必须**原样引用**,例如 `{{node/image-xxxx}}`、`@角色名_v2`、`#场景名`;禁止自行改名、简写或编造不存在的 Ref。 +- 每个 2.5 生成段都是**自包含**的:该段需要的参考图片必须在该段自己的 `Reference binding` 中重新列出,不能写“同上”“沿用上一段参考图”。 +- 全片反复使用的角色图 / 商品图,也要在每个实际涉及它们的段中重复绑定。 +- 只绑定本段真正相关的参考图,不把全集所有图片无差别塞进每一段。 +- 一张图片只控制它被用户指定或可明确判断的维度,禁止越权控制其他维度。 + +**参考资产提取与简单标识:** +- 先从本段剧情、镜头、动作与画面内容中自动提取**本段实际涉及且确实需要调用**的真实参考资产;角色图、场景图、商品图、道具图、站位图、动作图等都按实际用途识别。 +- 对每个真实参考只做**简洁身份标识**,说明它对应谁 / 什么 / 哪类用途即可,例如“林直人角色参考”“老宅客厅场景参考”“梅酒瓶道具参考”“本段站位参考”。 +- 不在最终 `Reference binding` 中展开长篇“控制什么 / 不控制什么”说明;参考图的内部作用边界仍按用户明确用途与可明确判断的内容理解,禁止越权把参考图里的额外人物、道具、背景、文字或姿态带入剧情。 +- 用户明确说“仅位置参考 / 仅服装参考 / 仅产品参考”等时,简单标识中保留这个“仅”的用途限定,例如“仅站位参考”“仅服装参考”。 + +**冲突处理:** +- 用户文字设定与参考图冲突时,按 A0.1.1 的事实来源优先级处理;用户最新明确文字修改优先。 +- 多张参考图彼此冲突时,不自行融合成新设定;按用户明确用途分别使用。 +- 参考图中存在用户未提及的额外人物、道具、文字或装饰,不自动引入剧情。 + +**2.5 Reference binding 推荐格式:** +```text +Reference binding: +- {{node/image-xxxx}}:林直人角色参考 +- {{node/image-yyyy}}:老宅客厅场景参考 +- {{node/image-zzzz}}:梅酒瓶道具参考 +- {{node/image-aaaa}}:仅站位参考 +``` + +上例中的节点形式仅表示**格式位置**;运行时必须替换为用户真实提供、且本段实际需要的完整节点 ID / 资产句柄,禁止照抄或编造示例 ID。若本段没有任何真实参考图片 / 资产句柄,则整节省略。 + + +### A1.3 画面文字:后期字幕 vs 实体资产文字 + +必须区分两类文字: + +**A. 后期型文字(默认禁止交给生成模型)** +- 字幕、标题、说明卡、旁白卡、贴纸文案、UI 叠字、水印 +- 默认写成:**无字幕、无额外屏幕文字、无后期文字叠加** +- 这些文字如有需要,默认留给后期剪辑添加 + +**B. 剧情内实体文字 / 产品资产文字(不是字幕)** +- 包装袋原有印刷、招牌、信件、书页、手机界面等 +- 若用户提供了参考图/资产图:优先写“**严格保持参考资产外观,不新增、不改写、不重绘包装文字**”,不要要求模型凭空生成清晰文字 +- 若没有参考资产:除非剧情必须读到具体文字,否则不要把“文字必须清晰可读”设为生成任务 +- 用户明确要求某段必须读出文字时,才逐字锁定;同时提示这是高风险生成项 + +**因此:**“无字幕 / 无额外屏幕文字”与“产品包装上已有文字”不冲突。禁止的是 AI 自行新增或改写文字,不是把真实包装变成无字包装。 + +--- + +## A2. 全量节拍解析与顺序保持(不筛掉剧情) + +A2 的目标不是“挑几个关键点”,而是把原剧情拆成**完整、连续、可计时的叙事节拍**。五类关键节拍只做标记,不作为删减门槛。 + +### A2.1 原子节拍:全部保留,并建立“源剧情账本” + +先按原文顺序拆出原子节拍,常见类型包括: + +| 原子节拍 | 定义 | 示例 | +|---|---|---| +| **对白** | 角色实际说出的完整一句或一组连续句 | 问、答、打断、补充 | +| **动作** | 会改变位置/物件/身体状态的动作 | 拿起、放下、起身、走到门口 | +| **反应** | 因上一事件产生、但不一定说话的反馈 | 停杯、后躲、看手腕、沉默 | +| **信息** | 观众/角色获得新事实 | 看见某物、认出产品、发现伤口 | +| **过渡/留白** | 用户原文明确要求的空间、时间或情绪过渡 | 空镜、环境音、停顿、场景衔接 | + +**所有原子节拍都要登记。** 不属于“高潮/转折”的普通动作也不能因此消失。 + +内部给每个源节拍编号 `E01 / E02 / E03 ...`,至少记录: +- 原文事件是谁做 / 谁说; +- 动作或对白是什么; +- 作用对象 / 道具是什么; +- 与前后事件的原始顺序; +- 用户是否明确给了时间、位置、数量、左右手、道具来源等事实。 + +后续每个 Timeline 中**会改变剧情状态的句子**都必须能映射回一个 `E##`。允许没有 `E##` 的内容仅限:摄影、构图、光线可见结果、已有动作直接对应的物理细节/拟音,以及不改变剧情事实的执行性描述。 + +**若某句话会改变人物、道具、位置、数量、关系、信息或因果,却找不到对应源节拍 → 视为 AI 新增剧情,必须删除。** + +### A2.2 五类关键标签:只标重要性,不改顺序 + +在原子节拍上额外打标签: +- **转折点**:关系 / 权力 / 信息发生反转 +- **情绪峰值**:本段/本场最强情绪泄露 +- **信息增量点**:新信息改变理解 +- **决策点**:角色做出选择并承担后果 +- **沉默点**:铺垫后的有效留白 + +**硬规则:** +- 标签可以重叠,一个节拍可同时属于多类。 +- 没有任何关键标签的节拍仍然保留。 +- **严禁“按情绪曲线排序剧情”。** 情绪曲线只能按原剧情时间顺序标注:低 → 压力 → 峰值 → 释放;它是分析图,不是重新剪辑指令。 + +### A2.3 每个节拍先做时间预算 + +对每个原子节拍估算最低自然时长: + +`节拍最低时长 = 自然对白时间 + 必要停顿 + 必须串行完成的动作/反应时间` + +注意: +- 能自然同时发生的“说话 + 小动作”可以重叠计时; +- 必须先后发生的因果动作必须相加; +- 长对白不能按“长句固定 3–3.5s”粗暴处理;要按实际文本长度、停顿、语气估算自然朗读时间; +- 不确定时宁可留出约 10%–20% 呼吸余量,也不要靠异常快语速硬塞; +- 关键停顿、反应、转身、走位不能被对白完全吞掉。 + +### A2.4 节拍 → 镜头 → 生成段 + +只合并**时间上相邻**的节拍,不跨越中间剧情拼接。**合段只改变承载方式,不改变任何 `E##` 的内容、执行者、对象、顺序或数量。一个源节拍可以跨多个镜头表现,但不能被改写成另一个事件。** + +一段可以容纳多个节拍,但“1–4 个节拍”仅是经验参考,不是硬上限。是否继续合并,以以下条件为准: +1. 合并后总时长 ≤ 模型单段上限; +2. 所有对白都能以自然语速说完; +3. 关键因果动作有完整过程; +4. 至少留得下必要反应与呼吸; +5. 不因塞得过满导致每 1–2 秒就强制切镜; +6. 段末可以形成清晰、可在下一段重新声明的状态。 + +出现以下任一情况,应主动开新段,即使理论上还能塞: +- 对白已经接近时间预算上限; +- 同段需要过多彼此竞争的动作/反应; +- 情绪或目标发生明确阶段切换; +- 场景/时间发生切换; +- 继续合并会破坏段间可独立生成性; +- 需要异常语速、瞬移动作或省略反应才能塞下。 + +### A2.5 长剧情的分批方式 + +**先完成全片段规划,再分批交付。** + +例如一集 180s: +- Seedance 2.0 理论最少 12 段,但实际可因对白密度变成 13、14、15……段; +- 全片段号先固定为 G01、G02、G03……; +- 然后按单批最多 6 段交付:Batch 1 = G01–G06,Batch 2 = G07–G12,Batch 3 = 剩余段; +- Seedance 2.5 同理,单批最多 3 段。 + +**批次边界只影响一次输出多少段,不改变全片顺序、段号和连续性。** + +### A2.6 兜底 + +如果剧情没有明显转折/峰值,也不要强行制造五类关键点。按原文顺序,以“一个可完整执行的动作/对白/反应单元”为节拍继续规划即可。 + +--- + +## A3. 分段与时长预算 + +### A3.0 先区分“理论最少段数”和“实际段数” + +**单段硬上限:** +- Seedance 2.0:每段 ≤ 15s +- Seedance 2.5:每段 ≤ 30s + +当用户给出严格总时长时,可先算理论最少段数: + +```text +理论最少段数 = ⌈总时长 / 单段上限⌉ +``` + +这个公式只回答“至少需要几段”,**不等于实际必须只做这么多段**。 + +示例:55s / Seedance 2.0: +- 理论最少 = 4 段; +- 若对白/动作很轻,可以做 15 + 15 + 15 + 10; +- 若剧情密度高,也可以做 12 + 11 + 11 + 11 + 10 = 55s; +- 只要每段 ≤ 15s、总和符合用户总时长、剧情完整即可。 + +**原则:在“不过密”和“不碎片化”之间取平衡,而不是追求最少段数。** + +### A3.1 实际段数的确定顺序 + +按以下顺序决定: +1. 先完成 A2 的全量节拍与最低时长预算; +2. 从前往后合并相邻节拍; +3. 每接近单段上限时,检查对白、动作、反应是否仍自然; +4. 若不自然,提前截断并开新段; +5. 得到**全片实际段数**; +6. 最后再按 A3.4 分 Batch。 + +不要先决定“必须 4 段”,再倒逼剧情塞进 4 段。 + +### A3.2 对白时长检查(硬门槛) + +每句对白必须在对应镜头/时间窗内真实说得完。 + +执行方式: +- 先按自然口语模拟朗读时间; +- 再加入剧本明确要求的停顿、结巴、喘息、欲言又止; +- 如果说话时还有可并行的小动作,可重叠; +- 如果动作必须等台词前/后完成,则单独占时; +- **禁止用异常快语速解决时长不够;** +- **禁止因为时长不够删词、改词、吞句尾。** + +若用户给出的“严格总时长”与“全部原文台词 + 必须动作”的最低自然时长互相冲突: +- 优先压缩**AI 自己添加的**空镜、无信息停顿、冗余运镜;用户原文明确要求的空镜、停顿、留白不得压缩或删除; +- 仍不够时,在全片总览明确标注“时长约束冲突”; +- 不擅自删台词或改剧情来假装满足。 + +### A3.3 时间轴写法 + +- 每段时间码从 `00:00` 重新开始,便于直接单独投喂模型; +- 全片总览另写该段对应的**全局时间范围**; +- 段内动作时间码不得互相矛盾; +- 并行动作可以重叠时间窗,但要明确“同时”; +- 串行动作必须前后衔接,不能靠同一秒完成多个不可能同时完成的动作。 + +### A3.4 长剧情与单批容量 + +**单批交付上限(容量限制,不是全片上限):** +- Seedance 2.0:单批最多 6 段 +- Seedance 2.5:单批最多 3 段 + +超过时: +- 全片段号保持连续; +- 仅拆成多个 Batch; +- 不重新计算前面段号; +- 不把未交付内容称为“被切掉”,统一称“下一批待交付段”。 + +2–3 分钟剧情完全允许存在 2、3、4 个甚至更多批次。 + +### A3.5 单段镜头密度(推荐,不是硬上限) + +- Seedance 2.0:通常 1–2 个主要镜头;内容极轻时可 3 个,但避免碎剪 +- Seedance 2.5:通常 2–4 个主要镜头 + +如果一段为了装下剧情需要持续高频 HARD CUT,优先拆段,而不是继续塞镜头。 + +### A3.6 通用禁止与文字规则 + +默认禁止: +- 不叠化、不闪白、不甩镜、不做无剧情依据的速度变化; +- 不新增用户未提供的 VO、旁白、台词; +- 不自动添加 BGM、情绪提示音; +- 不增加新角色、新道具、新剧情动作; +- **不生成后期字幕、标题、说明卡、UI 叠字、水印或其他额外屏幕文字。** + +但场景内已有的实体文字 / 产品包装文字按 A1.3: +- 有参考资产时保持参考外观,不新增、不改写、不重绘; +- 不把“包装必须出现”误写成“要求 AI 生成清晰准确文字”。 + +--- + +## A4. 资产与出镜状态规划(按时间轴写) + +A4 是所有模型共用的**内部规划规则**。角色如果在同一段不同时间块/镜头里的出镜状态不同,必须按时间轴分别登记,不能只写一个模糊总状态。 + +**A4 补充 · 外观与光线缺失时的设计提案** + +当剧本 / 用户未提供某角色外观,或某场景光线与环境基调缺失,但本集画面确实需要时: +- 允许按 Toonflow 的视觉设计 / 色彩用光方法(visualDesign / colorAndLight)推导「设计提案」,填入本段身份 + 外观锚点或场景光线; +- 所有提案一律标注「设计提案」,不视为剧情事实;不因此新增剧情、道具来源、角色关系或世界规则; +- 若不影响本段生成,则保持原文抽象层级,不强行补设计(遵循 A0.1.5)。 + +**最终输出映射:** +- Seedance 2.0:仍在每段正文前显式输出“资产标识”。 +- Seedance 2.5:不额外输出重复的“资产标识”大块;A4 信息分别映射进 `Reference binding`、`Immutable locks`、`Timeline` 与 `Preserve`。只有用户明确要求单列资产清单时才额外输出。 + +内部规划可使用下列格式: + +```text +## 资产标识 + +### 涉及角色 + +角色A|出镜状态总览 +- 时间块 / 镜头 1|00:00–00:XX|仅手部 / 实际出镜 / 完全画外……|说话 / 不说话 +- 时间块 / 镜头 2|00:XX–00:XX|…… + +身份 + 外观锚点:只引用用户已给定的信息。 +世界坐标:只写源剧情已确定或生成所必需的中性空间关系。 +画面坐标:按当前机位描述,不改变世界位置事实。 +特殊状态:只登记源剧情已有的脏污 / 伤势 / 湿度 / 持物等状态。 +本段重点表演:把已有剧情动作写得可见,不新增动作。 +同期台词严格保持原文: +「……」 + +角色B|出镜状态总览 +- 时间块 / 镜头 1|00:00–00:XX|完全画外|仅同期对白 +- 时间块 / 镜头 2|00:XX–00:XX|实际出镜|不说话 +…… + +### 涉及场景 +场景A|时间 +(场景锚点 + 摄影机位置/朝向/高度 + 前中后景 + 空间关系) + +### 关键道具 +道具A +(源剧情给定的段首状态 + 源剧情已有的时间轴动作 + 段末状态 + 文字/包装处理方式;不追溯未说明的来源) +``` + +### A4.1 角色出镜状态词表 + +按每个镜头实际可见范围选用: +- 实际出镜并说话 +- 实际出镜但不说话 +- 仅面部局部出镜 +- 仅手部出镜 +- 仅肩后出镜 +- 仅背影出镜 +- 仅脚部出镜 +- 完全画外|仅同期对白 +- 完全画外|无声音 + +**同一角色一段内有两种以上状态 → 必须列时间轴。** + +### A4.2 角色条目必含 6 类信息 +1. 身份 + 外观锚点 +2. 每镜出镜状态时间轴 +3. 世界坐标 + 画面坐标 +4. 特殊状态(本段会变化的:脏污 / 伤口 / 湿度 / 情绪外显等) +5. 本段重点表演 + 3–5 条可见表演要求 +6. 同期台词原文(若有) + +### A4.3 场景条目必含 4 类信息 +1. 场景锚点 +2. 摄影机位置 + 朝向 + 高度 +3. 前景 / 中景 / 后景 +4. 人物/地标空间关系与轴线 + +### A4.4 道具条目必含 4 类信息 +1. 段首绝对位置 / 使用者 / 状态 +2. 本段时间轴动作(谁、何时、怎么动) +3. 段末状态 +4. 禁止项;若有包装文字,注明按 A1.3“保持参考资产,不新增/改写/重绘文字” + +### A4.5 禁止 +- 不复制整套角色档案,只保留本段需要的锚点 +- 不写未出现的资产 +- 不把资产标识写成重复一遍完整剧情 +- 不用“本段实际出镜并说话(但镜头 1 又画外)”这种互相冲突的总括写法 +- 不要求 AI 凭空生成精确包装文字来替代参考资产 + +--- + +## A5. 站位:世界坐标 + 画面坐标(双层 · 自包含) + +**核心前提:每一段生成时,模型看不到任何上一段画面,也不依赖上一段尾帧参考。** + +### A5.1 每段必须自包含的 5 块信息 + +1. **世界坐标 · 轴线与地标**:角色相对门、桌、窗、走廊等真实位置;与机位无关。 +2. **画面坐标 · 当前镜头中的左右/前后/遮挡**:随当前机位重新声明。 +3. **光源方向 · 世界层 + 画面层**:只在同一连续光照条件下继承。 +4. **道具绝对位置与状态**:含本段移动路径。 +5. **本段结束状态**:下一段必须把它重写成“绝对初始状态”,而不是写“延续上一段”。 + +### A5.2 连续场景的状态链 + +同一地点、同一连续时间内: + +`上一段结束状态 → 下一段重新写成绝对初始状态 → 本段动作 → 本段结束状态` + +继承内容包括: +- 角色实际世界位置与身体朝向 +- 道具位置、持有者、数量、液面、污渍/损耗 +- 伤势、服装、湿度、血迹、烟尘等持续状态 +- 主光方向、色温和环境条件 + +### A5.3 人物移动只服从源剧情,不为连续性补动作 + +禁止的是 AI 自己制造无依据的位置变化,也禁止为了“解释位置变化”反过来补剧情。 + +- 原文明确写“起身走到门口” → 必须保留起身、行走、到达的过程,不能瞬移。 +- 原文下一节拍直接写“角色已经站在门口”,但没有写如何过去 → 把“站在门口”作为该节拍的既定初始状态,允许通过 HARD CUT / 新段进入;**不得自行补“起身、走过去”。** +- 原文明确写两人换位 → 按原文过程执行;原文没写换位 → 不得为了构图让二人交换世界位置。 +- 画面左右可以因合法换机位而变化,但世界位置不得无源变化。 + +### A5.4 轴线规则 + +- 同一连续对话默认维持既有 180° 轴线; +- 若用户明确要求反打/越轴,或剧情需要改变轴线,应通过中性机位、过轴移动或建立镜头让空间变化可理解; +- 禁止无提示的跳轴; +- **“不越轴”不等于摄影机永远不能换位置。** + +### A5.5 换场 / 时间跳跃时重新锚定 + +当场景、时间、天气或主要光源发生明确变化: +- 新场景重新建立世界坐标、画面坐标、轴线与光线; +- 不强行继承上一场机位或光线方向; +- 角色服装、伤势、随身道具等是否继承,按剧情时间连续性决定。 + +这样可以支持 2–3 分钟甚至更长的多场景剧情,而不会把第一场的站位规则锁死到整集。 + +--- + +## A6. 表演层 + +### A6.1 情绪 = 行为的副产品 +不写“他很难过”,写他**在做什么**。情绪从动作的微小偏差里泄露。 + +### A6.2 目标指向对象 +只有当用户原剧情已经能明确看出角色目标时,才把它整理为可执行目标,并指向具体的人 / 物 / 任务。**不得为了表演完整性自行推断角色动机、隐藏目的或关系意图。** + +### A6.3 状态优先,但关键因果动作必须保留过程 +关键因果动作(拿取 / 放下 / 倒液体 / 开门 / 换手 / 坐下 / 起身 / 走位)不能瞬移。 + +### A6.4 微表情必须有源剧情依据 + trigger +只有源剧情已经存在对应反应/情绪外显时,才允许写微表情,并写成 `[已有反应的可见微表情] + [原文触发条件]`。**不得因为镜头近就自行添加皱眉、抿嘴、脸红、吞咽、苦笑等新反应。** + +### A6.5 mask + crack(仅源剧情支持时) +- **mask**:只整理用户已经给出的表面状态,不自行赋予角色“伪装”。 +- **crack**:只把用户已有反应具体化为一个可见破绽,不新增反应。 +- 同一镜头不要连续堆多个 crack;源剧情没有 crack 时可以完全不用。 + +### A6.6 表演通道适配(必写) + +| 镜头可见 | 主表演通道 | +|---|---| +| 脸部可见 | 眼神 + 面部极小变化 | +| 仅手可见 | 握力 + 动作节拍 + 触碰 | +| 背影可见 | 重心 + 肩颈 + 呼吸 | +| 脚部可见 | 步态 + 重量转移 | +| 全身远景 | 姿态 + 空间占据 | + +**只写本镜头实际能看见的表演通道。** + +### A6.7 反应与台词的相对时机 +反应可以在对方台词结束前开始,但必须有明确触发词/触发动作;不要机械规定“所有反应都等台词说完”或“所有反应都提前”。 + +### A6.8 克制型爆发 +强情绪可以对**AI 自己添加的表演装饰**做减法,例如少一个额外皱眉、少一次多余叹气;**不得删除、替换或延后用户原剧情动作/对白/反应。** 可以用更轻的幅度、更短的表演事件表达克制,但剧情事件本身必须原样存在。 + +### A6.9 微表情事件数(上限参考,不是最低配额) +- ≤15s 段:通常不超过 1–2 个源剧情已有的微反应 +- 16–30s 段:通常不超过 2–3 个源剧情已有的微反应 + +**0 个完全允许。不得为了达到数量而新增微表情。** 若镜头只见手/背影,则不要硬写面部微表情。 + +--- + +## A7. 运镜与段间衔接 + +### A7.1 情绪曲线 + +```text +低 ──→ 中 ──→ 高 ──→ 释放 +起 压力 峰值 落地 +``` + +情绪曲线按原剧情时间顺序记录,不能拿来重排剧情。 + +### A7.2 情绪位置 → 运镜 +峰值可分为内心、信息反转、外部动作三类;运镜必须服从用户指定风格,不能因为“峰值”自动推近或自动大特写。 + +### A7.3 段间衔接规则(独立生成优先) + +**判断范围:只看“段 N 的末镜”与“段 N+1 的首镜”。** + +镜头属性分三类: +- **拍摄主体**:双人 / 单人 / 局部 / 空镜 / 群体 +- **景别**:全景 / 中景 / 近景 / 特写 / 大特写 +- **角度**:正面 / 侧面 / 背面 / 过肩 / 俯视 / 仰视 + +为避免两个独立生成段在剪辑点看起来像错误续帧,段间衔接默认至少满足一项: +1. 拍摄主体类型不同; +2. 景别差 ≥ 2 档; +3. 拍摄角度差 ≥ 90°。 + +三项都不满足时,只允许调整下一段首镜的**摄影主体/景别/角度/构图**,不得改变该首镜对应的源剧情事件、人物位置事实、动作、道具或对白。 + +**推荐:** +- 双人中景 → 单人/局部特写 +- 双人中景 → 空镜 +- 单人中景 → 双人中景 +- 局部特写 → 双人中景 +- 空镜 → 双人中景 +- 单人侧面中景 → 单人正面特写 + +**高风险:** +- 同一主体 + 同一景别 + 近似角度直接跨段 +- 同一手部动作在两个独立生成段之间硬接 + +注意:不存在“局部 → 局部一律禁止”这类与上面三条件冲突的第二套规则。若主体/景别/角度已经形成足够差异,可用;但仍要保证连续性易读。 + +### A7.4 动作连续剪辑 + +同一个未完成动作的 match-on-action **优先只放在同一生成段内**: +- 镜头 A 尾帧动作进行中; +- HARD CUT; +- 镜头 B 首帧继续完成。 + +跨生成段时,优先让上一段完成动作,下一段从“动作完成后的稳定状态”重新开始,以减少模型间不连续。 + +### A7.5 风格路由表 + +| 风格 | 运镜 | 表演 | 光线 | 声音 | +|---|---|---|---|---| +| **克制型** | 固定为主 / 峰值也可不动 | 情绪从动作偏差泄露 | 自然光 / 低反差 | 环境音主导 | +| **悬疑型** | 稳定机位为主 / 必要时突然反打 | 信息差核心 / 反应可迟半拍 | 硬阴影 / 侧逆光 | 静默可比音乐更有效 | +| **喜剧型** | 固定机位 / 全景定格常有效 | 角色认真演、反差产生喜感 | 均匀正常光 | 环境音主导 | + +用户已有明确风格时,以用户风格为最高优先级。 + +--- + +## A8. 跨段连续性检查(先判定关联,再校验) + +A7.3 是**段间镜头类型切换的唯一规则来源**;A8 只负责人物、道具、环境和持续状态的连续性。**不能把所有相邻生成段都强行串成同一个连续空间。先判断两段是否真的有连续关系,再决定要继承什么。** + +### A8.1 先判定相邻段的连续性关系 + +对每一个 `段 N 末态 → 段 N+1 初态`,内部只标记以下三类之一: + +1. **连续关联**:同一地点、同一连续时间,或源剧情明确是“继续 / 随后 / 承接 / 同一轮对话 / 同一动作链”,下一段初态依赖上一段末态。 +2. **局部状态关联**:场景或时间已变化,但源剧情明确要求某些持续状态继续存在,例如同一件随身道具、服装破损、伤势、湿度、污渍、产品剩余量等。此时只继承这些持续状态,**不强行继承上一场的人物位置、机位或画面左右**。 +3. **无连续关联 / 重新锚定**:场景、时间或叙事单元已经切换,且下一段不依赖上一段的人物位置或道具末态。此时只检查本段自身的起态、动作与末态是否合理;人物位置、机位、光线按本段重新建立。 + +判定依据只来自用户最新明确指令、源剧本和已确认状态。**不得为了“让它连得上”自行制造关联。**若源剧情直接给出下一段新的既定状态但没有过渡过程,按 A0.1.4 把该状态当作新的初态,可用 HARD CUT / 新时间块进入,不补移动或交接前史。 + +### A8.2 人物位置关系校验(连续关联段强制) + +对每个实际存在连续关联的人物,内部维护一条简洁状态链: + +`段首绝对位置/姿态 → 源剧情动作 → 段末绝对位置/姿态 → 下一段绝对初始位置/姿态` + +至少核对: +1. **世界位置**:相对门、桌、窗、走廊、车辆、固定家具等地标的位置是否一致; +2. **人物相对关系**:谁在谁的哪一侧、前后距离、是否隔着桌/门/柜台等关系是否无因改变; +3. **身体状态**:站 / 坐 / 蹲 / 躺、身体朝向、面向对象是否连续; +4. **手部占用**:若人物正在持有关键道具,哪只手/双手是否仍被该动作占用;源文未锁左右手且镜头无需时不要强行指定,但一旦为执行已经明确,就不能在相关镜头里无过程换手; +5. **出镜与画外**:画面裁切或换机位可以让人物从画内变成画外,但这不等于人物在世界空间中消失或换位; +6. **移动依据**:位置发生变化时,必须能对应源剧情 `E##` 中已有的移动/起身/落座/转身等事件,或源剧情直接给出的新初态;没有依据就不能靠镜头切换让人物瞬移。 + +**画面左/右可以因合法换机位而改变,世界位置不能因此改变。**反打时先检查世界坐标,再重算画面坐标;禁止为了保持“永远画面左/右”而偷偷搬人物。 + +### A8.3 道具状态链校验(段内 + 连续跨段强制) + +对剧情关键道具、商品和会参与动作的小物件,内部维护: + +`持有人 / 使用手(若已明确) / 绝对位置 / 可见或被遮挡 / 数量 / 开合状态 / 内容物或液面 / 污渍湿度损耗 / 本段动作 / 段末状态` + +硬规则: +- 一个人在连续镜头里本来拿着一支笔,且没有源剧情中的“放下 / 递出 / 收起 / 掉落 / 离开画面”等事件,下一时刻**不能凭空没了**; +- 若下一镜裁掉了手或道具、被身体/家具遮挡,允许“暂时不可见”,但它的世界状态仍然保持,**不可把“没拍到”理解成“道具消失”**; +- 若持物的同一只手在下一镜仍清楚可见,而没有状态变化事件,则该道具应继续在手中; +- 已放下的道具不能无过程回到手里,已经交给 B 的道具不能下一镜又同时出现在 A 手中; +- 数量、大小、形态、颜色、开合方式、液面、损耗和污渍不能无因复制、恢复或改变; +- 道具进入或离开画面边缘不等于道具状态变化,除非源剧情确实发生了移动。 + +### A8.4 场景与物理环境连续性 + +仅在“连续关联”或“局部状态关联”时检查: +- 门窗开合、椅子/餐具/家具已发生的移动; +- 地面水迹、污渍、破损、烟雾、食物剩余量等持续状态; +- 主光方向、时间、天气以及实际光源开关; +- 镜子、玻璃、反射面中不应出现与当前人物/道具状态矛盾的额外复制; +- 角色与固定环境不能发生无依据穿模、穿墙或越过封闭障碍。 + +### A8.5 跨段修正边界 + +发现连续性问题时,只允许: +- 修正世界坐标/画面坐标的文字冲突; +- 修正出镜/遮挡描述; +- 修正关键道具的持有、可见性和状态锁; +- 调整镜头承载、景别或切点,使已有动作更容易完整呈现; +- 必要时在**已有 `E##` 边界**重新分镜/分段。 + +**禁止为了修连续性新增“把笔放下 / 又拿起来 / 走到另一边 / 重新拿一件”等用户没有写的桥接动作。**若冲突来自源剧情自身,按 A0.1.6 标记“源文本冲突”,不擅自修成另一个故事。 + +**不要写“同上”“延续上一段站位”。需要继承的下一段必须把继承结果重新写成绝对初始状态;无连续关系的段则只检查本段自身。** + +--- + +## A9. 分段提示词模板(按模型路由) + +A9 只定义**最终交付外壳**,不改变 A2–A8 的任何执行逻辑。 + +- Seedance 2.0 → 使用 A9.1 +- Seedance 2.5 → 使用 A9.2 + +如果 A9 的表达方式与 A2–A8、A11–A12 的执行规则发生冲突,以执行规则为准。 + +### A9.1 Seedance 2.0 分段提示词模板(资产标识 + 正式提示词) + +```text +═══════════════════════════════════════════ +G0N|Batch X / 段 N |目标模型:Seedance 2.0 |本段时长:Xs |全局时间:MM:SS–MM:SS +═══════════════════════════════════════════ + +## 资产标识 + +### 涉及角色 +角色名|出镜状态总览 +- 镜头 N-1|00:00–00:XX|仅手部 / 实际出镜 / 完全画外……|说话 / 不说话 +- 镜头 N-2|00:XX–00:XX|…… +(身份 + 外观锚点 + 世界坐标 + 画面坐标 + 特殊状态 + 本段重点表演 + 表演要求 + 同期台词原文) + +### 涉及场景 +场景名|时间 +(场景锚点 + 摄影机位置朝向高度 + 前中后景 + 空间关系) + +### 关键道具 +道具名 +(段首绝对位置 + 时间轴动作 + 段末状态 + 禁止项;包装文字按 A1.3) + +───────────────────────────────────────── +【正式提示词】 + +生成一段总时长严格为 Xs 的真人电影短片。 +(画面风格 / 摄影机总述 / 光源总述) + +## 人物空间关系 +(世界坐标 + 画面坐标 · 双层;禁止只写“延续上一段”) + +## 镜头 N-1|00:00–00:XX|XXs|主体 + 景别 + 角度 +摄影机与构图:…… +首帧锁定:…… +动作时间轴:…… +表演:…… +物理:…… + +## 00:XX|HARD CUT + +## 镜头 N-2|00:XX–00:XX|XXs|主体 + 景别 + 角度 +…… + +## 光线 +(主光源世界方向 + 画面方向 + 曝光逻辑 + 与前段/前镜的连续性) + +## 声音 +(真实环境音 + 同期对白原文;是否有 BGM 服从用户要求) + +## 正向锁 +(人物绝对位置 / 道具持有 / 视线 / 连续状态 / 本镜不该出现的人物) + +## 文字锁 +无字幕、无额外屏幕文字、无后期叠字;实体包装/招牌文字仅保持参考资产,不新增、不改写、不重绘。 +``` + +### A9.2 Seedance 2.5 分段提示词模板(Objective 架构) + +Seedance 2.5 的最终交付采用更紧凑、可直接投喂的结构。**不要在每段前再重复一整套 A4 资产标识。** A4 的信息必须已经被压入 `Reference binding`、`Immutable locks`、`Timeline`、`Preserve`。 + +#### A9.2.0 最终格式硬门(强制) + +当目标模型为 **Seedance 2.5** 时,最终交付只能使用本节 A9.2 的字段结构。除段头信息外,允许的顶层字段仅为: +- `Objective` +- `Reference binding`(仅存在真实参考资产时出现;没有真实参考时整节省略) +- `Immutable locks` +- `Target duration` +- `Timeline` +- `Visual direction` +- `Audio direction` +- `Preserve` +- `Avoid` + +**禁止把任何中间规划稿、其他模型模板或非 A9.2 外壳直接作为 2.5 最终交付。** 除段头信息与上方白名单字段外,2.5 最终正文不得出现任何其他顶层字段、编号式分镜章节或额外分析块。 + +2.5 最终 `Timeline` 必须按 A9.2.1 使用 `【0:00-0:XX】` 时间块 + 连续自然语言。镜头变化如确有需要,只能嵌在对应时间块的自然语言中,不得另立镜头编号体系作为主结构。 + +如果内部草稿或上游输入采用其他结构,必须只把它当作**源材料**而非最终模板:先按 A0–A8/A11 解析,再在交付前重排进 A9.2 白名单字段。只要最终正文出现白名单之外的顶层结构,即判定为格式失败,**不得交付,必须在本轮直接改写为 A9.2**。 + +```text +═══════════════════════════════════════════ +G0N|Batch X / 段 N |目标模型:Seedance 2.5 |本段时长:Xs |全局时间:MM:SS–MM:SS +═══════════════════════════════════════════ + +Objective: +用 1–2 句说明:本段在整集中的位置、时长/画幅/总体质感,以及这一段要完成的核心戏剧目标。不要复述完整 Timeline。 + +Reference binding: +- 自动读取并分析本段剧情、镜头、动作与画面内容,从中提取本段实际涉及且需要调用的参考资产,包括角色图、场景图、商品图、道具图、站位图等。 +- 对提取出的资产进行简单标识,说明该资产对应的对象或用途即可,例如:“男主角色参考”“客栈场景参考”“产品包装参考”“红绳道具参考”。 +- 凡用户已经提供、且本段实际需要使用的真实参考图片或资产句柄,必须逐一列出,并原样保留其节点 ID、资产句柄或其他引用标识,不得改写、缩写或重新编号。 +- 同一参考资产即使在上一段已经使用,只要本段仍然涉及,就必须在本段重新提取并列出;禁止写“同上”“沿用上一段参考”等省略表达。 +- 只提取本段实际涉及的资产,不要把未出现在本段剧情或画面中的资产机械加入。 +- 无需详细解释每张参考图“控制什么 / 不控制什么”,仅做简洁、明确的资产身份标识即可。 +- 如果本段没有任何真实参考图片、节点 ID 或资产句柄,则整节可省略。 +- 严禁根据剧情自行编造 {{node/image-...}}、资产编号、引用标签或不存在的参考素材。 + +Immutable locks: +- 只写会直接影响生成稳定性的不可变条件:角色身份/服装、关键世界位置与左右关系、连续场景的光线逻辑、关键道具状态、商品结构、对白原文与口型、必要的画外锁定等。 +- 不把整段剧情重新抄一遍。 +- 连续场景跨段时,把上一段结束状态改写成本段的绝对初始状态,不写“延续上一段”。 + +Target duration: X seconds + +Timeline: +【0:00-0:XX】用一段连续中文自然描述这一时间块真正看见的画面:必要的场景/站位、当前出镜状态、景别或切镜、动作先后、关键表演反应、同期对白、关键道具变化与必要物理细节。像成片描述一样写,不拆成“摄影机 / 动作 / 表演 / 台词 / 物理”等子标题。 + +【0:XX-0:XX】继续用一段连续自然语言描述后续画面。 + +【0:XX-0:XX】按剧情需要继续;时间块数量不固定。 + +Visual direction: +用 1 个紧凑自然段概括整体摄影质感、光线、色温、景深、人物/商品视觉关系和必要物理质感。只写真正影响这一段的视觉要求。 + +Audio direction: +- 物理拟音 / 环境音:…… +- 对白人声:…… +- 用户明确要求配乐时才写配乐;用户未要求时默认“无背景音乐,仅保留真实同期声与环境音”。 + +Preserve: +用一行或一个短自然段列出必须保留的角色造型、场景锚点、商品结构、关键道具状态、空间关系或动作逻辑。 + +Avoid: +用一行或一个短自然段列出最容易出错且与本段直接相关的问题;不要堆一长串泛化负面词。 +``` + +#### A9.2.1 Timeline 写法(强制) + +`Timeline` 必须参考用户常用的 Seedance 2.5 成品提示词风格:**时间块 + 连续自然语言画面描述**。 + +正确示意: + +```text +Timeline: + +【0:00-0:06】 +在源剧情已经明确的场景中,角色A执行 E01 的原始动作。镜头按需要从建立镜头切到角色A中景;若角色B在该节拍按原文保持画外,就明确写“角色B保持画外”。只补充能直接看见的姿态、接触、物理反馈,不新增拿取、开盖、走位等源剧情没有的事件。 + +【0:06-0:12】 +承接 E02–E03。角色A按原文说出台词,角色B按原文做出既有反应。可以把已有反应写成具体可见动作,但不能把“反应”扩写成新的剧情行为。必要时切近景或局部特写,剧情事件顺序不变。 + +【0:12-0:18】 +承接 E04。若本时间块首帧源剧情已经规定某道具在角色手中,就直接从该状态开始,不追溯或补写道具是如何被拿到手里的。镜头只负责呈现,不负责补前史。 +``` + +**执行要求:** +- 每个时间块通常 1 个自然段,信息够用即可。 +- 时间块数量根据剧情自然决定,不固定为 3 或 4 块。 +- 可以直接写“切男主近景 / 切手部特写 / 回双人中景”,不必额外建立镜头编号。 +- 只写对当前时间块有实际影响的站位、左右、画外状态与连续性,不机械重复 `Immutable locks`。 +- 角色不应出现时,简短写“女主保持画外,不自动补入镜头”即可。 +- 台词直接嵌在对应动作发生的位置,不在 Timeline 后再次重复一遍。 +- 物理细节只写和当前动作直接相关的,如液体晃动、衣料接触、道具表面湿润、物体重量、碰撞反馈。 +- 每个时间块优先保持一个清晰动作链,不为追求信息完整而把每秒塞满。 +- **描述重点是“这一刻成片实际看见什么”,不是重新解释规则。** +- Timeline 中每一个会改变人物/道具/位置/数量/关系/信息的动作,都必须来自 A2 的源节拍 `E##`。 +- 不为了“更顺”“更完整”“更有因果”补源剧情没有的拿取、开合、抽取、递交、起身、走位、回头、使用次数、道具消耗等行为。 +- 若源剧情从一个既定状态直接开始,就直接写该状态;不要追问或补拍它之前怎么发生。 +- 原文使用“父母 / 家长 / 成人 / 某人”等泛称时,Timeline 保持同样泛称,除非用户最新明确指令已经指定具体人物。 + +#### A9.2.2 Reference binding(2.5 真实参考资产硬规则) + +- 自动读取本段剧情、镜头、动作与画面内容,只提取**本段实际涉及且需要调用**的真实角色图、场景图、商品图、道具图、站位图、动作图等参考资产。 +- 只引用用户真实提供的参考节点、图片标签或资产句柄,并**原样保留完整节点 / 句柄**;禁止改名、缩写、重新编号或根据剧情编造不存在的引用。 +- 每个真实参考单独列一行,采用“**真实节点 / 句柄:简洁资产标识**”写法;标识只说明它对应的对象或用途,例如“男主角色参考”“客栈场景参考”“产品包装参考”“红绳道具参考”。 +- 不要求逐张展开“控制什么 / 不控制什么”的长说明;但内部仍须遵守用户明确用途,不得让角色图越权改变站位、让站位图覆盖人物身份、让场景图额外带入人物或道具。 +- 用户明确说“仅位置参考 / 仅服装参考 / 仅产品参考”等时,简洁标识中必须保留用途限定,例如“仅站位参考”“仅服装参考”。 +- **每段自包含**:上一段已经使用过的参考,本段仍需要时必须再次列出;禁止写“同上”“沿用上一段参考”。 +- 只列本段实际需要的资产,不把全集参考库机械塞进每一段。 +- 没有真实参考时,省略整个 `Reference binding`;禁止伪造 `{{Ref}}`、`{{node/image-...}}`、资产编号或不存在的资产名。 + +#### A9.2.3 Immutable locks + +只保留**不可漂移**的信息,例如: +- 男主白衣、女主红衣; +- 女主在桌南侧/画面左,男主在桌北侧/画面右; +- 商品蓝色翻盖结构; +- 某角色在某时间块保持画外; +- 原文对白不改词、不吞字; +- 连续场景灯光方向与道具状态不重置。 + +不要把所有动作都写成 lock;会在 Timeline 内发生变化的动作应留在 Timeline。 + +#### A9.2.4 Audio direction + +- 用户明确要求 BGM / 配乐 → 按用户要求写。 +- 用户未要求 → 默认无 BGM、无情绪提示音,只保留真实环境音、物理拟音与同期对白。 +- 不因示例里曾出现配乐,就把配乐变成 2.5 的默认行为。 + +#### A9.2.5 Preserve / Avoid + +`Preserve` 与 `Avoid` 必须服务当前段执行: +- `Preserve` 写真正不能漂移的造型、空间、商品、道具、动作逻辑; +- `Avoid` 写当前段最可能发生的生成错误; +- 两者都保持短,不写几十个泛化标签。 + +--- + +## A10. 全片输出结构 + +长剧情必须同时区分“全片规划”和“当前批次交付”。全片总览继续用中文;每个生成段的正文则按目标模型路由到 A9.1 或 A9.2。 + +```text +═══════════════════════════════════════════ +全片总览 +═══════════════════════════════════════════ +· 目标模型:Seedance 2.X +· 用户目标总时长:(严格 / 参考 / 未指定) +· 单段硬上限:15s / 30s +· 理论最少段数:⌈总时长 / 单段上限⌉(仅下限) +· 全片实际段数:X 段(按内容密度确定) +· 全片段表:G01 … GXX(含每段时长 + 全局时间范围 + 核心节拍) +· 批次方案:Batch 1 = G01–G0X;Batch 2 = …… +· 当前输出批次:Batch X +· 下一批待交付段:GXX–GXX(如无则写“无”) +· 资产总表 +· 参考图片总表(仅 2.5 且用户实际提供参考图时):原样列出每个图片节点 / 资产句柄 + 用途;用于全片规划,不替代各段自己的 Reference binding +· 场景/时间变化表 +· 各连续场景世界轴线 +· 按原时间顺序的情绪曲线 +· 关键节拍标签 +· 风格 +· 运镜节奏图谱 +· 时长约束冲突(如无写“无”) +· 源剧情保真状态:应为“通过”;如源文本自身有空缺/冲突,只标注问题,不自行补剧情 + +───────────────────────────────────────── +若目标模型为 Seedance 2.0: +[G01] 使用 A9.1“资产标识 + 正式提示词” +[G02] 使用 A9.1 +…… + +若目标模型为 Seedance 2.5: +[G01] 直接使用 A9.2 Objective 架构,不再额外重复一整块资产标识 +[G02] 使用 A9.2 +…… +───────────────────────────────────────── +``` + +**长集规则:**即使当前只交付 Batch 1,也应先规划后续全局段以及当前批次在全片中的位置,避免每批重新切段导致前后逻辑漂移。 + +**2.5 简洁性规则:**全片总览负责解释“为什么这样分”;单段提示词负责“这一段具体怎么生成”。不要把总览内容重复塞进每一个 2.5 `Objective` 或 `Timeline`。 + +--- + +## A11. 结构校验(A12 前的唯一结构修正阶段) + +A11 负责“能不能生成、剧情有没有被挤坏”的结构问题;A12 只做文字和表现层抛光。 + +### A11.1 校验清单 +- [ ] 已建立 `E01 / E02 / E03...` 源剧情账本,并以用户最新明确指令 / 原始剧情为事实源? +- [ ] 最终 Timeline 中每个改变剧情状态的事件都能映射到某个 `E##`,没有无来源的新动作? +- [ ] 没有新增、删除、替换、改归属或改顺序任何用户剧情事件? +- [ ] 没有把“父母 / 家长 / 成人”等模糊角色擅自具体化为爸爸/妈妈/第二人? +- [ ] 没有为了连续性追溯道具来源、补开盖/抽取/拿取/走位等前史? +- [ ] 已按原文顺序登记全部原子节拍,没有只保留五类关键点? +- [ ] 情绪曲线没有被用于重排剧情? +- [ ] 理论最少段数只作为下限,没有强迫实际段数等于它? +- [ ] 每段 ≤ 模型单段硬上限? +- [ ] 全片各段时长总和符合用户严格总时长;若无法同时满足,是否显式标注冲突? +- [ ] 所有对白在所属时间窗内可按自然语速完整说完? +- [ ] 串行动作、反应与必要停顿有真实时间,不靠瞬移或异常快语速? +- [ ] 长剧情是否先有完整全片段表,再按 Batch 容量交付? +- [ ] A4 角色出镜状态是否按时间轴规划,且与最终正文一致? +- [ ] 是否已对每一个相邻生成段判定“连续关联 / 局部状态关联 / 无连续关联”,没有把无关段强行继承? +- [ ] 所有连续关联段的人物世界位置、相对关系、姿态、朝向和手部占用是否能从上一段末态无矛盾地进入下一段初态? +- [ ] 所有关键道具是否完成“持有人 / 位置 / 数量 / 状态 / 可见性”链条检查,没有无来源的消失、复制、换手、恢复或瞬移? +- [ ] 场景内已改变的门窗、家具、污渍、液面、破损、天气和光源状态是否在相关段中合理继承? +- [ ] 是否已做生成稳定性预检,避免把高风险人体/手部/道具交互、复杂运镜、遮挡和多重参考冲突同时塞进一个镜头? +- [ ] 若目标模型为 2.0,是否使用 A9.1“资产标识 + 正式提示词”? +- [ ] 若目标模型为 2.5,是否使用 A9.2 的 `Objective / Reference binding / Immutable locks / Target duration / Timeline / Visual direction / Audio direction / Preserve / Avoid` 架构? +- [ ] 若目标模型为 2.5,最终正文是否通过 A9.2.0 格式硬门:除段头与 A9.2 白名单字段外,没有任何其他顶层结构或额外分析块? +- [ ] 若目标模型为 2.5,`Timeline` 是否只用时间块 + 连续自然语言,没有另立镜头编号体系作为主组织结构? +- [ ] 若用户提供了参考图片,2.5 每个相关段是否都在自己的 `Reference binding` 中原样列出了需要的真实图片节点 / 资产句柄? +- [ ] `Reference binding` 是否只列本段真实需要的参考资产,并采用“真实节点 / 句柄 + 简洁资产标识”;用户明确的“仅站位 / 仅服装 / 仅产品”等用途限定是否保留? +- [ ] 是否避免用“同上 / 沿用上一段参考图”代替本段重新绑定? +- [ ] 2.5 `Timeline` 是否为“时间块 + 连续自然语言”,没有退化成一堆摄影机/动作/表演小标题? +- [ ] 2.5 是否避免把 A4 资产清单整块重复输出,而是把必要信息压进对应字段? +- [ ] 每段都是自包含世界坐标 + 画面坐标,而非“同上/延续上一段”? +- [ ] 连续场景状态继承、换场重新锚定是否正确? +- [ ] 段间衔接满足 A7.3? +- [ ] 动作连续剪辑是否尽量留在同一生成段? +- [ ] 对白原文照抄? +- [ ] 后期字幕/叠字是否没有交给生成模型?实体资产文字是否按 A1.3 处理? +- [ ] 无参考库时若生成参考图,是否只作 Reference binding 使用、外观标为设计提案、且未越权控制站位/光线/剧情?(A1.2 情况二补充) + +### A11.2 有限修正机制(防止死循环) + +第一次检查后若发现问题: +1. 把所有失败项一次性汇总; +2. **只做一轮集中结构修正**;结构修正只允许调整分段边界、镜头承载、时间预算、摄影表达和锁定信息,**不得修改任何 `E##` 的事件内容、执行者、对象、数量、顺序或台词**; +3. 修正后只重新核对受影响项和它们的直接连续性; +4. 然后进入 A11.3 剧情保真审计与 A11.4 生成稳定性预检;全部通过后进入 A12。 + +**禁止 A11 ↔ A12 来回递归。** + +若一轮集中修正后仍存在“用户要求彼此不可同时满足”的硬冲突(例如严格 30s 但原文对白自然朗读已超过 30s),保留用户原文并在“全片总览|时长约束冲突”中明确说明,不继续无限重算。 + +### A11.3 剧情保真审计(进入 A12 前必做) + +做一次单向比对,不向用户展示内部账本: + +1. 从源剧情账本按顺序读取 `E01 → E02 → ...`; +2. 确认每个 `E##` 都在最终某个生成段中出现,且执行者 / 对象 / 台词 / 顺序没有变化; +3. 反向扫描最终 Timeline 中所有会改变世界状态的动作;若找不到源 `E##`,删除该 AI 新增动作; +4. 摄影、构图、景别、对焦、已有动作的直接物理结果与拟音可以无 `E##`,但不得产生新的剧情事实; +5. 若删除 AI 新增动作后出现“状态从哪里来的”疑问,按 A0.1.4 处理:直接把用户给出的状态作为该节拍初始状态,不补前史; +6. 若源文本自身存在缺口或矛盾,保留缺口/矛盾并在全片总览标注,不自行编桥。 + +**审计目标不是让剧情更顺,而是确认最终提示词与用户剧情是同一件事。** + +### A11.4 生成稳定性预检(降低画面崩坏概率 · 强制) + +本节只降低生成风险,**不能承诺模型输出绝对不崩**。目标是提前消除最容易导致人物变形、手部错误、道具消失/复制、画面结构融化和身份漂移的提示词负担;不得以“稳定”为理由删剧情或改事件。 + +#### A11.4.1 高风险触发项 + +任一镜头出现以下情况时,标记为高风险并主动降复杂度: +- 3 个及以上主体同时大幅移动、互相遮挡或发生接触; +- 双手/多人同时操作小道具、交接、系扣、倒液体、擦拭等精细接触,同时还要求复杂运镜; +- 人物快速转身、蹲起、落地、穿脱、多人换位等大幅身体动作与近景手部细节同时发生; +- 镜子、玻璃、强反射、透明容器、多个影子等容易复制人物/肢体/道具的构图; +- 产品包装、小字、手指、液体或机械结构既要近距离准确,又要高速移动/旋转; +- 同一镜头同时要求极浅景深、强遮挡、快速运镜、精细接触和多角色表演; +- 本段引用过多参考图,且多张图对同一角色、服装、场景结构或产品形态存在潜在冲突; +- 提示词自身存在互斥要求,例如“人物完全固定”同时“快速换位”,“手始终握笔”同时“同镜空手完成另一动作”。 + +#### A11.4.2 降风险顺序 + +遇到高风险时,按以下顺序处理,直到提示词不再过载: +1. **删掉无关控制,不删剧情。** 删除不影响本镜的镜头术语、泛化负面词、无关材质细节和无用参考;只保留当前镜真正需要的锁。 +2. **摄影机先简化。** 精细手部/道具接触时优先固定或单一平稳运动;不在同一时刻叠加推拉、环绕、快摇、强移焦。 +3. **让关键接触完整可见。** 交接、拿取、擦拭、开合等动作,选择能同时看见相关手部和道具的景别,避免在最关键接触点被画框边缘、身体或前景完全遮住。 +4. **降低景深冲突。** 关键手部、道具与接触面必须都可辨时,不使用会把其中一方完全虚化的极浅景深。 +5. **复杂动作与复杂摄影不要抢同一时刻。** 若源剧情允许拆镜,就在已有 `E##` 边界把不同复杂交互分镜承载;若源剧情明确要求同时发生,则保持同时,但降低摄影机运动、背景动态与无关表演复杂度。 +6. **参考图只留本段真正需要的。** 同一对象多张参考若用途不同,明确各自范围;互相冲突时按 A1.2.1 处理,不让模型自行融合。 +7. **对高风险段增加定向 Avoid,而不是全片堆负面词。** 可按本镜实际风险加入:不出现额外手臂/手指、肢体融合、脸部身份漂移、道具复制/消失、物件穿手/穿桌、人体穿模、几何融化、镜像多出人物等;无此风险则不机械添加。 +8. **仍然过载时才重分镜/重分段。** 只能使用已有源节拍边界,不删、不新增、不改顺序、不改变同时发生关系。 + +#### A11.4.3 稳定性通过标准 + +进入 A12 前确认: +- 每镜有清楚的主要观看任务; +- 人物数量、肢体接触、道具数量和动作因果可被当前景别完整看清; +- 摄影机没有互相矛盾的运动命令; +- 不存在会诱发重复主体的无必要镜像/反射要求; +- Reference binding 不互相争夺同一维度; +- 关键人物身份、服装、商品结构和关键道具都已在适当字段锁定; +- 高风险段的 `Avoid` 只针对真实风险,不是几十项泛化负面词。 + +--- + +## A12. 交付前优化(最终抛光 · 单次执行) + +**A12 只执行一次。** 它不是第二轮分镜,也不负责重新算段数、重切节拍或回滚 A11。 + +优化不是重写,而是在既有结构上检查 A12.1–A12.18 的表现与可执行性。发现普通表达问题直接修;发现结构级硬冲突按 A12.19 处理,不递归返回。 + +### A12.1 首帧锁定 +对每个镜头的首帧,按“适用项”写清: +- 本镜是否有人物;若无人,明确“空镜,无人物” +- 人物站 / 坐 / 蹲 / 躺 +- 角色画面左右 +- 人物相对距离 +- 身体朝向 +- 视线初始落点(源剧情有明确关注对象时照写;没有时只用不承载新信息的中性落点,不推断新兴趣/敌意/暧昧) +- 手里拿什么 +- 关键道具摆在哪里 +- 摄影机距离和高度 +- 前景 / 中景 / 后景 + +不适用的项不要硬编。 + +### A12.2 出镜锁定按镜头执行 +以 A4 的内部时间轴状态规划为准;2.5 即使不单列资产标识,也必须在 Timeline / Immutable locks 中体现同样的出镜约束。 + +本镜不该出现的角色,显式写: +- 完全不出镜; +- 不出现脸 / 身体 / 肩膀 / 手 / 倒影 / 影子 / 焦外人形(按需要选择); +- 若仅画外同期对白,要明确“只有声音”。 + +特别是主观镜头、局部镜头、肩后镜头、单人镜头,避免模型自动补出另一个角色。 + +### A12.3 光学:写可见结果,不依赖镜头型号 +- ❌ “85mm f/1.4” +- ✅ “短焦肖像感视角,面部透视自然,背景轻度虚化” + +镜头型号可以辅助,但重点是最终画面结果。 + +### A12.4 摄影机矛盾检查 +每镜只保留一个主要摄影机运动逻辑。 +- ❌ “镜头完全固定,同时缓慢横移” +- ✅ “摄影机固定,仅做一次极慢移焦” + +### A12.5 回避摄影(仅适用于克制/含蓄风格) +用户风格属于克制、含蓄时,可优先: +- 手部特写 / 杯子 / 红绳 / 地板边缘 +- 肩后 / 柱子遮挡 / 虚焦前景 +- 双人中景 / 固定远景 + +不要把这条强行应用到动作片、强喜剧、产品实验等其他风格。 + +### A12.6 表演:行为而非抽象情绪 +- ❌ “他很难过” +- ✅ “他原本正在举杯,动作停约 0.4 秒,随后继续喝” + +优先把**源剧情已经存在的反应**写成可见动作。视线停顿 / 手指收紧 / 杯子停顿 / 嘴唇张开又合上 / 呼吸变化 / 重心变化只能在与源剧情反应一致时使用,不能作为 AI 自行添加的新表演事件。 + +### A12.7 微表情密度 +每角色每镜通常 0–2 个明确微表情事件。镜头看不到脸时,不写脸部反应。 + +### A12.8 眼神目标具体化 +只有源剧情已经写明角色在看某人/某物/某方向,才把目标写具体。若原文没有关注对象,不得自行选择一个具有剧情含义的目标。 + +自然行为顺序可写成“眼睛先动 → 头部后跟”,但只用于表现原文已有的看向动作,不新增一次看向。 + +### A12.9 双人动作避免机械同步 +若源剧情本身包含两个可并行、但未锁定精确同步的已有动作,可以在不改变事件顺序与因果的前提下做轻微节奏错开。**不得为了“自然”给任一角色新增动作、延后关键事件或改变原本明确的同时发生关系。** + +### A12.10 动作因果链 +优先把**已有源节拍**组织成清楚的因果链;如果用户原文确实包含多个动作,就全部保留,只在镜头承载上分配,不得为了“每镜一个核心动作”删掉任何源事件。AI 自己添加的装饰动作应删除。 + +### A12.11 道具连续性(段内 + 相关跨段) + +对每个关键道具至少检查:**持有人、使用手(若已明确)、绝对位置、可见/遮挡状态、数量、朝向、开合、液面/内容物、损耗、污渍/湿度、段末去向**。 + +- 段内按“初态 → 源剧情动作 → 末态”逐时间块扫描;连续关联段再按 A8.3 比较上一段末态与下一段初态。 +- 一支笔若仍由人物握持,且没有源 `E##` 对应的放下、递交、收起或掉落,下一时刻不能凭空消失。 +- 下一镜因裁切或遮挡没有拍到道具,不等于道具已经消失;世界状态继续保留。 +- 若同一只手仍清楚可见而道具无来源地没了,视为连续性失败;若手和道具都在画外,只记录“仍由该人物持有/仍处于原位置”,不要凭空改变状态。 +- 已放下的道具不能无过程回手;已经交给 B 的物件不能同时又出现在 A 手里;数量不能无因增减。 +- 源文未指定左右手且镜头不需要时不强行锁手;一旦提示词为执行明确了某只手,则相关连续镜头中不得无过程换手。 + +禁止无因恢复或重置:喝过的杯子突然满、擦开的污渍突然复原、打开的门无动作闭合、破损道具自动完好、已消耗物件恢复数量。 + +### A12.12 物理真实性 +重点检查液体惯性、衣料褶皱、手与道具接触、物体重量、桌面震动、碰撞反馈、玻璃折射/反射等。 + +### A12.13 光线一致性 +同一连续场景保持主光方向、色温与曝光逻辑。换场/时间跳跃则按 A5.5 重新建立,不强行继承。 + +禁止仅因剧情重要就突然加轮廓光、增强眼神光或改变曝光,除非用户风格明确要求。 + +### A12.14 声音 +默认只保留真实同期对白和环境/动作声。BGM、配乐、情绪音效是否存在,以用户要求为准;用户未要求则不自动添加,默认无背景音乐。 + +### A12.15 对白原文 + 时长 +用户提供对白必须: +- 原文照抄 +- 不改词 / 不换句式 / 不加语气词 / 不重复 / 不即兴 + +A12 **不得**通过“加快语速”解决对白塞不下的问题;这类问题应已在 A11 处理。A12 只微调不改变结构的停顿措辞说明。 + +### A12.16 正向锁优先 +优先写可执行状态: +- “角色 A 本镜始终位于画面左侧” +- “杯子由角色 A 右手持有” +- “角色 B 本镜完全画外” + +再补必要禁止项。 + +### A12.17 文字锁 +默认写: +- 无字幕 +- 无额外屏幕文字 +- 无后期标题/说明卡/UI 叠字/水印 + +若镜头含产品包装、招牌、书信等实体资产文字: +- 有参考图 → 保持参考资产,不新增、不改写、不重绘文字; +- 不要求模型额外生成“清晰准确的新文字”; +- 用户明确要求可读文字时才逐字锁定。 + +### A12.17.1 参考图片绑定完整性(Seedance 2.5) +当用户提供参考图片时,A12 只检查绑定是否完整、用途是否清楚,不得在优化阶段更换、删除、合并或自行新增参考图。 + +- 每个相关段都必须保留该段需要的真实参考节点 / 资产句柄; +- 不得因“上一段已经绑定”而从下一段删除; +- 不得把“仅站位参考”扩大为人物外观参考; +- 不得把角色参考图中的背景、陌生人物或额外道具带入剧情; +- 不得把商品参考图里的复杂文字改写成新的包装文案。 + +### A12.18 统一限制按需添加 +可按当前项目选用: +- 不增加人物 / 道具 / 对白 / 剧情动作 +- 不无故越轴 / 不无过程交换人物位置 +- 不做 MV 式快剪 +- 不做无风格依据的广告式补光 / 磨皮 +- 不夸张景深 / 不使用不自然慢动作 + +**不要机械粘贴与当前镜头无关的限制。** + +### A12.18.1 最终连续性与穿帮风险审计(交付前强制) + +A12 完成文字抛光后、最终输出前,再做一次**单向审计**,不返回 A11、不触发第二轮 A12: + +1. **建立每段起态 / 末态快照**:人物世界位置、姿态、朝向、出镜状态、手部占用;关键道具持有人/位置/数量/状态;场景门窗/家具/污渍/光源等持续状态。 +2. **只比较 A8 判定为“连续关联 / 局部状态关联”的段对**。无连续关系的相邻段不强行比较人物位置,只检查本段自身是否合理。 +3. **人物穿帮检查**:无来源瞬移、无来源换边、无过程站↔坐、同一人物在同一世界位置被重复成两人、画内/画外与机位描述互相矛盾。 +4. **道具穿帮检查**:无来源消失、复制、换手、回手、数量变化、开合重置、液面/污渍/破损恢复;特别检查“上一秒还拿着,下一秒同一只手清楚可见却空了”的情况。 +5. **空间穿帮检查**:固定家具移位、门窗状态跳变、人物穿墙/穿桌、物件穿手、角色与桌椅尺度突变、反射/镜像中多出不存在的人物或道具。 +6. **生成崩坏风险检查**:高风险镜头是否已经按 A11.4 降低运镜、遮挡、景深、并发接触与参考冲突;是否针对本镜真实风险加入必要的定向 Avoid。 +7. **剧情保真复核**:所有修正只能改变摄影表达、锁定信息、遮挡/可见性描述和镜头承载;不能新增“放下笔”“重新拿笔”“走回原位”等桥接动作来掩盖穿帮。 + +若发现的是 AI 草稿自身矛盾,直接在本次 A12 中修正成与已确认状态一致;若发现源剧情本身矛盾,保留原文并在全片总览标注“源文本冲突”。 + +**本节是提示词侧的穿帮风险审计,不等于真实生成视频已经无穿帮。真实视频是否出现多手多指、肢体融合、人物变脸、道具闪现/消失、穿模、镜像错误等,必须在媒体实际可读取时另做结果验收。** + +### A12.19 优化边界与终止条件(防死循环) + +A12 不允许改变: +- 用户原文台词 +- **任何源剧情 `E##` 的动作、反应、事件数量、执行者、承受者、道具、信息与因果关系** +- **用户原文中的模糊身份层级(如“父母/家长/成人”不得擅自具体化)** +- 剧情核心意图 +- 已在 A11 确认的节拍顺序 +- 全片实际段数 / 各段时长 +- 全局段号 / Batch 规划 +- 关键资产身份 +- 已确认的世界坐标逻辑 + +A12 只允许: +- 把描述写得更具体可执行 +- 补齐首帧/出镜锁 +- 减少过度表演 +- 补物理、光线、声音与连续性表述 +- 清理互相矛盾的措辞 + +**冲突来源区分:** +- 若冲突是 AI 草稿自己造成的表述错误(如同一镜同时写左手/右手持杯)→ 在 A12 直接修成与 A11 已确认状态一致; +- 若冲突来自用户源剧本本身(如同一时刻明确写了两个互斥位置)→ 不擅自改剧情,在全片总览标注“源文本冲突”。 + +**终止规则:**A12 完成一次后只做最终勾选,不再返回 A11,不再触发第二次 A12。 + +最终勾选: +- [ ] 所有源剧情 `E##` 均出现且顺序、执行者、对象、台词未改变 +- [ ] Timeline 中不存在无源 `E##` 的新增剧情动作 +- [ ] 没有补前史、补道具来源、擅自具体化模糊角色 +- [ ] 首帧适用项齐全 +- [ ] 每镜出镜状态与 A4 一致 +- [ ] 无摄影机矛盾 +- [ ] 表演可见且不过载 +- [ ] 眼神目标具体 +- [ ] 道具 / 物理 / 光线连续 +- [ ] 所有相邻段已按 A8 判定关联类型;有连续关系的段人物位置/姿态/朝向一致,无关系的段没有被错误强锁 +- [ ] 关键道具不存在无来源的消失、复制、换手、回手、数量变化或状态重置;画面裁切/遮挡没有被误判成世界状态变化 +- [ ] 已完成空间/门窗/家具/反射/镜像/穿模等穿帮风险审计 +- [ ] 高风险镜头已通过 A11.4 生成稳定性预检并做定向降复杂度 +- [ ] 对白原文无改动 +- [ ] 无 AI 新增字幕/叠字 +- [ ] 实体文字按参考资产处理 +- [ ] 无结构回滚 / 无循环 +- [ ] 若目标模型为 2.5,最终交付只包含 A9.2 允许字段,且不存在任何旧式三段壳、2.0 外壳或镜头编号主结构 +- [ ] 生成参考图(若有)只用于 Reference binding,外观标为设计提案,未越权引入站位/光线/剧情(A1.2 情况二补充) + +**勾选完成 → 输出最终版。** + +--- + +═══════════════════════════════════════════ + +--- + +## 在画布上推进 + +实际制作默认在当前画布呈现,但**Seedance 路由优先于画布发现与配置**:若已有可执行剧本/时间轴且当前目标是视频制作、生成、继续或修订,必须先按本文件 PART A 完成对应 Seedance 提示词规划/定稿,再进入[画布执行](references/canvasExecution.md)按需读取画布概览、目标节点、局部连接、模型配置、端口和节点函数。不得因为需要 `getConfig`、选择分辨率/画幅/模式或宿主弹出配置询问而跳过 PART A。只有尚未进入视频制作阶段时,才按普通流程先发现画布。“先完成剧本和资产方案”只限制阶段,仍使用文本节点,不触发媒体生成;仅当用户明确要对话文字、咨询或不要操作画布时省略节点操作。工作区采用宿主当前项目;未打开画布时说明具体条件,继续可完成的文字部分。 + +| 到达阶段 | 当前成果 | 需要读取 | +|---|---|---| +| 1. 内容与范围 | 原文或剧本文本节点;必要的制作简报 | [输入与剧本](references/sourceAndScript.md) | +| 2. 资产 | 当前范围的角色、场景、道具清单及实际采用图片 | [资产制作](references/assets.md) | +| 3. Seedance 提示词 | 覆盖本次剧情的全片规划、分段与正式提示词;**只执行本文件内嵌 PART A**(2.0 走 A9.1、2.5 走 A9.2),本阶段不读取 storyboard 或 methods | **仅本文件内嵌 PART A** | +| 4. 生成与采用 | 当前片段生成节点、真实输出、反馈与采用记录 | [画布执行](references/canvasExecution.md)、[状态与交付](references/stateAndDelivery.md) | +| 5. 交付或继续 | 有效剧本、素材和片段索引,实际完成范围与下一步 | [状态与交付](references/stateAndDelivery.md) | + +只创建当前已到达阶段需要的节点。一个剧情片段可以有多个镜头,默认对应一份完整提示词、一个视频生成节点;不默认给每个镜头先生成关键帧。连线传递实际素材,不代表审批或自动调度。 + +剧情制作中的正式资产依据本次已确认的完整剧本;单独设计角色、场景或道具时,以用户确认的设计需求和已有素材为依据,不要求补写剧本。用户同时要求剧本与资产方案时,可同轮提取资产清单和设计草案,标明所依赖的待确认剧本,不把草案当作生成授权。角色不必先有完整生平,只有声音的角色不生成无用途肖像。风格、表演、动作和连续性直接落实到制作资料与镜头,不强制各写独立报告;没有打斗、特殊道具等需求时不造空文档。 + +## 按当前创作问题读取方法 + +执行规则决定怎样在 Toonflow 保存、生成和继续;以下方法**只用于 Seedance 提示词阶段之前的创作/改编/资产设计,或 Seedance 成品之后的媒体执行**。进入 Seedance 提示词硬隔离后,不读取本节任何创作方法;提示词定稿前后不得让这些方法覆盖 PART A。 + +| 正在解决的问题 | 阅读方法 | 将判断落实到哪里 | +|---|---|---| +| 把已确认剧本拆成 Seedance 2.0/2.5 分段提示词(节拍、时长、站位、表演、运镜、连续性、模板) | **本文件内嵌「SEEDANCE EPISODE DIRECTOR · PART A」** | 分段规划、每段正式提示词(A9.1/A9.2)、剧情保真锁 | +| 创意、人物驱动、因果、大纲或续作 | [故事开发](references/methods/storyDevelopment.md) | 行动命题、事件链、选择与结果 | +| 小说视听化、场景、心理、对白与时长 | [剧本改编](references/methods/screenAdaptation.md) | 场次、完整行动和声音、改编提案与估时 | +| 外观、空间、道具结构及持续状态 | [视觉设计](references/methods/visualDesign.md) | 资产锚点、空间母版与变体 | +| 风格、材质本色、受光与调色 | [色彩与用光](references/methods/colorAndLight.md) | 共享视觉依据、场景光线和片段约束 | +| 非定稿阶段的剧情创作/改编 | 仅使用上面的故事开发与剧本改编方法 | 形成可确认的剧本;一旦定稿并进入 Seedance,立即停止使用这些方法 | +| Seedance 成品提示词之后的媒体执行与验收 | [画布执行](references/canvasExecution.md)、[状态与交付](references/stateAndDelivery.md) | 只执行已定稿 prompt、连接真实参考、核验真实结果;不得另写提示词规则 | + +这些方法的结论只进入**Seedance 之前**的剧本/资产设计成果;进入 Seedance 提示词硬隔离后,任何方法结论都不能直接写入或改写最终 prompt,必须由 PART A 从已确认输入重新处理。方法示例、类型节奏和风格候选不能自动变成本项目事实。 + +仅当交接与合并的成本低于独立分析工作量时,可用 `subAgent` 分担**Seedance 之前**的长篇原文事实提取或资料整理。**Seedance 提示词硬隔离阶段禁止让 subAgent 独立起草、重写或优化分段 prompt**;A0–A12 必须由同一主执行链统一完成,避免子任务带入第二套镜头/表演/连续性规则。 + +少量文字、资产盘点、连线和布局直接完成,不安排固定岗位或额外审查轮次。分工限于独立的内容处理,不改变后续确认、生成和采用流程;依赖前段真实结果的后段生成仍等待该结果。 + +## 确认与执行 + +- 展示实质阶段成果并确认是否调整;用户已经明确批准的内容和连续制作范围直接沿用。不把每个工具调用、内部分析或无需求的子步骤变成提问。 +- 内容确认、消耗算力授权、结果采用分别记录。生成前展示可审阅的具体方案:对象与数量、模型、完整提示词、实际参考、规格及执行次数。对用户统一称“消耗算力”,无法查询时写“算力消耗未知”。 +- 通过宿主 `askUser` 或明确回复取得授权。已批准的同一具体方案或批次不逐节点重复问;新增数量、改变实际方案或额外重试时核对授权是否覆盖。普通“继续”、沉默和表单失败不构成新生成授权。 +- Seedance 目标模型只按 PART A A0 判定;**未指定时必须先用一次简短提问确认 2.0 或 2.5。** 这个问题属于 Seedance A0,不属于画布配置,且不得解除路由锁存。画布层仅在目标模型确认并进入 PART A 后,通过实时配置核实该模型/模式是否实际可执行。节点默认值、宿主默认值、配置表单、历史配置或用户对分辨率/画幅等配置的回答,都不得反向覆盖或解除 A0 的模型路由;配置问答结束后继续当前 Seedance 执行态。 +- 有对白不等于必须有外部音色样本。提示词内的声音写法只服从 PART A;实际执行时仅通过[画布执行](references/canvasExecution.md)核对模型是否支持原生声音与真实音频输入,不得据此改写 PART A 的对白/声音规则。 + +## 完成与恢复的底线 + +文本节点正文通过节点函数保存,文件路径从实际 `data.textPath` 读取。跨轮制作使用一个简洁状态记录和一个总览节点;沿用现有台账,不因缺固定模板要求重做。 + +待确认或已采用文本需要固定版本依据,生成需保留本次提示词、参数、参考和旧输出。确认后再次核对实际节点,防止用户在等待期间的修改被当作已批准;已采用素材优先固定在素材节点,修订另建候选。具体做法见[状态与交付](references/stateAndDelivery.md)。 + +当前原生媒体节点返回 `generating` 只表示开始,不能宣称完成。若本轮没有真实状态或等待工具,完成本轮已授权且无依赖的启动与文字工作后,登记并告知用户完成后回复,再回读对应节点;不编造自动唤醒或后台轮询。连续片段的后段生成需等前段采用并取得真实交界状态,文字规划可先列预期状态;无依赖的资产或片段可按已明确授权的批次安排。 + +视频路径不代表 Agent 看过视频。只按实际媒体读取能力核验,能力不足时由用户预览并报告问题、交界状态与采用决定,明确 Agent 未核验的部分。交付区分已生成片段、用户采用片段、已合成成片与已归集副本;没有对应工具就如实交付现有成果及缺项。 diff --git a/references/workflow.md b/references/workflow.md new file mode 100644 index 0000000..3fe3f50 --- /dev/null +++ b/references/workflow.md @@ -0,0 +1,67 @@ +# 七阶段流水线与闸门 + +核心不是「一键出片」,而是**资产节点化 / 可局部重做 / 阶段确认 / 方法论文件化**。落到文件上:节点 = `30_shots.json` 的一行,连线 = `refs` 与 `manifest` 依赖,画布 = 目录。 + +``` +基线资产 assets/ + config/ (跨集只读,被阶段 1–2 引用) + │ + ① 策划叙事 ─ ② 分镜中枢 ─ ③ 配音先行 ─ ④ 出图/出视频 ─ ⑤ 缝合 ─ ⑥ 审片归档 + │ │ │ │ │ │ + 00_brief 30_shots.json vo_NN.mp3 Sxx_ renders/ INDEX.md + 10_events 40_prompts/ manifest + 20_script + └── 贯穿:校验前置 · 提示词哈希 · 单镜重做 · 阶段闸门 · manifest 回溯 ──┘ +``` + +## 阶段与闸门 + +| # | 阶段 | 输入 | 输出 | 闸门(必须停下等确认) | +|---|---|---|---|---| +| 0 | 基线资产 | 角色设定、参考图 | `assets/` 角色卡 / 画风模板 / HUD | 锚图定稿后锁为只读 | +| 1 | 策划与叙事 | 选题、原著片段 | `00_brief.md`、`10_events.md`、`20_script.md` | 禁忌清单过一遍;**重编不是缩写** | +| 2 | 分镜中枢 | 阶段 1 + 资产 | `30_shots.json`、`40_prompts/Sxx.i2v.txt` | `manju.py validate` 全绿;提示词逐条展示 | +| 3 | 配音先行 | `line` 字段 | `work/EPxx/audio/vo_NN.mp3` | 实测时长回填 `duration`,不允许加快语速硬塞 | +| 4 | 出图 / 出视频 | `refs` + 提示词 | `work/EPxx/{images,videos}/Sxx_.*` | **展示对象、数量、模型、完整提示词、参数、执行次数,取得明确授权**;导出后清服务端记录与产物 | +| 5 | 缝合 | 已采用片段 | `renders/EPxx_成片.mp4` | 只拼「已采用」片段;未采用的另建候选 | +| 6 | 审片与归档 | 成片 | `renders/INDEX.md`、`50_manifest.json` | 区分已生成 / 已采用 / 已合成,不把清单完成当状态完成 | + +**闸门铁律**:普通「继续」、沉默、表单失败都不构成新的生成授权;额外重试要先核对授权是否覆盖。生成返回任务 ID / `generating` 只表示开始,不能宣称完成。 + +**阶段 0 / 4 的模型闸门**:出锚图与首帧走内网 H3-Image(`tools/submit_t2i.py`,端点 `192.168.1.30:30113`,权重自动探测),出视频在 A14B 与 MiniMax H3 之间先选型(是否需要原生音轨),两者在 K8s 侧共用一张卡、只能串行。端点、节点图与两端差异见 [models.md](models.md);**展示授权清单时必须写明用的是哪个模型、哪个端点**——换模型等于换节点图,不能只改 endpoint。 + +**阶段 4 出图的自检闸门**:`submit_t2i.py` 每次出图后自动做 PNG 自检(颜色数 / 亮度 / 标准差),输出 `[SANITY]` 行。 +**`[SANITY]` 判失败(纯色图)时必须停下**,不要重跑、也不要清理服务端 —— 这说明量化档位或端点选错了 +(DCU 禁 `int8_convrot`,K8s-30113 只能用 `int8_convrot`),重跑只会再出一张废图。 +正确做法:按 [models.md §2.0](models.md) 的量化档位表核对端点与权重,再决定换端点还是改提示词。 + +**阶段 4 的导出后置闸门(必做)**:`/view` 拉回本地且文件大于 `cleanup.minBytes` 才算「已导出」,随后用官方标准接口(`/api/history`、`/api/queue` 的 `{"delete":[...]}`,删后必须复核「删前有→删后无」——200 空 body 是幂等响应,不等于删除成功)清掉服务端记录,再清本次生成的 `output` / `temp` 文件。官方没有删 `output/` 文件的 HTTP 路由,按 `cleanup.deleteApi`(社区自定义节点的 DELETE)或 `cleanup.commands` 处理。清理失败要如实报告状态,不能把「已下载」说成「已清理」。**只清服务端**:本地成片、提示词原文、`30_shots.json`、`50_manifest.json` 全部保留,台账默认只去掉 `promptId`。工具与接口细节见 [models.md §3.4](models.md)。 + +## 输出契约 + +`30_shots.json` 一行一镜,每个 `shotId` 对应三样东西: + +- `40_prompts/Sxx.i2v.txt` —— 该镜提示词**原文**,一字不改,供复核与回溯 +- `work/EPxx/videos/Sxx_.mp4` —— 哈希取提示词内容 sha256 前 8 位,改词即换文件,旧版不覆盖 +- `50_manifest.json` 中的一条记录:路径、哈希、模型参数、参考版本、状态、重做原因 + +## 单镜重做 + +改第 3 镜不动其余镜头: + +```bash +python3 tools/manju.py hash "$(cat projects/EPxx/40_prompts/S03.i2v.txt)" # 新哈希 +# 修改 30_shots.json 里 S03 的 promptHash / status=planned +python3 tools/manju.py validate projects/EPxx/30_shots.json +# 只重提 S03:python3 tools/submit_i2v.py projects/EPxx/30_shots.json --only S03 --force +# 再在 50_manifest.json 追加一条 attempt,保留旧记录 +``` + +依赖影响面按真实引用查:角色外观改 → 所有引用该锚图的镜;台词改 → 该镜时长与配音;空间/动作改 → 相邻交界镜。未被影响的片段继续有效。 + +## 不做的事 + +- 不递归「结构修正 ↔ 抛光」:结构修正只做一轮集中修改,随后单次抛光。 +- 不为了「让它连得上」自行补桥接动作、补道具来源、把模糊角色具体化。 +- 不把提示词当作已生成的成片,不把文件路径当作「已看过视频」。 +- 派生内容是否允许回灌知识库,按项目 `policy` 清单执行,默认不允许。 +- 不在「导出后清理」里删本地已采用成片或提示词原文;也不清别人挂在同一个 ComfyUI 上的任务(`--clear` 全清一律禁用,只按 `prompt_id` 精确删)。`/free` 整批结束统一调用一次,别每镜卸载模型。 diff --git a/scripts/cleanup_comfyui.py b/scripts/cleanup_comfyui.py new file mode 100644 index 0000000..f0ac10c --- /dev/null +++ b/scripts/cleanup_comfyui.py @@ -0,0 +1,883 @@ +#!/usr/bin/env python3 +"""manju 生成后清理:只删「自己发起的任务」的 ComfyUI 记录与服务端产物。 + +归属模型(本版本核心): + * 本地台账里的 promptId 只可能是本技能提交的任务 —— 这是第一层凭证; + * ComfyUI 把 client_id 持久化在 history 项 prompt[3]["client_id"] 里, + 提交脚本用可识别的 "manju-i2v-*" / "manju-t2i-*",并把 clientId 写进台账。 + 清理时按「台账 clientId 精确匹配 > ownerPrefixes 前缀白名单」判归属, + 未通过一律拒绝,**不会调用任何删除接口**(fail-closed)。 + * 服务端扩展再做一次独立归属校验,双保险。 + +标准接口(ComfyUI 0.38 / 0.45 实机核对 + 官方 server.py / docs.comfy.org): + * GET /api/system_stats 探测 /api 前缀是否可用 + * GET /api/history/ 抽产物清单 + client_id(顺序铁律) + * POST /api/history {"delete": [pid, ...]} 批量删生成记录 + * POST /api/queue {"delete": [pid, ...]} 批量删队列残留 + * POST /api/free {"unload_models": true, "free_memory": true} 释放模型/显存 + * GET /api/history/ + GET /api/queue 删后复核「从有到无」 + +官方**没有**删除 output/ 产物文件的 HTTP 路由(DELETE /userdata 只管 ComfyUI/user/, +/api/assets 删的是数据库引用且现网 503)。所以本技能自带扩展 +assets/comfyui-manju-cleanup/,装到 ComfyUI/custom_nodes 后提供: + * GET /manju/cleanup/ping 能力探测(官方 add_routes 自动镜像 /api 前缀) + * POST /manju/cleanup/purge 按 pid 从服务端 history 反查产物并安全删除 + +顺序铁律(装了扩展时): + 预览 purge(dry_run=true) → purge(dry_run=false) 删文件 → 官方 POST /history|/queue + 删记录 → 复核 → 整批 /free。 + purge 依赖 history 反查文件名,**必须先删文件再删记录**;反序会永远查不到产物。 + +没装扩展时自动降级到社区 DELETE 插件(deleteApi)或 cleanup.commands 文件系统模板; +此时顺序仍是「先抽清单 → 删记录 → 复核 → 删文件」。 + +安全闸门:本地导出的成片必须存在且 >= cleanup.minBytes 才允许清理;默认 dry-run, +必须 --apply 才真删。只按 prompt_id 精确删,禁用 {"clear": true}。本地资产永不删除。 + +用法: + python3 tools/cleanup_comfyui.py --ep EP01 # 预演 + python3 tools/cleanup_comfyui.py --ep EP01 --apply # 真清 + python3 tools/cleanup_comfyui.py --ep EP01 --shot S03 --apply # 只清一镜 + python3 tools/cleanup_comfyui.py --prompt-id --endpoint http://... --apply + python3 tools/cleanup_comfyui.py --ep EP01 --apply --purge-input --free +""" +import argparse +import json +import os +import shlex +import subprocess +import sys +import time +import urllib.error +import urllib.parse +import urllib.request + +opener = urllib.request.build_opener(urllib.request.ProxyHandler({})) + +# K8s 三个端点的默认降级模板:动态取 pod 名,不重启 Pod 也能精确删产物。 +# 与 assets/config.template.json 的 cleanup.commands 保持一致;工作空间配置可覆盖。 +_K8S_RM_TMPL = ( + "KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong exec " + "$(KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong get pods " + "-l app={app} -o jsonpath='{.items[0].metadata.name}') -c comfyui -- " + "sh -c \"cd {root} && rm -f -- {files} {temp_files}\"") + +DEFAULT_CLEANUP = { + "auto": False, # 提交脚本导出成功后是否自动调用 + "minBytes": 100000, # 本地成片小于此值视为导出失败,拒绝清理 + "commands": { # {endpoint: "shell 模板"},占位符见 render_command + # 2026-11-13 起三个端口都指向同一个 pod(comfyui-wan-h3image,ComfyUI 0.45): + # 旧的 comfyui-wan-a14b / comfyui-wan-h3 deployment 已 scale 到 0, + # 它们的 Service selector 改指 app=comfyui-wan-h3image,NodePort 保持不变。 + # 因此三条模板的 pod 选择器必须统一,否则会取到空 pod 名。 + "http://192.168.1.30:30112": _K8S_RM_TMPL.replace("{app}", "comfyui-wan-h3image"), + "http://192.168.1.30:30111": _K8S_RM_TMPL.replace("{app}", "comfyui-wan-h3image"), + # H3-Image 文生图端点:未装 manju-cleanup 扩展,走 kubectl exec 降级 + "http://192.168.1.30:30113": _K8S_RM_TMPL.replace("{app}", "comfyui-wan-h3image"), + }, + "command": "", # 通用回退模板 + "outputRoot": "/comfyui/output", # 服务端 output 根目录(K8s 是 PVC 软链) + "inputRoot": "/comfyui/input", + "purgeInput": False, # 上传的首帧图是否一起删(多镜可能共用,默认不删) + "free": False, # 整批清理结束后是否 POST /free(别每镜调用) + "apiBase": "/api", # 官方新版标准前缀;探测失败自动回退 "" + "deleteApi": "", # 社区自定义节点:comfyui_extra_api | api-tools | "" + "nodeApi": "", # 扩展路径前缀;留空自动探测 /api/manju/cleanup + "clientIds": [], # 额外 client_id 精确白名单(补老台账没记 clientId 的任务) + "ownerPrefixes": ["manju-"], # client_id 前缀白名单 + "requireOwner": True, # 归属校验失败一律拒绝;改成 false 是危险的 + "token": "", # 扩展设了 MANJU_CLEANUP_TOKEN 时填这里 +} + +# 社区自定义节点提供的标准 DELETE 路由(现网未安装,需显式配置才启用) +DELETE_APIS = { + "comfyui_extra_api": ( + "/comfyapi/v1/output-images", + "/comfyapi/v1/output-images/{name}?temp=false"), + "api-tools": ( + "/api-tools/v1/images/output", + "/api-tools/v1/images/output/{name}?temp=false"), +} +IMAGE_EXTS = (".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp") + +_API_BASE_CACHE = {} +_NODE_CACHE = {} + + +def find_root(): + env = os.environ.get("MANJU_ROOT") + if env: + return os.path.abspath(os.path.expanduser(env)) + d = os.getcwd() + while True: + if os.path.isfile(os.path.join(d, "config", "pipeline.json")): + return d + nd = os.path.dirname(d) + if nd == d: + break + d = nd + return os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + + +def load_cfg(root): + p = os.path.join(root, "config", "pipeline.json") + raw = json.load(open(p, encoding="utf-8")) if os.path.isfile(p) else {} + c = dict(DEFAULT_CLEANUP) + c.update(raw.get("cleanup", {})) + return raw, c + + +def http(host, path, payload=None, timeout=30, method=None): + """返回 (status, json|None)。HTTPError 不当异常抛,返回码交给调用方判断。 + + ComfyUI 的 delete / free / interrupt 路由返回 200 空 body;空 body 不解析。 + """ + if method is None: + method = "POST" if payload is not None else "GET" + data, headers = None, {} + if payload is not None: + data = json.dumps(payload).encode() + headers["Content-Type"] = "application/json" + req = urllib.request.Request(host + path, data=data, headers=headers, method=method) + try: + with opener.open(req, timeout=timeout) as r: + body, status = r.read(), r.status + except urllib.error.HTTPError as e: + return e.code, None + if not body: + return status, None + try: + return status, json.loads(body) + except ValueError: + return status, None + + +def api_base(host, cfg): + """探测 /api 前缀(官方新版标准路径),不可用则回退无前缀的旧路径。""" + want = str(cfg.get("apiBase", "/api")).rstrip("/") + key = (host, want) + if key in _API_BASE_CACHE: + return _API_BASE_CACHE[key] + pref = "" + if want: + try: + st, d = http(host, want + "/system_stats", timeout=10) + if st == 200 and isinstance(d, dict) and ("system" in d or "devices" in d): + pref = want + except Exception: + pass + _API_BASE_CACHE[key] = pref + return pref + + +def ap(host, cfg, path): + return api_base(host, cfg) + path + + +def rel_file(f): + """history outputs 里的一条 -> (type, subfolder, filename)""" + return (f.get("type") or "output", + (f.get("subfolder") or "").strip("/\\"), + f.get("filename") or "") + + +def collect_outputs(item): + """从 history 条目的 outputs 抽全部产物,含 SaveImage / SaveVideo 多输出节点。""" + found = [] + for node in (item.get("outputs") or {}).values(): + for key in ("images", "videos", "gifs", "audio"): + for f in (node.get(key) or []): + t, sub, name = rel_file(f) + if name: + found.append({"type": t, "subfolder": sub, "filename": name}) + return found + + +def collect_inputs(item): + """从 history 的 prompt 节点图里找 LoadImage 用到的上传图(input 目录)。""" + found = [] + prompt = item.get("prompt") or [] + graph = prompt[2] if len(prompt) > 2 and isinstance(prompt[2], dict) else {} + for node in graph.values(): + if not isinstance(node, dict): + continue + ct = node.get("class_type", "") + if "LoadImage" not in ct and "ImageLoader" not in ct: + continue + name = (node.get("inputs") or {}).get("image") + if isinstance(name, str) and name: + sub, _, base = name.rpartition("/") + found.append({"type": "input", "subfolder": sub, "filename": base or name}) + return found + + +def client_id_of(item): + """ComfyUI 把 client_id 持久化在 history 项 prompt[3](HTTP 序列化态)或 prompt[0] + (内存态原始布局 [extra_data, number, prompt])。两种都兼容,再退化递归找。""" + p = item.get("prompt") if isinstance(item, dict) else None + if isinstance(p, (list, tuple)): + for idx in (3, 0): + if len(p) > idx and isinstance(p[idx], dict) and "client_id" in p[idx]: + return str(p[idx].get("client_id") or "") + r = _find_client_id(item) + return str(r) if r else "" + + +def _find_client_id(o): + if isinstance(o, dict): + if "client_id" in o: + return o["client_id"] + for v in o.values(): + r = _find_client_id(v) + if r is not None: + return r + elif isinstance(o, (list, tuple)): + for v in o: + r = _find_client_id(v) + if r is not None: + return r + return None + + +def credentials_for(job, cfg): + """本次任务的归属凭证:台账 clientId + 配置精确白名单 + 前缀白名单。""" + ids = [x for x in [job.get("clientId")] + list(cfg.get("clientIds") or []) if x] + return {"client_ids": list(dict.fromkeys(str(x) for x in ids)), + "prefixes": list(cfg.get("ownerPrefixes") or []), + "require_owner": bool(cfg.get("requireOwner", True)), + "token": str(cfg.get("token") or "")} + + +def owner_of(cid, creds): + """(owned, reason)。没有任何凭证时 fail-closed,绝不因为「传了 pid」就放行。""" + if cid and cid in creds["client_ids"]: + return True, "台账 clientId 精确匹配" + if cid and any(cid.startswith(p) for p in creds["prefixes"] if p): + return True, "client_id 前缀白名单匹配" + if not creds["require_owner"]: + return True, "requireOwner=false(显式关闭归属校验,不推荐)" + return False, ("client_id=%r 不在白名单:台账无 clientId、clientIds 未列、" + "ownerPrefixes 不匹配" % cid) + + +def node_api(host, cfg): + """探测 manju-cleanup 扩展,返回可用路径前缀('' 表示未安装)。""" + key = (host, str(cfg.get("nodeApi") or "")) + if key in _NODE_CACHE: + return _NODE_CACHE[key] + custom = str(cfg.get("nodeApi") or "").rstrip("/") + cands = [custom] if custom else [ap(host, cfg, "/manju/cleanup"), + "/manju/cleanup"] + for p in dict.fromkeys([x for x in cands if x]): + try: + st, d = http(host, p + "/ping", timeout=8) + if st == 200 and isinstance(d, dict) and d.get("ok"): + _NODE_CACHE[key] = p + return p + except Exception: + pass + _NODE_CACHE[key] = "" + return "" + + +def node_purge(host, cfg, prefix, pids, creds, dry_run, purge_input): + """调扩展的 purge;服务端按 pid 自己从 history 反查文件并二次校验归属。""" + body = {"pids": list(pids), + "client_ids": creds["client_ids"], + "owner_prefixes": creds["prefixes"], + "require_owner": creds["require_owner"], + "dry_run": bool(dry_run), "purge_input": bool(purge_input)} + if creds["token"]: + body["token"] = creds["token"] + try: + st, d = http(host, prefix + "/purge", body, timeout=90) + except Exception as e: + return {"ok": False, "error": "请求失败:%s" % e, "pids": {}} + if st != 200 or not isinstance(d, dict): + return {"ok": False, "error": "HTTP %d" % st, "pids": {}} + return d + + +def node_files_text(entry): + """把扩展返回的单个 pid 报告压成一行人话。""" + if not entry: + return "扩展未返回该 pid" + if not entry.get("exists"): + return "拒绝:history 已无该条,服务端不猜测文件名" + if not entry.get("owned"): + return "拒绝:扩展归属校验未通过(%s)" % entry.get("owner_reason", "") + counts = {} + for f in entry.get("files") or []: + counts[f["status"]] = counts.get(f["status"], 0) + 1 + return "扩展 purge:%s" % (", ".join("%s=%d" % kv for kv in sorted(counts.items())) + or "无文件") + + +def inspect_pid(pid, host, cfg, creds, purge_input=False): + """阶段 A:先从 history 抽产物清单与 client_id,删了记录就再也拿不到。 + + 扩展的 dry_run 预览由调用方按 host 批量执行(node_purge),不在这里发请求。 + """ + rep = {"pid": pid, "host": host, "outputs": [], "inputs": [], + "history": "?", "queue": "?", "verify": "?", "files": "?", + "commands": [], "had": False, "client_id": "", "owned": False, + "owner_reason": "", "creds": creds, "node": "", "node_entry": {}} + rep["node"] = node_api(host, cfg) + try: + st, item = http(host, ap(host, cfg, "/history/" + urllib.parse.quote(pid)), timeout=30) + d = item or {} + if st != 200: + rep["verify"] = "history 读取 HTTP %d,不做文件清理" % st + return rep + entry = d.get(pid, d) if isinstance(d, dict) else {} + rep["had"] = bool(d) and (pid in d if isinstance(d, dict) else True) + all_out = collect_outputs(entry) if isinstance(entry, dict) else [] + # 有些节点(LoadVideo / 预览类)会在 outputs 里回带 type=input 的源素材。 + rep["outputs"] = [f for f in all_out if f["type"] in ("output", "temp")] + extra = [f for f in all_out if f["type"] == "input"] + seen = {(f["type"], f["subfolder"], f["filename"]) for f in extra} + rep["inputs"] = extra + [f for f in collect_inputs(entry) + if (f["type"], f["subfolder"], f["filename"]) not in seen] + rep["client_id"] = client_id_of(entry) + except Exception as e: + rep["verify"] = "history 读取失败:%s" % e + rep["owned"], rep["owner_reason"] = owner_of(rep["client_id"], creds) + if not rep["had"]: + rep["note"] = "history 已无该条(可能重启/被清过),不猜测文件名" + return rep + + +def merge_node_preview(rep, resp): + """把服务端 dry_run 预览的归属结论并进客户端报告(服务端优先否决)。""" + if not (isinstance(resp, dict) and resp.get("ok")): + rep["node_error"] = (resp or {}).get("error", "预览失败") + return + e = (resp.get("pids") or {}).get(rep["pid"]) + rep["node_entry"] = e or {} + if e and not e.get("owned"): + rep["owned"] = False + rep["owner_reason"] = "扩展否决:%s" % e.get("owner_reason", "") + + +def delete_records(host, pids, cfg, had_map): + """按 host 批量调标准接口删记录,再逐 pid 复核「从有到无」。 + + 200 空 body 只代表请求被接受且幂等完成,不代表记录真的消失。 + """ + out = {pid: {} for pid in pids} + for path, key in (("/history", "history"), ("/queue", "queue")): + try: + st, _ = http(host, ap(host, cfg, path), {"delete": list(pids)}, timeout=30) + ok = st == 200 + for pid in pids: + out[pid][key] = ("HTTP 200(空 body)" if ok else "FAILED HTTP %d" % st) + except Exception as e: + for pid in pids: + out[pid][key] = "FAILED: %s" % e + + for pid in pids: + try: + st, d = http(host, ap(host, cfg, "/history/" + urllib.parse.quote(pid)), timeout=20) + still = bool(d) and (pid in d if isinstance(d, dict) else True) + if st == 200 and not still and had_map.get(pid): + out[pid]["verify"] = "已确认(删前有 → 删后无)" + elif not had_map.get(pid): + out[pid]["verify"] = "幂等 200,但删前就无此记录,不宣称删除成功" + elif still: + out[pid]["verify"] = "FAILED:复核时记录仍在" + else: + out[pid]["verify"] = "未确认(HTTP %d)" % st + except Exception as e: + out[pid]["verify"] = "复核失败:%s" % e + try: + st, q = http(host, ap(host, cfg, "/queue"), timeout=20) + if st == 200 and isinstance(q, dict): + live = set() + for arr in ("queue_running", "queue_pending"): + for x in q.get(arr) or []: + if isinstance(x, list) and len(x) > 1: + live.add(str(x[1])) + for pid in pids: + out[pid]["queue_verify"] = "queue 已无该 pid" if pid not in live else \ + "FAILED:queue 里仍有该 pid" + except Exception: + pass + return out + + +def render_command(template, files, root, input_files, input_root): + """把模板里的占位符替换成 shell-safe 的路径列表。""" + def q(fs): + return " ".join(shlex.quote(os.path.join(f["subfolder"], f["filename"])) + for f in fs) if fs else "" + return (template + .replace("{files}", q([f for f in files if f["type"] == "output"])) + .replace("{temp_files}", q([f for f in files if f["type"] == "temp"])) + .replace("{input_files}", q(input_files)) + .replace("{root}", shlex.quote(root) if root else ".") + .replace("{input_root}", shlex.quote(input_root) if input_root else ".")) + + +def pick_command(cfg, host): + return (cfg.get("commands") or {}).get(host.rstrip("/")) or cfg.get("command") or "" + + +def try_http_delete(host, cfg, files): + """社区方案:若端点装了自定义节点,用标准 HTTP DELETE 删 output 图片。""" + name = str(cfg.get("deleteApi") or "").strip() + if not name or name not in DELETE_APIS: + return [], files, "" + list_path, del_tpl = DELETE_APIS[name] + try: + st, d = http(host, list_path, timeout=15) + if st != 200 or not isinstance(d, (list, dict)): + return [], files, "deleteApi=%s 未就绪(HTTP %d),回退文件模板" % (name, st) + except Exception as e: + return [], files, "deleteApi=%s 探测失败:%s" % (name, e) + + deleted, remaining, fails = [], [], [] + for f in files: + path = os.path.join(f["subfolder"], f["filename"]) + eligible = (f["type"] == "output" and not f["subfolder"] + and f["filename"].lower().endswith(IMAGE_EXTS)) + if not eligible: + remaining.append(f) + continue + url = del_tpl.replace("{name}", urllib.parse.quote(f["filename"])) + try: + st, _ = http(host, url, timeout=20, method="DELETE") + (deleted if st in (200, 204) else remaining).append(f) + if st not in (200, 204): + fails.append("%s → HTTP %d" % (path, st)) + except Exception as e: + remaining.append(f) + fails.append("%s → %s" % (path, e)) + note = "标准 DELETE 删掉 %d 个%s" % (len(deleted), (";失败:" + ", ".join(fails[:3])) if fails else "") + return deleted, remaining, note + + +def delete_files(host, cfg, rep, apply, purge_input=False): + """降级路线:优先社区 DELETE,其余走服务端文件系统模板。 + + dry-run 绝不发任何 DELETE / 任何 shell 命令,只列清单与将要执行的命令。 + """ + files = rep["outputs"] + (rep["inputs"] if purge_input else []) + inputs = rep["inputs"] if purge_input else [] + if not files: + rep["files"] = "无产物文件需删" + return rep + + tpl = pick_command(cfg, host) + cmd = render_command(tpl, files, cfg.get("outputRoot", ""), + inputs, cfg.get("inputRoot", "")) if tpl else "" + + if not apply: + parts = ["dry-run 不删(%d 个文件)" % len(files)] + name = str(cfg.get("deleteApi") or "").strip() + if name in DELETE_APIS: + st, d = http(host, DELETE_APIS[name][0], timeout=15) + n_img = sum(1 for f in files if f["type"] == "output" and not f["subfolder"] + and f["filename"].lower().endswith(IMAGE_EXTS)) + parts.append("deleteApi=%s %s,%d 个图片将走标准 DELETE" + % (name, "可用" if st == 200 and isinstance(d, (list, dict)) else "未就绪", + n_img)) + if cmd: + rep["commands"].append(cmd) + else: + parts.append("未配 cleanup.commands[%s],服务端文件只能手工清" % host) + rep["pending"] = files + rep["files"] = " | ".join(parts) + return rep + + deleted, remaining, note = try_http_delete(host, cfg, files) + parts = [note] if note else [] + + if remaining: + if not tpl: + parts.append("未配 cleanup.commands[%s],%d 个文件未删(见清单)" + % (host, len(remaining))) + rep["pending"] = remaining + else: + cmd = render_command(tpl, remaining, cfg.get("outputRoot", ""), + inputs, cfg.get("inputRoot", "")) + rep["commands"].append(cmd) + try: + p = subprocess.run(cmd, shell=True, capture_output=True, + text=True, timeout=120) + parts.append("模板 %s (rc=%d)" % ("ok" if p.returncode == 0 else "FAILED", + p.returncode)) + if p.returncode != 0: + parts.append(p.stderr.strip()[:200]) + except Exception as e: + parts.append("模板 FAILED: %s" % e) + if not parts: + parts.append("全部走标准 DELETE") + rep["files"] = " | ".join(parts) + return rep + + +def free_models(host, cfg): + """标准接口释放模型/显存。它只是设置队列 flag,真正卸载发生在下一个队列循环。""" + try: + st, _ = http(host, ap(host, cfg, "/free"), + {"unload_models": True, "free_memory": True}, timeout=30) + return "HTTP %d(空 body,异步生效)" % st if st == 200 else "FAILED HTTP %d" % st + except Exception as e: + return "FAILED: %s" % e + + +LEDGER_NAMES = ("t2i_runs.json", "a14b_runs.json") + + +def ledger_paths(root, ep): + """列出该扫描范围内的台账(去重)。 + + submit_t2i.py 把台账写在 **os.path.dirname(out)**,所以台账位置随输出路径变: + --ep/--shot 出图 → work//images/t2i_runs.json + 裸 --out 出锚图 → assets/characters/t2i_runs.json(跟图片同目录!) + 因此不能只猜固定路径 —— 漏扫 = 锚图产物永远留在服务端。 + 这里直接递归扫工作空间下所有同名台账,--ep 时额外限定只取该集内的。 + """ + found, seen = [], set() + + def add(label, path): + rp = os.path.realpath(path) + if rp in seen: + return + seen.add(rp) + found.append((label, path, "videoModel" if label == "a14b_runs.json" else "imageModel")) + + for base, dirs, files in os.walk(root): + dirs[:] = [d for d in dirs if d not in (".git", "__pycache__", "node_modules")] + for fn in files: + if fn not in LEDGER_NAMES: + continue + path = os.path.join(base, fn) + rel = os.path.relpath(path, root) + if ep: + # 带 --ep 时:只要台账路径里含该集号,或台账在集外(锚图目录) + in_ep = (os.sep + ep + os.sep) in (os.sep + rel) + outside_ep = not any( + part.startswith("EP") and os.path.isdir(os.path.join(root, "work", part)) + for part in rel.split(os.sep) + ) + if not in_ep and not outside_ep: + continue + add(fn, path) + return found + + +def gather(root, raw, cfg, ep, shots, prompt_ids): + """收集待清理任务,逐条过导出闸门。返回 (jobs, skipped)。 + + prompt_ids 元素兼容 6 元组与 7 元组(末尾多一个 clientId)。 + """ + jobs, skipped = [], [] + for p in prompt_ids: + pid, host, key, ledger, ledger_key, local = p[:6] + cid = p[6] if len(p) > 6 else "" + jobs.append({"pid": pid, "host": host, "key": key, "ledger": ledger, + "ledgerKey": ledger_key, "local": local, "clientId": cid, + "reason": "--prompt-id 显式指定,跳过导出闸门"}) + # 扫描台账:无 --ep 时扫工作空间根的台账(裸 --out 的锚图), + # 有 --ep 时扫该集台账 + 根级台账(锚图不属于任何集)。 + for label, path, cfg_key in ledger_paths(root, ep): + if not os.path.isfile(path): + continue + runs = json.load(open(path, encoding="utf-8")) + host = str(raw.get(cfg_key, {}).get("endpoint", "")).rstrip("/") + for key, rec in runs.items(): + if shots and key not in shots and key.split("/")[-1] not in shots: + continue + pid = rec.get("promptId") + if not pid: + continue # 已清过,跳过 + # 台账里的 endpoint 是该任务**实际**提交到的端点,优先于配置里的全局值 + # (锚图与首帧可能不在同一个端点,别清错地方) + task_host = str(rec.get("endpoint") or host).rstrip("/") + local = os.path.join(root, rec.get("out", "")) + ok = os.path.isfile(local) and os.path.getsize(local) >= int(cfg["minBytes"]) + j = {"pid": pid, "host": task_host, "key": key, "ledger": path, + "ledgerKey": key, "local": local, + "clientId": rec.get("clientId", "")} + if ok: + jobs.append(j) + else: + j["reason"] = "本地导出文件缺失或过小:%s" % local + skipped.append(j) + seen, uniq = set(), [] + for j in jobs: + if j["pid"] in seen: + continue + seen.add(j["pid"]) + uniq.append(j) + return uniq, skipped + + +def update_ledger(jobs, skipped, apply, purge_ledger): + """默认移除服务端可关联的 promptId 并留清理时间;--purge-ledger 则删整条。""" + if not apply: + return 0 + touched = set() + for j in jobs: + p = j.get("ledger") + if not p or not os.path.isfile(p) or p in touched: + continue + touched.add(p) + runs = json.load(open(p, encoding="utf-8")) + for job in jobs: + if job.get("ledger") != p: + continue + k = job.get("ledgerKey") + if k not in runs: + continue + if purge_ledger: + runs.pop(k, None) + else: + runs[k].pop("promptId", None) + runs[k]["cleanedAt"] = time.strftime("%Y-%m-%d %H:%M:%S") + with open(p, "w", encoding="utf-8") as f: + json.dump(runs, f, ensure_ascii=False, indent=2) + return len(touched) + + +def group_by(pairs, key): + g = {} + for item in pairs: + g.setdefault(key(item), []).append(item) + return g + + +def cleanup_pid(pid, host, apply, cfg, creds=None, purge_input=False): + """单 pid 完整清理,供提交脚本的 after_export 钩子调用。""" + creds = creds or credentials_for({}, cfg) + rep = inspect_pid(pid, host, cfg, creds, purge_input) + prefix = rep["node"] + if prefix: + prev = node_purge(host, cfg, prefix, [pid], creds, True, purge_input) + merge_node_preview(rep, prev) + if not rep["owned"]: + rep["history"] = rep["queue"] = "拒绝:归属校验未通过" + rep["files"] = "拒绝:不删任何服务端文件" + return rep + if not apply: + rep["history"] = "dry-run 不删" + rep["queue"] = "dry-run 不删" + if prefix: + rep["files"] = node_files_text(rep["node_entry"]) + return rep + return delete_files(host, cfg, rep, False, purge_input) + + if prefix: + res = node_purge(host, cfg, prefix, [pid], creds, False, purge_input) + rep["node_entry"] = (res.get("pids") or {}).get(pid, {}) + rep["files"] = node_files_text(rep["node_entry"]) + if not res.get("ok"): + rep["files"] += " | purge HTTP 异常:%s" % res.get("error", "") + res = delete_records(host, [pid], cfg, {pid: rep["had"]})[pid] + rep["history"] = "%s | %s" % (res["history"], res["verify"]) + rep["queue"] = res["queue"] + (" | " + res["queue_verify"] if res.get("queue_verify") else "") + if not prefix: + rep = delete_files(host, cfg, rep, True, purge_input) + return rep + + +def after_export(root, pid, host, ledger, ledger_key, local, client_id=""): + """提交脚本钩子:成片已落本地后,清掉服务端记录与产物。 + + 调用方保证下载成功。这里再独立过一次导出闸门 + 归属闸门,任何异常都只影响 + 清理、不影响已成片的产物。整批做完再单独 --free,不要每镜卸载模型。 + """ + raw, cfg = load_cfg(root) + host = host.rstrip("/") + if not os.path.isfile(local) or os.path.getsize(local) < int(cfg["minBytes"]): + return "SKIP 本地成片缺失/过小,未清理:%s" % local + if not client_id and ledger and os.path.isfile(ledger): + try: + client_id = (json.load(open(ledger, encoding="utf-8")) + .get(ledger_key, {}).get("clientId", "")) + except Exception: + pass + creds = credentials_for({"clientId": client_id}, cfg) + rep = cleanup_pid(pid, host, True, cfg, creds, bool(cfg.get("purgeInput"))) + if not rep["owned"]: + return "REFUSE 归属校验未通过(client_id=%s):未删任何记录/文件" % rep["client_id"] + update_ledger([{"ledger": ledger, "ledgerKey": ledger_key, "pid": pid}], + [], True, bool(cfg.get("purgeLedger"))) + tail = "" + if "未删" in rep["files"] or "未配" in rep["files"] or "拒绝" in rep["files"]: + tail = " | ⚠ 仍有服务端文件待清" + return ("history=%s queue=%s files=%s 产物%d个 归属=%s%s" + % (rep["history"], rep["queue"], rep["files"], len(rep["outputs"]), + rep["client_id"] or "-", tail)) + + +def print_report(j, rep, cfg): + print("\n[%s] %s @ %s" % (j["key"], j["pid"], j["host"])) + print(" 归属 : %s | client_id=%s | %s" % + ("✅ 自己的任务" if rep["owned"] else "⛔ 拒绝(非本人任务)", + rep["client_id"] or "-", rep["owner_reason"])) + print(" 扩展 : %s" % (rep["node"] + "/purge" if rep["node"] else + "未安装 → 降级 deleteApi / commands")) + print(" history : %s" % rep["history"]) + print(" queue : %s" % rep["queue"]) + print(" 产物 : %d 个文件" % len(rep["outputs"])) + for f in rep["outputs"]: + print(" - [%s] %s" % (f["type"], os.path.join(f["subfolder"], f["filename"]))) + if rep["node_entry"]: + for f in rep["node_entry"].get("files") or []: + print(" · %s → %s%s" % (os.path.join(f["subfolder"], f["filename"]), + f["status"], + ("(" + f["reason"] + ")") if f.get("reason") else "")) + if rep["inputs"]: + print(" 上传图 : %d 个%s" % (len(rep["inputs"]), + "(--purge-input 未开,列出不删)" if not cfg.get("purgeInput") else "")) + print(" 文件删除: %s" % rep["files"]) + for c in rep["commands"]: + print(" 命令 : %s" % c) + if rep.get("node_error"): + print(" 扩展错误: %s" % rep["node_error"]) + if rep.get("note"): + print(" 备注 : %s" % rep["note"]) + + +def main(): + ap_ = argparse.ArgumentParser(description="只清自己发起的任务:ComfyUI 记录 + 服务端产物") + ap_.add_argument("--ep", default="", help="集号,如 EP01;读该集两个台账") + ap_.add_argument("--shot", default="", help="只清指定镜,逗号分隔") + ap_.add_argument("--prompt-id", default="", help="直接指定 prompt_id,逗号分隔") + ap_.add_argument("--endpoint", default="", help="--prompt-id 对应的服务地址") + ap_.add_argument("--client-id", default="", help="--prompt-id 对应任务的 client_id(归属凭证)") + ap_.add_argument("--apply", action="store_true", help="真的执行;默认只预演") + ap_.add_argument("--purge-input", action="store_true", help="连上传的首帧图一起删") + ap_.add_argument("--purge-ledger", action="store_true", help="删掉本地台账整条记录") + ap_.add_argument("--free", action="store_true", help="整批结束后 POST /free 释放模型") + ap_.add_argument("--force", action="store_true", help="跳过本地导出文件闸门(危险)") + a = ap_.parse_args() + + root = find_root() + raw, cfg = load_cfg(root) + if a.force: + cfg["minBytes"] = 0 + if a.purge_input: + cfg["purgeInput"] = True + shots = set(x.strip() for x in a.shot.split(",") if x.strip()) + explicit = [] + if a.prompt_id: + host = (a.endpoint or raw.get("videoModel", {}).get("endpoint", "")).rstrip("/") + if not host: + return "用 --prompt-id 时必须给 --endpoint 或在 config 里配 videoModel.endpoint" + for pid in [x.strip() for x in a.prompt_id.split(",") if x.strip()]: + explicit.append((pid, host, pid, "", pid, "", a.client_id)) + + jobs, skipped = gather(root, raw, cfg, a.ep, shots, explicit) + if not jobs and not skipped: + return "没有待清理的 prompt(台账里无 promptId,或都已被清过)" + + print("模式:%s | 归属校验:%s" % ( + "APPLY 真删" if a.apply else "DRY-RUN 预演", + "开启(fail-closed)" if cfg.get("requireOwner", True) else "⚠ 已关闭")) + print("待清 %d 条,导出闸门拦下 %d 条" % (len(jobs), len(skipped))) + for s in skipped: + print(" [SKIP] %s %s" % (s["key"], s["reason"])) + + # 阶段 A:抽清单 + 客户端归属判定 + 探测扩展 + reports = [] + for j in jobs: + creds = credentials_for(j, cfg) + rep = inspect_pid(j["pid"], j["host"], cfg, creds, bool(cfg.get("purgeInput"))) + reports.append((j, rep, creds)) + + # 阶段 A2:扩展 dry_run 预览(按 host 批量),服务端归属结论优先否决 + for host, triples in group_by(reports, lambda t: t[1]["host"]).items(): + with_node = [t for t in triples if t[1]["node"]] + if not with_node: + continue + merged = {"client_ids": [], "prefixes": [], "require_owner": True, "token": ""} + for _, _, c in with_node: + merged["client_ids"] += c["client_ids"] + merged["prefixes"] += c["prefixes"] + merged["token"] = merged["token"] or c["token"] + merged["client_ids"] = list(dict.fromkeys(merged["client_ids"])) + merged["prefixes"] = list(dict.fromkeys(merged["prefixes"])) + prev = node_purge(host, cfg, with_node[0][1]["node"], + [t[1]["pid"] for t in with_node], merged, True, + bool(cfg.get("purgeInput"))) + for _, rep, _ in with_node: + merge_node_preview(rep, prev) + + # 归属闸门:不归属的 pid 绝不进入任何删除操作 + eligible = [t for t in reports if t[1]["owned"]] + for _, rep, _ in reports: + if not rep["owned"]: + rep["history"] = rep["queue"] = "拒绝:归属校验未通过" + rep["files"] = "拒绝:不删任何服务端文件" + rep["commands"] = [] + + # 阶段 B:扩展真实删文件(必须在删记录之前:purge 依赖 history 反查) + for host, triples in group_by(eligible, lambda t: t[1]["host"]).items(): + with_node = [t for t in triples if t[1]["node"]] + if not (a.apply and with_node): + continue + merged = {"client_ids": [], "prefixes": [], "require_owner": True, "token": ""} + for _, _, c in with_node: + merged["client_ids"] += c["client_ids"] + merged["prefixes"] += c["prefixes"] + merged["token"] = merged["token"] or c["token"] + merged["client_ids"] = list(dict.fromkeys(merged["client_ids"])) + merged["prefixes"] = list(dict.fromkeys(merged["prefixes"])) + res = node_purge(host, cfg, with_node[0][1]["node"], + [t[1]["pid"] for t in with_node], merged, False, + bool(cfg.get("purgeInput"))) + for _, rep, _ in with_node: + rep["node_entry"] = (res.get("pids") or {}).get(rep["pid"], {}) + rep["files"] = node_files_text(rep["node_entry"]) + if not res.get("ok"): + rep["files"] += " | purge 异常:%s" % res.get("error", "") + + # 阶段 C:官方标准接口批量删记录 + 复核(只传 eligible 的 pid) + if a.apply: + for host, triples in group_by(eligible, lambda t: t[1]["host"]).items(): + pids = [t[1]["pid"] for t in triples] + res = delete_records(host, pids, cfg, + {t[1]["pid"]: t[1]["had"] for t in triples}) + for _, rep, _ in triples: + r = res[rep["pid"]] + rep["history"] = "%s | %s" % (r["history"], r["verify"]) + rep["queue"] = r["queue"] + (" | " + r["queue_verify"] + if r.get("queue_verify") else "") + else: + for _, rep, _ in eligible: + rep["history"] = "dry-run 不删" + rep["queue"] = "dry-run 不删" + + # 阶段 D:未装扩展的走降级路线(社区 DELETE / 文件系统模板) + for _, rep, _ in eligible: + if rep["node"]: + if not a.apply: + rep["files"] = node_files_text(rep["node_entry"]) + else: + delete_files(rep["host"], cfg, rep, a.apply, bool(cfg.get("purgeInput"))) + + for j, rep, _ in reports: + print_report(j, rep, cfg) + + if a.apply: + n = update_ledger([j for j, rep, _ in eligible if rep["owned"]], + skipped, True, a.purge_ledger) + print("\n台账更新:%d 个文件(%s)" % ( + n, "整条删除" if a.purge_ledger else "移除 promptId + 记 cleanedAt")) + if a.free or cfg.get("free"): + for host in sorted(set(j["host"] for j, _, _ in eligible)): + print(" /free %s -> %s" % (host, free_models(host, cfg))) + else: + print("\n这是预演,未删除任何东西。确认清单后加 --apply。") + return 0 + + +if __name__ == "__main__": + try: + sys.exit(main()) + except Exception as e: + print("ERROR: %s" % e, file=sys.stderr, flush=True) + sys.exit(1) diff --git a/scripts/make_overlay.py b/scripts/make_overlay.py new file mode 100644 index 0000000..5ea209f --- /dev/null +++ b/scripts/make_overlay.py @@ -0,0 +1,131 @@ +#!/usr/bin/env python3 +"""xv 程序化包装素材:0 积分、零第三方依赖,纯标准库写 PNG。 + +生成 HUD 横/竖细光分隔 与 落版(光环 / 光束 / 星点)底图。 +文字不烧进图里(避免生成模型重绘文字),后期由 ASS 叠加。 + +用法: python3 tools/make_overlay.py +""" +import math +import os +import random +import struct +import zlib + +def _find_root(): + """工作空间根:MANJU_ROOT > cwd 向上找 config/pipeline.json > 脚本上级。""" + env = os.environ.get("MANJU_ROOT") + if env: + return os.path.abspath(os.path.expanduser(env)) + d = os.getcwd() + while True: + if os.path.isfile(os.path.join(d, "config", "pipeline.json")): + return d + nd = os.path.dirname(d) + if nd == d: + break + d = nd + return os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + + +ROOT = _find_root() +OUT = os.path.join(ROOT, "assets", "overlay") +W, H = 720, 1280 + + +def write_png(path, w, h, rows): + raw = b"".join(b"\x00" + r for r in rows) + + def chunk(t, d): + return struct.pack(">I", len(d)) + t + d + struct.pack(">I", zlib.crc32(t + d) & 0xFFFFFFFF) + + data = b"\x89PNG\r\n\x1a\n" + data += chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0)) + data += chunk(b"IDAT", zlib.compress(raw, 9)) + data += chunk(b"IEND", b"") + with open(path, "wb") as f: + f.write(data) + return len(data) + + +def clamp(v): + return max(0, min(255, int(v))) + + +def outro(): + """深蓝径向底 + 三层光环 + 中心光束 + 星点,供 zoompan 缓推。""" + random.seed(20102026) + cx, cy = W * 0.5, H * 0.46 + rows = [] + for y in range(H): + row = bytearray() + for x in range(W): + dx, dy = (x - cx) / W, (y - cy) / H + d = math.sqrt(dx * dx + dy * dy) + # 基底:越靠中心越亮的深蓝 + base = math.exp(-d * 3.1) + r = 4 + 16 * base + g = 10 + 46 * base + b = 22 + 92 * base + # 三层同心光环(高斯窄带) + for radius, strength in ((0.155, 1.0), (0.225, 0.62), (0.30, 0.30)): + ring = math.exp(-((d - radius) / 0.010) ** 2) * strength + r += 26 * ring + g += 120 * ring + b += 190 * ring + # 中心光束:竖直柔和光柱 + beam = math.exp(-((x - cx) / 46.0) ** 2) * math.exp(-abs(y - cy) / 520.0) + g += 20 * beam + b += 42 * beam + # 上下压暗 + fade = 1.0 - 0.55 * (abs(y / H - 0.5) * 2) ** 3 + row += bytes((clamp(r * fade), clamp(g * fade), clamp(b * fade))) + rows.append(bytes(row)) + # 星点(在已生成的行上补点) + pix = [bytearray(r) for r in rows] + for _ in range(230): + x, y = random.randrange(W), random.randrange(H) + a = random.uniform(0.25, 0.9) + for dy in range(-1, 2): + for dx in range(-1, 2): + xx, yy = x + dx, y + dy + if 0 <= xx < W and 0 <= yy < H: + k = a if (dx, dy) == (0, 0) else a * 0.22 + i = xx * 3 + pix[yy][i] = clamp(pix[yy][i] + 40 * k) + pix[yy][i + 1] = clamp(pix[yy][i + 1] + 150 * k) + pix[yy][i + 2] = clamp(pix[yy][i + 2] + 220 * k) + return [bytes(r) for r in pix] + + +def hud(vertical): + """细光分隔:横排为水平线,竖排为垂直线;带两端渐隐。""" + rows = [] + for y in range(H): + row = bytearray() + for x in range(W): + if vertical: + t = abs(x - W * 0.5) + fade = max(0.0, 1.0 - abs(y / H - 0.5) * 1.7) + else: + t = abs(y - H * 0.5) + fade = max(0.0, 1.0 - abs(x / W - 0.5) * 1.7) + glow = math.exp(-(t / 2.2) ** 2) * fade + row += bytes((clamp(6 * glow), clamp(110 * glow), clamp(190 * glow))) + rows.append(bytes(row)) + return rows + + +def main(): + os.makedirs(OUT, exist_ok=True) + for name, rows in (("outro.png", outro()), + ("hud_flow.png", hud(False)), + ("hud_seed.png", hud(True))): + p = os.path.join(OUT, name) + n = write_png(p, W, H, rows) + print(" %s %dx%d %d KB" % (name, W, H, n // 1024)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/manju.py b/scripts/manju.py new file mode 100644 index 0000000..1eef7a9 --- /dev/null +++ b/scripts/manju.py @@ -0,0 +1,275 @@ +#!/usr/bin/env python3 +"""manju 工作空间命令行入口 —— 零第三方依赖。 + + setup 初始化工作空间(建目录/配置/复制脚本,仅从技能包运行) + validate <30_shots.json> 校验分镜清单(ERROR 退出 1) + hash 计算提示词 sha256 前 8 位 + hash-file 计算提示词文件 sha256 前 8 位 + manifest <30_shots.json> 生成/更新 50_manifest.json,保留已有 attempts + init 新建一集目录骨架 + +用法:先在工作空间根用技能包的 manju.py 运行 setup,之后一律用 tools/manju.py。 +""" + +import json +import sys +from datetime import datetime +from pathlib import Path + +def _find_root(): + """工作空间根:MANJU_ROOT > cwd 向上找 config/pipeline.json > 脚本上级。""" + import os as _os + env = _os.environ.get("MANJU_ROOT") + if env: + return Path(env).expanduser().absolute() + d = Path.cwd().absolute() + for p in (d, *d.parents): + if (p / "config" / "pipeline.json").is_file(): + return p + return Path(__file__).absolute().parent.parent + + +ROOT = _find_root() +sys.path.insert(0, str(Path(__file__).absolute().parent)) +from validate_shots import validate, shot_hash # noqa: E402 + + +def cmd_validate(args): + if len(args) != 1: + return "用法: xv.py validate <30_shots.json>" + errors, warns, summary = validate(args[0]) + print(f"[{summary.get('episode', '?')}] {summary['shots']} 镜 / {summary['total']}s " + f"(目标 {summary['target']}s) ERROR={summary['errors']} WARN={summary['warns']}") + for item in errors: + print(f" ERROR {item}") + for item in warns: + print(f" WARN {item}") + if not errors: + print(" 校验通过(WARN 需在生成前逐条确认)") + return 1 if errors else 0 + + +def cmd_hash(args): + if not args: + return "用法: xv.py hash <提示词原文>" + print(shot_hash(" ".join(args))) + return 0 + + +def cmd_hash_file(args): + if len(args) != 1: + return "用法: xv.py hash-file " + print(shot_hash(Path(args[0]).read_text(encoding="utf-8"))) + return 0 + + +def cmd_manifest(args): + if len(args) != 1: + return "用法: xv.py manifest <30_shots.json>" + src = Path(args[0]).resolve() + data = json.loads(src.read_text(encoding="utf-8")) + out = src.parent / "50_manifest.json" + old = {} + if out.exists(): + try: + old = {r["shotId"]: r for r in json.loads(out.read_text(encoding="utf-8")).get("shots", [])} + except Exception as exc: + return f"已有 manifest 无法解析,未覆盖:{exc}" + + records = [] + for s in data["shots"]: + sid = s["shotId"] + rec = old.get(sid, {"shotId": sid, "attempts": []}) + prompt_hash = s.get("promptHash") or "" + pf = s.get("promptFile") + if pf: + fp = src.parent / pf + if fp.exists(): + actual = shot_hash(fp.read_text(encoding="utf-8")) + if prompt_hash and prompt_hash != actual: + return f"{sid}: promptHash 与 {pf} 不符,请先修正再生成 manifest" + prompt_hash = actual + rec.update({ + "promptFile": pf or "", + "promptHash": prompt_hash, + "status": s.get("status", "planned"), + "duration": s.get("duration"), + "refs": s.get("refs", []), + }) + rec.setdefault("attempts", []) + records.append(rec) + + doc = { + "episode": data.get("episode"), + "source": "30_shots.json", + "updatedAt": datetime.now().isoformat(timespec="seconds"), + "note": "attempts 只追加不覆盖:每次提交记录提示词快照、完整参数、参考、返回与实际文件", + "shots": records, + } + out.write_text(json.dumps(doc, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + print(f"已写入 {out.relative_to(ROOT)}({len(records)} 镜,保留历史 attempts)") + return 0 + + +BRIEF = """# EP{ep} 任务卡 + +项目: +时长: +镜头数: +核心冲突: +角色: +画风: +禁忌:(按本项目 policy 清单填写,必填) + +> 禁忌栏必写。重编不是缩写;每镜必须能回溯到 10_events.md 的 E##。 +""" + +EVENTS = """# EP{ep} 源节拍账本 + +一行一个 E##,30–60 字,只写影响主线的动作,不复述整段对话。 +每个会改变剧情状态的提示词句子都必须映射回这里的 E##。 + +- E01|待填写:谁做了什么 → 造成什么结果 → 情绪 → 预估秒数 +""" + +SCRIPT = """# EP{ep} 剧本 / 旁白 + +待填写。旁白全文逐字写入 `30_shots.json` 的 `line`,配音阶段按实测时长回填 `duration`。 +""" + +SHOTS = """{{ + "episode": "{ep}", + "brief": "00_brief.md", + "targetDuration": 5.06, + "tolerance": 3.0, + "shots": [ + {{ + "shotId": "S01", + "eventIds": ["E01"], + "scene": "待填写", + "shotType": "中景", + "subject": "待填写", + "angle": "正面", + "visual": "待填写:可见画面,不写抽象情绪", + "line": "", + "duration": 5.06, + "characters": [], + "refs": [], + "motion": "轻微呼吸 + 单一缓推", + "promptFile": "40_prompts/S01.md", + "continuity": {{ "relation": "reset", "initialState": "待填写:本段绝对初始状态" }}, + "status": "planned" + }} + ] +}} +""" + +PROMPT = """S01|E01|时长:5.06s|模型:wan2.2-i2v-a14b|432x768 / 81帧 / 16fps / 4-step + +[首帧锚] +待填写 + +[首帧锁定] +待填写 + +[画面] +待填写 + +[轻运动] +待填写 + +[正向锁] +待填写 + +[文字锁] +无字幕、无额外屏幕文字、无后期叠字、无水印;实体文字保持参考资产,不新增、不改写、不重绘 + +[Avoid] +待填写 +""" + + +def cmd_setup(args): + """在工作空间根建骨架;必须从技能包目录的 manju.py 运行(需要 assets/)。""" + if args: + return "用法: manju.py setup(在工作空间根目录运行,无参数)" + root = Path.cwd().absolute() + skill = Path(__file__).absolute().parent.parent + assets = skill / "assets" + if not (assets / "config.template.json").is_file(): + return ("找不到技能包 assets/config.template.json;" + "请用技能包内的 scripts/manju.py 运行 setup") + cfg = root / "config" / "pipeline.json" + if cfg.exists(): + return f"已存在,未改动:{cfg.relative_to(root)}" + + for d in ("config", "projects", "work", "renders", "logs", + "assets/characters", "assets/scenes", "assets/props", + "assets/style", "assets/overlay", "assets/templates", "tools"): + (root / d).mkdir(parents=True, exist_ok=True) + + cfg.write_text((assets / "config.template.json").read_text(encoding="utf-8"), + encoding="utf-8") + for name in ("policy.template.md", "brief.template.md", "events.template.md", + "script.template.md", "prompts.template.md", "shot.schema.json"): + src = assets / name + if src.is_file(): + (root / "assets" / "templates" / name).write_text( + src.read_text(encoding="utf-8"), encoding="utf-8") + + copied = [] + for src in sorted((skill / "scripts").glob("*.py")): + dst = root / "tools" / src.name + if not dst.exists(): + dst.write_text(src.read_text(encoding="utf-8"), encoding="utf-8") + copied.append(dst.name) + + print(f"已初始化 {root}") + print(f" 配置:{cfg.relative_to(root)}(请填 workspace / videoModel.endpoint)") + print(f" 脚本:{len(copied)} 个已复制到 tools/") + print(" 下一步:编辑 config/pipeline.json,然后 python3 tools/manju.py init EPxx") + return 0 + + +def cmd_init(args): + if len(args) != 1: + return "用法: manju.py init " + ep = args[0] + if not ep.startswith("EP") or len(ep) != 4: + return "集号需为 EPxx,例如 EP02" + target = ROOT / "projects" / ep + if target.exists(): + return f"已存在,未改动:{target}" + (target / "40_prompts").mkdir(parents=True) + (target / "00_brief.md").write_text(BRIEF.format(ep=ep), encoding="utf-8") + (target / "10_events.md").write_text(EVENTS.format(ep=ep), encoding="utf-8") + (target / "20_script.md").write_text(SCRIPT.format(ep=ep), encoding="utf-8") + (target / "30_shots.json").write_text(SHOTS.format(ep=ep), encoding="utf-8") + (target / "40_prompts/S01.md").write_text(PROMPT, encoding="utf-8") + print(f"已创建 {target.relative_to(ROOT)},运行 tools/manju.py validate projects/{ep}/30_shots.json 校验") + return 0 + + +COMMANDS = { + "setup": cmd_setup, + "validate": cmd_validate, + "hash": cmd_hash, + "hash-file": cmd_hash_file, + "manifest": cmd_manifest, + "init": cmd_init, +} + + +def main(argv): + if len(argv) < 2 or argv[1] not in COMMANDS: + print(__doc__) + return 2 + result = COMMANDS[argv[1]](argv[2:]) + if isinstance(result, str): + print(result, file=sys.stderr) + return 2 + return result + + +if __name__ == "__main__": + sys.exit(main(sys.argv)) diff --git a/scripts/render.py b/scripts/render.py new file mode 100644 index 0000000..d29d840 --- /dev/null +++ b/scripts/render.py @@ -0,0 +1,271 @@ +#!/usr/bin/env python3 +"""manju 缝合器:已采用片段 + 配音 + 字幕 + HUD 标注 + 落版 -> 成片。 + +规格 720x1280 / 30fps / H.264+AAC。字幕取 30_shots.json 的 line 原文, +按标点折 1–3 行;HUD 文字全片只标一次(一横一竖);落版 zoompan 缓推。 +去水印用 crop 底部带 + 居中填充,不用 drawbox。 + +用法: python3 tools/render.py projects/EPxx/30_shots.json +""" +import argparse +import json +import os +import re +import subprocess +import sys + +def _find_root(): + """工作空间根:MANJU_ROOT > cwd 向上找 config/pipeline.json > 脚本上级。""" + env = os.environ.get("MANJU_ROOT") + if env: + return os.path.abspath(os.path.expanduser(env)) + d = os.getcwd() + while True: + if os.path.isfile(os.path.join(d, "config", "pipeline.json")): + return d + nd = os.path.dirname(d) + if nd == d: + break + d = nd + return os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + + +ROOT = _find_root() +CFG = json.load(open(os.path.join(ROOT, "config", "pipeline.json"), encoding="utf-8")) +OUT = CFG["output"] + + +def ff(): + import imageio_ffmpeg + return imageio_ffmpeg.get_ffmpeg_exe() + + +def run(args, quiet=True): + cmd = [ff(), "-hide_banner", "-loglevel", "error", "-y"] + args + r = subprocess.run(cmd, capture_output=True, text=True) + if r.returncode != 0: + print("FFMPEG FAILED:\n" + " ".join(cmd) + "\n" + r.stderr[-3000:], file=sys.stderr) + raise SystemExit(1) + return r + + +def probe(path): + r = subprocess.run([ff(), "-hide_banner", "-i", str(path)], + stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, text=True) + m = re.search(r"Duration:\s*(\d+):(\d+):([\d.]+)", r.stderr) + dur = (int(m.group(1)) * 3600 + int(m.group(2)) * 60 + float(m.group(3))) if m else None + return dur, r.stderr + + +def ts(t): + h = int(t // 3600) + m = int(t % 3600 // 60) + s = t % 60 + return "%d:%02d:%05.2f" % (h, m, s) + + +PUNCT = set(",。;!?、,.;!?") + + +def wrap_line(text, maxlen=11): + """按标点折 1–3 行;标点永不落单,永远附着在前一行末尾。""" + parts = [p for p in re.split(r"([,。;!?、,.;!?])", text) if p] + lines, cur = [], "" + for p in parts: + if p in PUNCT: + # 标点直接并入当前行(哪怕略超 maxlen),绝不起新行 + cur += p + elif len(cur) + len(p) <= maxlen or not cur: + cur += p + else: + lines.append(cur) + cur = p + if cur: + lines.append(cur) + # 若最后一行只有标点(理论上不会发生),并入上一行 + if len(lines) > 1 and all(c in PUNCT for c in lines[-1]): + lines[-2] += lines.pop() + if len(lines) > 3: + # 极端长句:均分三段,切点尽量落在标点后 + n = len(text) + cuts = [i + 1 for i, c in enumerate(text) if c in PUNCT] + best = None + for a in cuts: + for b in cuts: + if a < b < n and max(a, b - a, n - b) < (best[0] if best else 999): + best = (max(a, b - a, n - b), a, b) + if best and best[0] <= maxlen + 3: + _, a, b = best + lines = [text[:a], text[a:b], text[b:]] + else: + step = maxlen + lines = [text[i:i + step] for i in range(0, n, step)][:3] + return "\\N".join(lines) + + +ASS_HEAD = """[Script Info] +ScriptType: v4.00+ +PlayResX: 720 +PlayResY: 1280 +ScaledBorderAndShadow: yes +WrapStyle: 2 + +[V4+ Styles] +Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding +Style: Default,PingFang SC,46,&H00FFFFFF,&H00FFFFFF,&H000C1420,&H90000000,0,0,0,0,100,100,0,0,1,3,1,2,60,60,150,1 +Style: HUD,PingFang SC,26,&H00E8D4A8,&H00E8D4A8,&H000C1420,&H90000000,0,0,0,0,100,100,2,0,1,2,0,7,40,40,60,1 + +[Events] +Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text +""" + + +def build_ass(shots, ass_path): + lines = [ASS_HEAD] + t = 0.0 + for i, s in enumerate(shots): + d = float(s["duration"]) + body = wrap_line(s["line"]) + lines.append("Dialogue: 0,%s,%s,Default,,0,0,0,,{\\fad(250,250)}%s\n" % + (ts(t + 0.22), ts(t + d - 0.22), body)) + if i == 0: # 横排 HUD:全片只标一次 + lines.append("Dialogue: 0,%s,%s,HUD,,0,0,0,,{\\an7\\pos(56,92)\\fad(400,400)}2010 / 机房\n" % + (ts(t + 0.5), ts(t + 2.8))) + if i == len(shots) - 1: # 竖排 HUD:全片只标一次 + lines.append("Dialogue: 0,%s,%s,HUD,,0,0,0,,{\\an5\\pos(650,340)\\fad(400,400)}二\\N〇\\N二\\N六\n" % + (ts(t + 0.5), ts(t + 2.8))) + t += d + with open(ass_path, "w", encoding="utf-8") as f: + f.writelines(lines) + return t + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("shots") + ap.add_argument("--crop-bottom", type=int, default=0, + help="底部水印带高度;A14B 实测无水印,默认 0(不裁画面)") + ap.add_argument("--outro-seconds", type=float, default=2.0) + ap.add_argument("--name", default=None) + a = ap.parse_args() + + shots_path = os.path.abspath(a.shots) + data = json.load(open(shots_path, encoding="utf-8")) + ep = data["episode"] + shots = data["shots"] + vid_dir = os.path.join(ROOT, "work", ep, "videos") + aud_dir = os.path.join(ROOT, "work", ep, "audio") + tmp = os.path.join(ROOT, "work", ep, "render") + os.makedirs(tmp, exist_ok=True) + runs_path = os.path.join(vid_dir, "a14b_runs.json") + runs = json.load(open(runs_path, encoding="utf-8")) if os.path.exists(runs_path) else {} + + # 1) 逐段标准化:去水印带 -> 居中填充到 720x1280 -> 30fps -> clone 补足精确时长 + norm = [] + for i, s in enumerate(shots, 1): + sid = s["shotId"] + rec = runs.get(sid) + if not rec: + print("ERROR: 缺 %s 的 A14B 产物记录" % sid, file=sys.stderr) + return 1 + src = os.path.join(ROOT, rec["out"]) + if not os.path.exists(src): + print("ERROR: 缺视频 %s" % src, file=sys.stderr) + return 1 + d = float(s["duration"]) + keep = float(s.get("keepSeconds", d)) + dst = os.path.join(tmp, "norm_%s.mp4" % sid) + base = ("crop=iw:ih-%d:0:0,scale=%d:%d:force_original_aspect_ratio=increase," + "crop=%d:%d,setsar=1,fps=%d" % + (a.crop_bottom, OUT["width"], OUT["height"], OUT["width"], OUT["height"], + OUT["fps"])) + if keep < d - 0.05: + # 局部修正:只采用前 keep 秒(漂移前的稳定段),慢放到目标时长 + tail = ("trim=duration=%.3f,setpts=PTS*%.6f,fps=%d," + "trim=duration=%.3f,setpts=PTS-STARTPTS,format=yuv420p" % + (keep, d / keep, OUT["fps"], d)) + note = "采用前 %.2fs 慢放至 %.2fs" % (keep, d) + else: + # 常规:A14B 约 5.06s,clone 尾帧补足精确时长 + tail = ("tpad=stop_mode=clone:stop_duration=3," + "trim=duration=%.3f,setpts=PTS-STARTPTS,format=yuv420p" % d) + note = "全段" + vf = base + "," + tail + run(["-i", src, "-vf", vf, "-an", "-c:v", "libx264", "-preset", "veryfast", + "-crf", "19", "-r", str(OUT["fps"]), dst]) + norm.append(dst) + print(" 标准化 %s -> %.2fs(%s)" % (sid, d, note), flush=True) + + # 2) 落版:光环 / 光束 / 星点 + zoompan 缓推,无文字 + outro_png = os.path.join(ROOT, "assets", "overlay", "outro.png") + outro = os.path.join(tmp, "outro.mp4") + frames = int(a.outro_seconds * OUT["fps"]) + zvf = ("zoompan=z='min(zoom+0.0008,1.10)':x='iw/2-(iw/zoom/2)':" + "y='ih/2-(ih/zoom/2)':d=%d:s=%dx%d:fps=%d,format=yuv420p" % + (frames, OUT["width"], OUT["height"], OUT["fps"])) + run(["-loop", "1", "-framerate", str(OUT["fps"]), "-i", outro_png, + "-vf", zvf, "-t", str(a.outro_seconds), "-an", "-c:v", "libx264", + "-preset", "veryfast", "-crf", "19", outro]) + print(" 落版 %.2fs" % a.outro_seconds, flush=True) + + # 3) 字幕 + HUD(一横一竖,各一次) + ass_path = os.path.join(tmp, "ep01.ass") + main_dur = build_ass(shots, ass_path) + total = main_dur + a.outro_seconds + print(" 字幕 %d 条 / 主片 %.2fs / 总长 %.2fs" % (len(shots), main_dur, total), flush=True) + + # 4) 一次性拼接 + 烧字幕(单次编码,避免多次重编码掉画质) + video_only = os.path.join(tmp, "video_final.mp4") + ins = [] + for p in norm + [outro]: + ins += ["-i", p] + concat_in = "".join("[%d:v]" % i for i in range(len(norm) + 1)) + fc = ("%sconcat=n=%d:v=1:a=0[cat];[cat]ass=%s:fontsdir=/System/Library/Fonts[v]" % + (concat_in, len(norm) + 1, ass_path)) + run(ins + ["-filter_complex", fc, "-map", "[v]", "-an", "-c:v", "libx264", + "-preset", "veryfast", "-crf", "19", "-pix_fmt", OUT["pix_fmt"], + "-r", str(OUT["fps"]), video_only]) + + # 5) 音轨:每段配音补静音到本镜时长,再补落版静音 + audio_m4a = os.path.join(tmp, "audio_final.m4a") + ains, parts, labels = [], [], [] + for i, s in enumerate(shots): + p = os.path.join(aud_dir, "vo_%02d.mp3" % (i + 1)) + if not os.path.exists(p): + print("ERROR: 缺配音 %s" % p, file=sys.stderr) + return 1 + ains += ["-i", p] + parts.append("[%d:a]apad,atrim=duration=%.3f,aresample=48000[a%d]" % + (i, float(s["duration"]), i)) + labels.append("[a%d]" % i) + afc = ";".join(parts) + ";" + "".join(labels) + \ + "concat=n=%d:v=0:a=1,apad,atrim=duration=%.3f[aout]" % (len(shots), total) + run(ains + ["-filter_complex", afc, "-map", "[aout]", "-c:a", "aac", + "-b:a", "192k", "-ar", "48000", audio_m4a]) + + # 6) 封装 + out_name = a.name or "%s_成片_v2.mp4" % ep + out_path = os.path.join(ROOT, "renders", out_name) + os.makedirs(os.path.dirname(out_path), exist_ok=True) + run(["-i", video_only, "-i", audio_m4a, "-c", "copy", "-shortest", + "-movflags", "+faststart", out_path]) + + dur, info = probe(out_path) + streams = [l.strip() for l in info.splitlines() if "Stream #" in l] + report = {"output": os.path.relpath(out_path, ROOT), "duration": dur, + "mainDuration": round(main_dur, 2), "outroSeconds": a.outro_seconds, + "bytes": os.path.getsize(out_path), "streams": streams, + "shots": [{"shotId": s["shotId"], "duration": s["duration"], + "video": runs[s["shotId"]]["out"]} for s in shots]} + with open(os.path.join(tmp, "render_report.json"), "w", encoding="utf-8") as f: + json.dump(report, f, ensure_ascii=False, indent=2) + print("\n=== 成片 ===", flush=True) + print(out_path, flush=True) + print("时长 %.2fs | %.2f MB" % (dur or 0, os.path.getsize(out_path) / 1048576), flush=True) + for l in streams: + print(" " + l, flush=True) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/review.py b/scripts/review.py new file mode 100644 index 0000000..a041d45 --- /dev/null +++ b/scripts/review.py @@ -0,0 +1,134 @@ +#!/usr/bin/env python3 +"""xv 批量审片:从 A14B 片段抽首/中/末帧,按九宫格联系表分组。 + +用法: + python3 tools/review.py projects/EPxx/30_shots.json --group 1 # S01-S09 联系表 + python3 tools/review.py projects/EPxx/30_shots.json --group 2 # S10-S18 联系表 + python3 tools/review.py projects/EPxx/30_shots.json --only S13,S15 + +联系表每格 = 一段视频的首/中/末三帧横排,便于看漂移轨迹; +9 段一表(3 行 × 3 列),输出到 work//review/contact_G.png。 +""" +import argparse +import json +import os +import subprocess +import sys + +def _find_root(): + """工作空间根:MANJU_ROOT > cwd 向上找 config/pipeline.json > 脚本上级。""" + env = os.environ.get("MANJU_ROOT") + if env: + return os.path.abspath(os.path.expanduser(env)) + d = os.getcwd() + while True: + if os.path.isfile(os.path.join(d, "config", "pipeline.json")): + return d + nd = os.path.dirname(d) + if nd == d: + break + d = nd + return os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + + +ROOT = _find_root() + + +def ff(): + import imageio_ffmpeg + return imageio_ffmpeg.get_ffmpeg_exe() + + +def run(args): + r = subprocess.run([ff(), "-hide_banner", "-loglevel", "error", "-y"] + args, + capture_output=True, text=True) + if r.returncode != 0: + print("FFMPEG FAILED:\n" + r.stderr[-2000:], file=sys.stderr) + raise SystemExit(1) + return r + + +def frame(path, at, out): + run(["-ss", "%.2f" % at, "-i", path, "-frames:v", "1", + "-vf", "scale=180:-1", out]) + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("shots") + ap.add_argument("--group", type=int, default=0, help="1=S01-S09, 2=S10-S18, 0=不限配合 --only") + ap.add_argument("--only", default="", help="逗号分隔镜号") + a = ap.parse_args() + + shots_path = os.path.abspath(a.shots) + data = json.load(open(shots_path, encoding="utf-8")) + ep = data["episode"] + vid_dir = os.path.join(ROOT, "work", ep, "videos") + rev_dir = os.path.join(ROOT, "work", ep, "review") + os.makedirs(rev_dir, exist_ok=True) + runs = json.load(open(os.path.join(vid_dir, "a14b_runs.json"), encoding="utf-8")) + + wanted = set(x.strip() for x in a.only.split(",") if x.strip()) + if a.group == 1: + wanted = {"S%02d" % i for i in range(1, 10)} + elif a.group == 2: + wanted = {"S%02d" % i for i in range(10, 19)} + + cells, labels = [], [] + for s in data["shots"]: + sid = s["shotId"] + if sid not in wanted: + continue + rec = runs.get(sid) + if not rec: + print("SKIP %s: 无产物记录" % sid, flush=True) + continue + src = os.path.join(ROOT, rec["out"]) + if not os.path.exists(src): + print("SKIP %s: 文件不存在" % sid, flush=True) + continue + d = float(s["duration"]) + cell_frames = [] + for k, at in enumerate((0.4, d / 2, d - 0.4)): + f = os.path.join(rev_dir, "_%s_f%d.png" % (sid, k)) + frame(src, at, f) + cell_frames.append(f) + # 三帧横排成一行 + row = os.path.join(rev_dir, "_%s_row.png" % sid) + ins = [] + for f in cell_frames: + ins += ["-i", f] + run(ins + ["-filter_complex", "[0:v][1:v][2:v]hstack=inputs=3[r]", + "-map", "[r]", row]) + cells.append(row) + labels.append(sid) + print(" %s -> 3 帧" % sid, flush=True) + + if not cells: + print("无可审片片段", file=sys.stderr) + return 1 + + # every 9 cells -> one 3x3 contact sheet + batch = a.group or 1 + for start in range(0, len(cells), 9): + part = cells[start:start + 9] + tag = "G%d" % batch if a.group else "custom" + if a.group: + batch += 1 + while len(part) < 9: + part.append(part[-1]) # 补齐 3x3,重复最后格 + ins = [] + for p in part: + ins += ["-i", p] + fc = ("[0:v][1:v][2:v]vstack=inputs=3[r0];" + "[3:v][4:v][5:v]vstack=inputs=3[r1];" + "[6:v][7:v][8:v]vstack=inputs=3[r2];" + "[r0][r1][r2]vstack=inputs=3[out]") + out = os.path.join(rev_dir, "contact_%s.png" % tag) + run(ins + ["-filter_complex", fc, "-map", "[out]", out]) + print("联系表:", os.path.relpath(out, ROOT), "| 格顺序:", " ".join(labels[start:start + 9]), flush=True) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/selftest_cleanup.py b/scripts/selftest_cleanup.py new file mode 100644 index 0000000..55574b6 --- /dev/null +++ b/scripts/selftest_cleanup.py @@ -0,0 +1,311 @@ +#!/usr/bin/env python3 +"""ai-manju 清理链路自检:扩展插件纯逻辑 + 客户端端到端 mock ComfyUI。 + +用法:python3 tools/selftest_cleanup.py +零第三方依赖;起一个本地 HTTPServer 模拟 ComfyUI 的标准接口与 manju-cleanup 扩展, +用 subprocess 跑 cleanup_comfyui.py 的 dry-run / apply,断言「只删自己发起的任务」。 +""" +import importlib.util +import json +import os +import subprocess +import sys +import tempfile +import threading +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer + +HERE = os.path.dirname(os.path.abspath(__file__)) +CLEANUP = os.path.join(HERE, "cleanup_comfyui.py") +# 扩展插件本体在技能包的 assets/ 下;setup 复制脚本到工作空间 tools/ 时, +# assets/ 只有模板、没有扩展源码 —— 所以要往回找技能包,容错退化为跳过扩展用例。 +PLUGIN_CANDIDATES = [ + os.path.join(HERE, "..", "assets", "comfyui-manju-cleanup", "__init__.py"), + os.path.join(HERE, "..", "..", "assets", "comfyui-manju-cleanup", "__init__.py"), + os.path.join(HERE, "..", "..", "..", "assets", "comfyui-manju-cleanup", "__init__.py"), +] +PLUGIN = next((p for p in PLUGIN_CANDIDATES if os.path.isfile(p)), PLUGIN_CANDIDATES[0]) +FAIL = [] + + +def check(cond, msg): + if not cond: + FAIL.append(msg) + print(" [FAIL] " + msg) + else: + print(" [ok] " + msg) + + +def test_plugin(): + print("\n== 扩展插件纯逻辑 ==") + spec = importlib.util.spec_from_file_location("manju_cleanup_node", PLUGIN) + m = importlib.util.module_from_spec(spec) + spec.loader.exec_module(m) + root = tempfile.mkdtemp(prefix="manju-selftest-") + out, inp = os.path.join(root, "output"), os.path.join(root, "input") + os.makedirs(os.path.join(out, "video")) + os.makedirs(inp) + roots = {"output": out, "input": inp, "temp": os.path.join(root, "temp")} + os.makedirs(roots["temp"]) + paths = [os.path.join(out, "a.mp4"), os.path.join(out, "video", "b.mp4"), + os.path.join(inp, "head.png")] + for p in paths: + open(p, "wb").write(b"x" * 512) + + f = lambda n, s="", t="output": {"filename": n, "subfolder": s, "type": t} + + def item(cid, outs, imgs=()): + g = {str(i): {"class_type": "LoadImage", "inputs": {"image": n}} + for i, n in enumerate(imgs)} + return {"prompt": [1, "pid", g, {"client_id": cid}, {}], + "outputs": {"9": {"images": outs}}} + + own = item("manju-i2v-ab12", [f("a.mp4"), f("b.mp4", "video"), + f("head.png", "", "input")], ["head.png"]) + other = item("xv-someone", [f("a.mp4")]) + hist = {"p1": own, "p2": other} + check(m.resolve(roots, f("../etc/passwd"))[1] == "path escape refused", "路径 .. 逃逸被拒") + check(m.resolve(roots, f("/etc/passwd"))[1] == "absolute path refused", "绝对路径被拒") + check(m.resolve(roots, f("b.mp4", "video"))[1] == "", "正常子目录可解析") + r = m.build_report(hist, roots, ["p1", "p2"], client_ids=["manju-i2v-ab12"], dry_run=True) + check(r["summary"]["shared"] == 1, "被别人引用的产物判 shared") + check(r["summary"]["skipped-input"] == 1, "purge_input 默认关闭") + check(r["summary"]["refused"] == 1, "未归属 pid 的文件被拒") + check(all(os.path.isfile(p) for p in paths), "dry-run 零副作用") + r = m.build_report(hist, roots, ["p1"], client_ids=["manju-i2v-ab12"], dry_run=False) + check(os.path.isfile(paths[0]) and not os.path.isfile(paths[1]), "只删独占产物") + check(os.path.isfile(paths[2]), "上传素材默认保留") + r = m.build_report({"p1": own}, roots, ["p1"], client_ids=["manju-i2v-ab12"], + dry_run=False, purge_input=True) + check(not os.path.isfile(paths[2]), "purge_input=true 才删输入") + check(not m.build_report(hist, roots, ["p1"], dry_run=False)["pids"]["p1"]["owned"], + "无归属凭证 fail-closed") + check(m.build_report(hist, roots, ["p1"], prefixes=["manju-"], dry_run=True) + ["pids"]["p1"]["owned"], "前缀白名单可用") + check(not m.build_report({}, roots, ["nope"], client_ids=["x"], dry_run=False) + ["pids"]["nope"]["exists"], "history 无记录时拒绝猜测文件名") + + # 回归(2026-11-12):ComfyUI 0.45 内存态 history 布局 = [extra_data, number, prompt], + # client_id 在 prompt[0];HTTP 序列化布局 = [number, prompt_id, prompt, extra_data, [...]], + # client_id 在 prompt[3]。扩展两种布局都要能读,否则 0.45 上归属校验全失败、清不掉。 + open(os.path.join(out, "mem.mp4"), "wb").write(b"x" * 512) # 专属文件,避免被前面用例删掉 + item_mem = {"prompt": [{"client_id": "manju-i2v-mem01", "create_time": 1}, 0, + {"1": {"class_type": "LoadImage"}}], + "outputs": {"9": {"images": [{"filename": "mem.mp4", "type": "output"}]}}} + item_http = {"prompt": [0, "pid", {"1": {"class_type": "LoadImage"}}, + {"client_id": "manju-i2v-http01"}, ["9"]], + "outputs": {"9": {"images": [{"filename": "http.mp4", "type": "output"}]}}} + check(m.client_id_of(item_mem) == "manju-i2v-mem01", "内存态[0]布局能读 client_id") + check(m.client_id_of(item_http) == "manju-i2v-http01", "HTTP态[3]布局能读 client_id") + r_mem = m.build_report({"m1": item_mem}, roots, ["m1"], prefixes=["manju-"], dry_run=True) + check(r_mem["pids"]["m1"]["owned"] is True, "内存态布局归属判定通过") + check(r_mem["pids"]["m1"]["files"][0]["status"] == "dry-run", "内存态布局产物进入预览") + r_reject = m.build_report({"m1": item_mem}, roots, ["m1"], prefixes=["other-"], dry_run=True) + check(r_reject["pids"]["m1"]["owned"] is False, "非 manju- 前缀仍拒绝") + + +class Server: + """mock ComfyUI:官方 /api/* + manju-cleanup 扩展。""" + + def __init__(self): + self.state = {"deleted": set(), "purge": [], "history_posts": [], + "free": 0, "node": True} + self.items = { + "own-pid": {"prompt": [1, "own-pid", {}, {"client_id": "manju-i2v-ab12"}, {}], + "outputs": {"9": {"images": [ + {"filename": "own.mp4", "subfolder": "video", "type": "output"}]}}}, + "other-pid": {"prompt": [1, "other-pid", {}, {"client_id": "xv-someone"}, {}], + "outputs": {"9": {"images": [ + {"filename": "other.mp4", "subfolder": "video", "type": "output"}]}}}, + } + h = self + + class H(BaseHTTPRequestHandler): + def log_message(self, *a): + pass + + def _send(self, code, obj=None): + body = b"" if obj is None else json.dumps(obj).encode() + self.send_response(code) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(len(body))) + self.end_headers() + if body: + self.wfile.write(body) + + def do_GET(self): + p = self.path + if p == "/api/system_stats": + return self._send(200, {"system": {"comfyui_version": "test"}}) + if p == "/api/manju/cleanup/ping" and h.state["node"]: + return self._send(200, {"ok": True, "version": "1.0.0", + "roots": {"output": "/tmp/fake"}}) + if p == "/api/queue": + return self._send(200, {"queue_running": [], "queue_pending": []}) + if p.startswith("/api/history/"): + pid = p.rsplit("/", 1)[-1] + if pid in h.state["deleted"] or pid not in h.items: + return self._send(200, {}) + return self._send(200, {pid: h.items[pid]}) + return self._send(404, {}) + + def do_POST(self): + n = int(self.headers.get("Content-Length") or 0) + raw = self.rfile.read(n) if n else b"{}" + try: + body = json.loads(raw) + except ValueError: + body = {} + p = self.path + if p == "/api/manju/cleanup/purge" and h.state["node"]: + pids = body.get("pids") or [] + allowed = set(body.get("client_ids") or []) + prefixes = body.get("owner_prefixes") or [] + h.state["purge"].append({"dry_run": body.get("dry_run"), + "pids": list(pids)}) + out = {} + for pid in pids: + it = h.items.get(pid, {}) + cid = it.get("prompt", [None] * 4)[3].get("client_id", "") + owned = cid in allowed or any(cid.startswith(x) for x in prefixes) + rows = [] + for fn in ("own.mp4", "other.mp4"): + rows.append({"type": "output", "subfolder": "video", + "filename": fn, "bytes": 100, + "status": "dry-run" if body.get("dry_run") else "deleted", + "reason": ""}) + out[pid] = {"exists": bool(it), "client_id": cid, "owned": owned, + "owner_reason": "" if owned else "not in whitelist", + "files": rows[:1]} + return self._send(200, {"ok": True, "pids": out, "summary": {}}) + if p == "/api/history": + h.state["history_posts"].append(list(body.get("delete") or [])) + h.state["deleted"].update(body.get("delete") or []) + return self._send(200) + if p == "/api/queue": + return self._send(200) + if p == "/api/free": + h.state["free"] += 1 + return self._send(200) + return self._send(404, {}) + + self.httpd = ThreadingHTTPServer(("127.0.0.1", 0), H) + self.port = self.httpd.server_address[1] + self.thread = threading.Thread(target=self.httpd.serve_forever, daemon=True) + + def __enter__(self): + self.thread.start() + return self + + def __exit__(self, *a): + self.httpd.shutdown() + self.httpd.server_close() + + +def run_clean(root, *args): + env = dict(os.environ, MANJU_ROOT=root) + return subprocess.run([sys.executable, CLEANUP] + list(args), + env=env, capture_output=True, text=True, timeout=60) + + +def test_client(): + print("\n== 客户端端到端(本地 mock ComfyUI)==") + root = tempfile.mkdtemp(prefix="manju-selftest-ws-") + os.makedirs(os.path.join(root, "config")) + vid = os.path.join(root, "work", "EP01", "videos") + os.makedirs(vid) + for name in ("S01.mp4", "S02.mp4"): + open(os.path.join(vid, name), "wb").write(b"x" * 2048) + with Server() as srv: + host = "http://127.0.0.1:%d" % srv.port + cfg = {"videoModel": {"endpoint": host}, + "cleanup": {"minBytes": 100, "apiBase": "/api", + "ownerPrefixes": ["manju-"], "requireOwner": True}} + json.dump(cfg, open(os.path.join(root, "config", "pipeline.json"), "w")) + json.dump({"S01": {"out": "work/EP01/videos/S01.mp4", "promptId": "own-pid", + "clientId": "manju-i2v-ab12"}, + "S02": {"out": "work/EP01/videos/S02.mp4", "promptId": "other-pid"}}, + open(os.path.join(vid, "a14b_runs.json"), "w")) + + dry = run_clean(root, "--ep", "EP01") + check(dry.returncode == 0, "dry-run 退出码 0:" + dry.stderr[:120]) + check(not srv.state["deleted"] and not srv.state["history_posts"], + "dry-run 不删任何记录") + check(all(x["dry_run"] is True for x in srv.state["purge"]), + "dry-run 只发 purge(dry_run=true)") + check("⛔ 拒绝(非本人任务)" in dry.stdout, "非本人任务被明确标注拒绝") + check("✅ 自己的任务" in dry.stdout, "本人任务通过归属校验") + + srv.state["purge"].clear() + app = run_clean(root, "--ep", "EP01", "--apply", "--free") + check(app.returncode == 0, "apply 退出码 0:" + app.stderr[:120]) + check(srv.state["deleted"] == {"own-pid"}, + "只删自己的 history 记录(实际 %s)" % sorted(srv.state["deleted"])) + check(srv.state["history_posts"] and srv.state["history_posts"][0] == ["own-pid"], + "POST /api/history 的 delete 列表不含别人的 pid") + real = [x for x in srv.state["purge"] if x["dry_run"] is False] + check(len(real) == 1 and real[0]["pids"] == ["own-pid"], + "purge 真删只对本人 pid 调用一次") + order = [("purge" if x["dry_run"] is False else "preview") for x in srv.state["purge"]] + check(order and order[-1] == "purge", "purge 在删记录之前(依赖 history 反查)") + check(srv.state["free"] == 1, "/free 整批只调一次") + check("已确认(删前有 → 删后无)" in app.stdout, "删后复核通过") + + # 未装扩展:自动降级,不报错 + srv.state["node"] = False + srv.state["deleted"].clear() + srv.state["history_posts"].clear() + srv.state["purge"].clear() + json.dump({"S01": {"out": "work/EP01/videos/S01.mp4", "promptId": "own-pid", + "clientId": "manju-i2v-ab12"}}, + open(os.path.join(vid, "a14b_runs.json"), "w")) + deg = run_clean(root, "--ep", "EP01") + check(deg.returncode == 0, "未装扩展时降级不报错:" + deg.stderr[:120]) + check("未安装 → 降级" in deg.stdout, "明确提示降级路线") + check(not srv.state["purge"], "未装扩展不发 purge 请求") + + +def test_anchor_ledger(): + """回归:裸 --out 出的锚图,台账写在图片同目录,清理必须能扫到。 + + 2026-11-13 修的漏洞:ledger_paths() 只认固定路径 work//images/t2i_runs.json, + 而 submit_t2i.py 把台账写在 os.path.dirname(out) —— 锚图的台账落在 + assets/characters/t2i_runs.json,于是锚图产物永远留在服务端。 + """ + print("\n== 锚图台账扫描(回归) ==") + root = tempfile.mkdtemp(prefix="manju-selftest-anchor-") + os.makedirs(os.path.join(root, "config")) + os.makedirs(os.path.join(root, "assets", "characters")) + open(os.path.join(root, "assets", "characters", "ling.png"), "wb").write(b"x" * 2048) + host = "http://127.0.0.1:1" # 不真的连,只看扫没扫到 + cfg = {"imageModel": {"endpoint": host}, + "cleanup": {"minBytes": 100, "apiBase": "/api", + "ownerPrefixes": ["manju-"], "requireOwner": True}} + json.dump(cfg, open(os.path.join(root, "config", "pipeline.json"), "w")) + json.dump({"ling.png": {"out": "assets/characters/ling.png", "promptId": "anchor-pid", + "clientId": "manju-t2i-abcd1234", "endpoint": host}}, + open(os.path.join(root, "assets", "characters", "t2i_runs.json"), "w")) + + spec = importlib.util.spec_from_file_location("cc_anchor", CLEANUP) + m = importlib.util.module_from_spec(spec) + spec.loader.exec_module(m) + found = [p for _, p, _ in m.ledger_paths(root, "")] + check(any(p.endswith(os.path.join("assets", "characters", "t2i_runs.json")) for p in found), + "锚图台账(图片同目录)能被扫到") + + jobs, skipped = m.gather(root, cfg, cfg.get("cleanup", cfg), "", set(), []) + check(any(j["pid"] == "anchor-pid" for j in jobs), + "无 --ep 时锚图任务进入待清列表") + check(any(j["pid"] == "anchor-pid" for j in jobs) and + all(j["host"].rstrip("/") == host.rstrip("/") for j in jobs if j["pid"] == "anchor-pid"), + "端点取台账里记录的实际端点,不靠配置猜") + + +if __name__ == "__main__": + if os.path.isfile(PLUGIN): + test_plugin() + else: + print("\n== 扩展插件纯逻辑 ==\n [skip] 扩展源码不在技能包内(工作空间副本),只跑客户端用例") + test_client() + test_anchor_ledger() + print("\n%s (%d 项失败)" % ("ALL PASS" if not FAIL else "FAILED", len(FAIL))) + sys.exit(1 if FAIL else 0) diff --git a/scripts/submit_i2v.py b/scripts/submit_i2v.py new file mode 100644 index 0000000..743bcd9 --- /dev/null +++ b/scripts/submit_i2v.py @@ -0,0 +1,291 @@ +#!/usr/bin/env python3 +"""manju I2V:ComfyUI 图生视频提交器(默认适配 Wan2.2 A14B)。 + +零第三方依赖;模型参数来自 config/pipeline.json,运动提示词来自 40_prompts/Sxx.i2v.txt, +产物只写 work//videos/Sxx_.mp4。换模型需改下方 UNET/LORA 常量。 + +用法: + python3 tools/submit_i2v.py projects/EPxx/30_shots.json --only S01 + python3 tools/submit_i2v.py projects/EPxx/30_shots.json +""" +import argparse +import hashlib +import json +import mimetypes +import os +import sys +import time +import urllib.error +import urllib.parse +import urllib.request +import uuid + +def _find_root(): + """工作空间根:MANJU_ROOT > cwd 向上找 config/pipeline.json > 脚本上级。""" + env = os.environ.get("MANJU_ROOT") + if env: + return os.path.abspath(os.path.expanduser(env)) + d = os.getcwd() + while True: + if os.path.isfile(os.path.join(d, "config", "pipeline.json")): + return d + nd = os.path.dirname(d) + if nd == d: + break + d = nd + return os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + + +ROOT = _find_root() +CFG = json.load(open(os.path.join(ROOT, "config", "pipeline.json"), encoding="utf-8")) +VM = CFG["videoModel"] +HOST = VM["endpoint"] + +# 本机代理会把明文 HTTP 请求改写成 text/html,必须显式绕过 +opener = urllib.request.build_opener(urllib.request.ProxyHandler({})) + +UNET_HIGH = "wan2.2_i2v_high_noise_14B_fp8_scaled.safetensors" +UNET_LOW = "wan2.2_i2v_low_noise_14B_fp8_scaled.safetensors" +LORA_HIGH = "wan2.2_i2v_lightx2v_4steps_lora_v1_high_noise.safetensors" +LORA_LOW = "wan2.2_i2v_lightx2v_4steps_lora_v1_low_noise.safetensors" +CLIP = "umt5_xxl_fp8_e4m3fn_scaled.safetensors" +VAE = "wan_2.1_vae.safetensors" + +NEGATIVE = ("blurry, low quality, deformed, distorted face, face morphing, identity drift, " + "extra limbs, extra fingers, text, letters, subtitles, watermark, logo, brand, UI, " + "jitter, flicker, morphing, fast camera movement, camera shake, oversaturated, " + "cartoonish deformation, sudden rotation") + + +def request(method, path, data=None, headers=None, timeout=90): + r = urllib.request.Request(HOST + path, data=data, method=method, headers=headers or {}) + with opener.open(r, timeout=timeout) as resp: + return resp.read(), resp.headers.get("Content-Type", "") + + +def get_json(path, timeout=90): + raw, _ = request("GET", path, timeout=timeout) + return json.loads(raw) + + +def health(): + """按启动参数预检,不按 RAM 硬挡(旧坑:--force-fp16 把 fp8 升 fp16 撞 4GB cgroup)。""" + d = get_json("/system_stats", timeout=20) + info = d.get("system", {}) + argv = info.get("argv", []) or [] + if "--force-fp16" in argv and os.environ.get("A14B_FORCE_CAPACITY") != "1": + raise RuntimeError("服务端仍带 --force-fp16:fp8 权重被升成 fp16 会 OOM,请先修服务端") + return info.get("comfyui_version", "unknown") + + +def upload_image(path): + boundary = "----xv" + uuid.uuid4().hex + fn = os.path.basename(path) + ctype = mimetypes.guess_type(fn)[0] or "image/png" + payload = open(path, "rb").read() + head = ("--" + boundary + "\r\n" + 'Content-Disposition: form-data; name="image"; filename="' + fn + '"\r\n' + "Content-Type: " + ctype + "\r\n\r\n").encode() + tail = ("\r\n--" + boundary + "\r\n" + 'Content-Disposition: form-data; name="overwrite"\r\n\r\ntrue\r\n' + "--" + boundary + "--\r\n").encode() + raw, _ = request("POST", "/upload/image", data=head + payload + tail, + headers={"Content-Type": "multipart/form-data; boundary=" + boundary}, + timeout=180) + d = json.loads(raw) + name = d.get("name") or d.get("filename") + if not name: + raise RuntimeError("上传首帧失败: " + raw.decode(errors="replace")[:500]) + return name + + +def build_workflow(image_name, prompt, width, height, frames, seed, steps, cfg, fps, prefix): + """双专家 MoE:high_noise 跑前 2 步,low_noise 跑后 2 步,各挂对应 4-step LoRA。 + + 节点图对齐 0.45(30113) 与 0.38(30112) 都能跑的官方模板: + * ModelSamplingSD3 shift=5 必须挂(缺了画面发糊/漂移) + * UNETLoader.weight_dtype="default" 用文件原生 fp8(别强制 fp8_e4m3fn 再转一次) + * SaveVideo.format="auto"(该字段是动态组合,取值 auto/mp4/mkv/webm; + 传 "video/h264-mp4" 这类组合串会被静默丢弃) + """ + half = steps // 2 + return { + "1": {"class_type": "UNETLoader", "inputs": {"unet_name": UNET_HIGH, "weight_dtype": "default"}}, + "2": {"class_type": "UNETLoader", "inputs": {"unet_name": UNET_LOW, "weight_dtype": "default"}}, + "3": {"class_type": "LoraLoaderModelOnly", "inputs": {"model": ["1", 0], "lora_name": LORA_HIGH, "strength_model": 1.0}}, + "4": {"class_type": "LoraLoaderModelOnly", "inputs": {"model": ["2", 0], "lora_name": LORA_LOW, "strength_model": 1.0}}, + "5": {"class_type": "CLIPLoader", "inputs": {"clip_name": CLIP, "type": "wan"}}, + "6": {"class_type": "CLIPTextEncode", "inputs": {"text": prompt, "clip": ["5", 0]}}, + "7": {"class_type": "CLIPTextEncode", "inputs": {"text": NEGATIVE, "clip": ["5", 0]}}, + "8": {"class_type": "VAELoader", "inputs": {"vae_name": VAE}}, + "9": {"class_type": "LoadImage", "inputs": {"image": image_name}}, + "10": {"class_type": "ImageScale", "inputs": {"image": ["9", 0], "upscale_method": "lanczos", + "width": width, "height": height, "crop": "center"}}, + "11": {"class_type": "WanImageToVideo", "inputs": { + "positive": ["6", 0], "negative": ["7", 0], "vae": ["8", 0], + "width": width, "height": height, "length": frames, "batch_size": 1, + "start_image": ["10", 0]}}, + "12": {"class_type": "ModelSamplingSD3", "inputs": {"model": ["3", 0], "shift": 5.0}}, + "13": {"class_type": "ModelSamplingSD3", "inputs": {"model": ["4", 0], "shift": 5.0}}, + "14": {"class_type": "KSamplerAdvanced", "inputs": { + "model": ["12", 0], "add_noise": "enable", "noise_seed": seed, + "steps": steps, "cfg": cfg, "sampler_name": "euler", "scheduler": "simple", + "positive": ["11", 0], "negative": ["11", 1], "latent_image": ["11", 2], + "start_at_step": 0, "end_at_step": half, "return_with_leftover_noise": "enable"}}, + "15": {"class_type": "KSamplerAdvanced", "inputs": { + "model": ["13", 0], "add_noise": "disable", "noise_seed": seed, + "steps": steps, "cfg": cfg, "sampler_name": "euler", "scheduler": "simple", + "positive": ["11", 0], "negative": ["11", 1], "latent_image": ["14", 0], + "start_at_step": half, "end_at_step": steps, "return_with_leftover_noise": "disable"}}, + "16": {"class_type": "VAEDecode", "inputs": {"samples": ["15", 0], "vae": ["8", 0]}}, + "17": {"class_type": "CreateVideo", "inputs": {"images": ["16", 0], "fps": fps}}, + "18": {"class_type": "SaveVideo", "inputs": {"video": ["17", 0], "filename_prefix": prefix, + "format": "auto"}}, + } + + +def submit(wf, client_id): + body = json.dumps({"prompt": wf, "client_id": client_id}).encode() + try: + raw, _ = request("POST", "/prompt", data=body, + headers={"Content-Type": "application/json"}, timeout=90) + except urllib.error.HTTPError as e: + detail = e.read().decode(errors="replace") + raise RuntimeError("工作流校验失败 (HTTP %s): %s" % (e.code, detail[:3000])) + d = json.loads(raw) + if d.get("node_errors"): + raise RuntimeError("节点错误: " + json.dumps(d["node_errors"], ensure_ascii=False)[:3000]) + return d.get("prompt_id") + + +def wait(prompt_id, timeout): + t0 = time.time() + gaps = 0 + while True: + try: + d = get_json("/history/" + urllib.parse.quote(prompt_id), timeout=30) + except Exception as e: + gaps += 1 + print(" ...服务暂不可达 (%d): %s" % (gaps, str(e)[:90]), flush=True) + if gaps >= 8 or time.time() - t0 > timeout: + raise TimeoutError("等待出片超时或服务重启") + time.sleep(8) + continue + gaps = 0 + item = d.get(prompt_id) + if item: + status = item.get("status", {}) + if status.get("completed") or item.get("outputs"): + if status.get("status_str") == "error": + raise RuntimeError("渲染失败: " + json.dumps(status.get("messages", []), ensure_ascii=False)[:2000]) + return item + if time.time() - t0 > timeout: + raise TimeoutError("等待出片超时 %s 秒" % timeout) + time.sleep(4) + + +def find_video(item): + for out in (item.get("outputs") or {}).values(): + for key in ("images", "videos", "gifs", "video"): + for f in out.get(key, []) or []: + if isinstance(f, dict) and f.get("filename", "").lower().endswith((".mp4", ".webm", ".mkv")): + return f + raise RuntimeError("未找到视频输出: " + json.dumps(item.get("outputs"), ensure_ascii=False)[:1500]) + + +def download(f, out): + q = urllib.parse.urlencode({"filename": f["filename"], "subfolder": f.get("subfolder", ""), + "type": f.get("type", "output")}) + raw, _ = request("GET", "/view?" + q, timeout=300) + os.makedirs(os.path.dirname(os.path.abspath(out)) or ".", exist_ok=True) + with open(out, "wb") as fh: + fh.write(raw) + return len(raw) + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("shots", help="30_shots.json 路径") + ap.add_argument("--only", default="", help="只跑指定镜,逗号分隔") + ap.add_argument("--force", action="store_true", help="已存在也重跑") + ap.add_argument("--timeout", type=int, default=1800) + ap.add_argument("--cleanup", action="store_true", + help="导出后清理 ComfyUI 的 history/queue 记录与产物(等价于 cleanup.auto=true)") + ap.add_argument("--no-cleanup", action="store_true", + help="本次强制不清理,覆盖 config 里的 cleanup.auto") + a = ap.parse_args() + do_cleanup = (a.cleanup or CFG.get("cleanup", {}).get("auto", False)) and not a.no_cleanup + + shots_path = os.path.abspath(a.shots) + data = json.load(open(shots_path, encoding="utf-8")) + ep = data["episode"] + base = os.path.dirname(shots_path) + img_dir = os.path.join(ROOT, "work", ep, "images") + vid_dir = os.path.join(ROOT, "work", ep, "videos") + os.makedirs(vid_dir, exist_ok=True) + log_path = os.path.join(vid_dir, "a14b_runs.json") + runs = json.load(open(log_path, encoding="utf-8")) if os.path.exists(log_path) else {} + + print("ComfyUI:", health(), flush=True) + width, height = VM["width"], VM["height"] + frames, steps, fps = VM["frames"], VM["steps"], VM["fps"] + wanted = set(x.strip() for x in a.only.split(",") if x.strip()) + jobs = [s for s in data["shots"] if not wanted or s["shotId"] in wanted] + + for s in jobs: + sid = s["shotId"] + image = os.path.join(img_dir, sid + ".png") + prompt_file = os.path.join(base, "40_prompts", sid + ".i2v.txt") + if not os.path.exists(image): + print("SKIP %s: 缺首帧 %s" % (sid, image), file=sys.stderr) + continue + if not os.path.exists(prompt_file): + print("SKIP %s: 缺运动提示词 %s" % (sid, prompt_file), file=sys.stderr) + continue + prompt = open(prompt_file, encoding="utf-8").read().strip() + h8 = hashlib.sha256(prompt.encode("utf-8")).hexdigest()[:8] + out = os.path.join(vid_dir, "%s_%s.mp4" % (sid, h8)) + if os.path.exists(out) and os.path.getsize(out) > 100000 and not a.force: + print("SKIP %s: 已存在 %s" % (sid, os.path.basename(out)), flush=True) + continue + seed = int(hashlib.sha256((sid + prompt).encode()).hexdigest()[:8], 16) % (2 ** 31) + t0 = time.time() + print("[%s] %s -> %s | %dx%d %d帧 seed=%d" % + (time.strftime("%H:%M:%S"), sid, os.path.basename(out), width, height, frames, seed), flush=True) + name = upload_image(image) + wf = build_workflow(name, prompt, width, height, frames, seed, steps, 1.0, fps, + "video/xv_%s_%s" % (ep, sid)) + # client_id 会被 ComfyUI 持久化在 history 项 prompt[3],是清理时的归属凭证 + cid = "manju-i2v-" + uuid.uuid4().hex[:8] + pid = submit(wf, cid) + item = wait(pid, a.timeout) + size = download(find_video(item), out) + runs[sid] = {"out": os.path.relpath(out, ROOT), "promptHash": h8, "seed": seed, + "promptId": pid, "clientId": cid, "image": os.path.relpath(image, ROOT), + "width": width, "height": height, "frames": frames, "fps": fps, + "steps": steps, "seconds": round(time.time() - t0, 1), + "bytes": size, "at": time.strftime("%Y-%m-%d %H:%M:%S")} + with open(log_path, "w", encoding="utf-8") as f: + json.dump(runs, f, ensure_ascii=False, indent=2) + print("[ok] %s %.2fMB in %.1fs" % (sid, size / 1048576, time.time() - t0), flush=True) + if do_cleanup: + try: + sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) + from cleanup_comfyui import after_export + print("[cleanup] " + after_export(ROOT, pid, HOST, log_path, sid, out, cid), + flush=True) + except Exception as e: + # 成片已安全落地;清理失败只提示,绝不影响主流程 + print("[cleanup] FAILED %s(成片已落地,可稍后跑 cleanup_comfyui.py 补清)" + % e, file=sys.stderr, flush=True) + + print("DONE %d/%d" % (sum(1 for s in jobs if s["shotId"] in runs), len(jobs)), flush=True) + return 0 + + +if __name__ == "__main__": + try: + sys.exit(main()) + except Exception as e: + print("ERROR: %s" % e, file=sys.stderr, flush=True) + sys.exit(1) diff --git a/scripts/submit_t2i.py b/scripts/submit_t2i.py new file mode 100644 index 0000000..e2f67e9 --- /dev/null +++ b/scripts/submit_t2i.py @@ -0,0 +1,408 @@ +#!/usr/bin/env python3 +"""manju T2I:内网 MiniMax H3-Image 文生图提交器。 + +零第三方依赖。读 config/pipeline.json 的 imageModel,输出 PNG 到 +work//images/.png —— 正是 tools/submit_i2v.py 期望的首帧路径。 +服务端明文 HTTP,必须绕过本机代理(见 references/models.md §3.2)。 + +用法: + python3 tools/submit_t2i.py --ep EP01 --shot S01 --prompt-file 40_prompts/S01.t2i.txt + python3 tools/submit_t2i.py --prompt "A lone figure on a misty pier, ..." --out assets/characters/ling.png + python3 tools/submit_t2i.py --ep EP01 --shot S03 --width 4096 --height 4096 --force + +约定:给 --ep/--shot 时,未给 --prompt-file 则读 +projects//40_prompts/.t2i.txt(出图提示词,与 .i2v.txt 运动提示词分开留档)。 + +★ 权重自适应(2026-11-13) +------------------------ +不同端点的 H3-Image 量化权重名不同,写死必然踩坑: + + DCU 192.168.1.24:30120 -> minimax_h3_image_pruned_w4a8.safetensors + K8s 192.168.1.30:30113 -> minimax_h3_image_pruned_int8_convrot.safetensors + +所以本脚本**不写死权重名**:提交前读目标端点的 /object_info/, +按优先级挑一个真正存在的(见 UNET_PRIORITY)。端点换权重、或将来新增第三个 +端点,不用改代码就能跑。 + +⚠️ 两条线的坑完全不同,别互相照搬: + - DCU(ROCm gfx928):**不要用 int8_convrot** —— convrot 的 rint 有 bug → NaN → 纯黑图。 + - K8s(CUDA sm_75):**没有 w4a8**(w4a8 的 CUDA 加速路径要求 sm_80),只有 int8_convrot。 + 该端点跑在 4Gi cgroup 硬限里,靠 22 处内存墙补丁 + 显存换入换出才跑得动, + 详见 references/models.md §2.1。 +""" +import argparse +import hashlib +import json +import os +import sys +import time +import uuid +import urllib.parse +import urllib.request + +DEFAULTS = { + "endpoint": "http://192.168.1.30:30113", + "width": 2048, + "height": 2048, + "steps": 6, + "seed": 42, + "prefix": "H3IMG", + "timeout": 3600, +} + +# 权重候选,按优先级。实际用哪个由目标端点 /object_info 决定。 +UNET_PRIORITY = [ + "minimax_h3_image_pruned_w4a8.safetensors", # DCU 30120 + "minimax_h3_image_pruned_int8_convrot.safetensors", # K8s 30113 +] +CLIP_PRIORITY = [ + "qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors", +] +VAE_PRIORITY = [ + "minimax_h3_image_vae_fp16.safetensors", +] + +# 本机代理会把明文 HTTP 响应改写成 text/html,必须显式绕过 +opener = urllib.request.build_opener(urllib.request.ProxyHandler({})) + + +def pick_weight(host, node_type, priority): + """从端点的 /object_info/ 里挑一个真实存在的权重名。 + + 端点换权重不用改代码 —— 这是本脚本能在 DCU / K8s 两套基础设施上通吃的关键。 + 探不到就回退到 priority[0],让服务端报 node_errors(比静默猜错好)。 + """ + try: + d = get(host, "/object_info/" + node_type, timeout=20) + node = d.get(node_type) or {} + req = ((node.get("input") or {}).get("required") or {}) + available = [] + for key in ("unet_name", "clip_name", "vae_name"): + v = req.get(key) + if isinstance(v, list) and v and isinstance(v[0], list): + available = list(v[0]) + break + for name in priority: + if name in available: + return name + # 端点上有别的 H3-Image 权重(将来新增档位)—— 认前缀兜底 + for name in available: + if name.startswith("minimax_h3_image"): + return name + return priority[0] + except Exception: + return priority[0] + + +def find_root(): + """工作空间根:MANJU_ROOT > cwd 向上找 config/pipeline.json > 脚本上级。""" + env = os.environ.get("MANJU_ROOT") + if env: + return os.path.abspath(os.path.expanduser(env)) + d = os.getcwd() + while True: + if os.path.isfile(os.path.join(d, "config", "pipeline.json")): + return d + nd = os.path.dirname(d) + if nd == d: + break + d = nd + return os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + + +def load_cfg(root): + cfg = dict(DEFAULTS) + p = os.path.join(root, "config", "pipeline.json") + if os.path.isfile(p): + cfg.update(json.load(open(p, encoding="utf-8")).get("imageModel", {})) + return cfg + + +def get(host, path, timeout=60): + return json.loads(opener.open(host + path, timeout=timeout).read()) + + +def post(host, path, payload, timeout=60): + req = urllib.request.Request(host + path, data=json.dumps(payload).encode(), + headers={"Content-Type": "application/json"}) + return json.loads(opener.open(req, timeout=timeout).read()) + + +def build(prompt, width, height, steps, seed, prefix, unet, clip, vae): + """实机 /object_info 核对:width/height step=32;vae、images 为 optional。 + + unet/clip/vae 由 pick_weight() 从目标端点探出来,不写死。 + """ + return { + "1": {"class_type": "UNETLoader", + "inputs": {"unet_name": unet, "weight_dtype": "default"}}, + "2": {"class_type": "CLIPLoader", + "inputs": {"clip_name": clip, "type": "minimax", "device": "default"}}, + "3": {"class_type": "VAELoader", "inputs": {"vae_name": vae}}, + "4": {"class_type": "MiniMaxH3ImageConditioning", + "inputs": {"clip": ["2", 0], "vae": ["3", 0], "prompt": prompt, + "width": width, "height": height}}, + "5": {"class_type": "ConditioningZeroOut", "inputs": {"conditioning": ["4", 0]}}, + "6": {"class_type": "KSampler", + "inputs": {"model": ["1", 0], "seed": seed, "steps": steps, "cfg": 1.0, + "sampler_name": "euler", "scheduler": "simple", + "positive": ["4", 0], "negative": ["5", 0], + "latent_image": ["4", 1], "denoise": 1.0}}, + "7": {"class_type": "VAEDecode", "inputs": {"samples": ["6", 0], "vae": ["3", 0]}}, + "8": {"class_type": "SaveImage", "inputs": {"images": ["7", 0], "filename_prefix": prefix}}, + } + + +def wait(host, pid, timeout): + t0 = time.time() + gaps = 0 + while True: + try: + d = get(host, "/history/" + urllib.parse.quote(pid), timeout=30) + except Exception as e: + gaps += 1 + print(" ...服务暂不可达 (%d): %s" % (gaps, str(e)[:90]), flush=True) + if gaps >= 8 or time.time() - t0 > timeout: + raise TimeoutError("等待出图超时或服务重启") + time.sleep(8) + continue + gaps = 0 + item = d.get(pid) + if item: + st = item.get("status", {}) + errs = [m for m in st.get("messages", []) if m[0] == "execution_error"] + if errs: + raise RuntimeError("渲染失败: " + json.dumps(errs, ensure_ascii=False)[:2000]) + if st.get("completed") and item.get("outputs"): + return item + if time.time() - t0 > timeout: + raise TimeoutError("等待出图超时 %s 秒" % timeout) + time.sleep(5) + + +def find_image(item): + for out in (item.get("outputs") or {}).values(): + for f in out.get("images", []) or []: + if isinstance(f, dict) and f.get("filename"): + return f + raise RuntimeError("未找到图片输出: " + json.dumps(item.get("outputs"), ensure_ascii=False)[:1200]) + + +def download(host, f, out): + q = urllib.parse.urlencode({"filename": f["filename"], + "subfolder": f.get("subfolder", ""), + "type": f.get("type", "output")}) + raw = opener.open(host + "/view?" + q, timeout=300).read() + os.makedirs(os.path.dirname(os.path.abspath(out)) or ".", exist_ok=True) + with open(out, "wb") as fh: + fh.write(raw) + return len(raw) + + +def sanity_check(path): + """出图自检:全黑 / 全白 / 单色 一律判失败。 + + 为什么必须有这一步(2026-11-13 实测踩过): + H3-Image 在量化档位不对时会**出图成功但内容是纯黑/单色** —— + ComfyUI 侧 status.completed=True、outputs 有文件,不报错。 + 不自检就会把废图当成成品记进台账,后面审片才发现。 + + 只用标准库读 PNG:解 IHDR 拿尺寸,采样像素算颜色数/亮度/标准差。 + """ + try: + with open(path, "rb") as fh: + data = fh.read() + if data[:8] != b"\x89PNG\r\n\x1a\n": + return "not-png" + # PNG IHDR: 8 字节签名 + 4 长度 + 4 类型 + 8 宽高 + w = int.from_bytes(data[16:20], "big") + h = int.from_bytes(data[20:24], "big") + # 解 IDAT(PNG 用 zlib deflate) + import zlib + idat = b"" + i = 8 + while i < len(data) - 8: + ln = int.from_bytes(data[i:i + 4], "big") + typ = data[i + 4:i + 8] + if typ == b"IDAT": + idat += data[i + 8:i + 8 + ln] + elif typ == b"IEND": + break + i += 12 + ln + if not idat: + return "no-idat" + raw = zlib.decompress(idat) + # 假设 8bit RGB/RGBA,逐行反滤波(filter 0..4) + bpp = 4 if len(raw) >= h * (1 + w * 4) else 3 + stride = w * bpp + prev = bytearray(stride) + colors = set() + bright_sum = 0.0 + bright_sq = 0.0 + cnt = 0 + pos = 0 + for _y in range(h): + ft = raw[pos] + pos += 1 + line = bytearray(raw[pos:pos + stride]) + pos += stride + if ft == 1: + for x in range(bpp, stride): + line[x] = (line[x] + line[x - bpp]) & 0xFF + elif ft == 2: + for x in range(stride): + line[x] = (line[x] + prev[x]) & 0xFF + elif ft == 3: + for x in range(stride): + a = line[x - bpp] if x >= bpp else 0 + line[x] = (line[x] + ((a + prev[x]) >> 1)) & 0xFF + elif ft == 4: + for x in range(stride): + a = line[x - bpp] if x >= bpp else 0 + c = prev[x - bpp] if x >= bpp else 0 + b = prev[x] + p = a + b - c + pa, pb, pc = abs(p - a), abs(p - b), abs(p - c) + pr = a if (pa <= pb and pa <= pc) else (b if pb <= pc else c) + line[x] = (line[x] + pr) & 0xFF + prev = line + # 采样:每 8 行取一行,避免大图太慢 + for x in range(0, stride, bpp * 7): + px = (line[x], line[x + 1], line[x + 2]) + colors.add(px) + v = (px[0] * 299 + px[1] * 587 + px[2] * 114) / 1000.0 + bright_sum += v + bright_sq += v * v + cnt += 1 + if cnt == 0: + return "empty" + mean = bright_sum / cnt + std = (max(0.0, bright_sq / cnt - mean * mean)) ** 0.5 + # 判定:颜色数极少 或 标准差极小 → 近乎纯色(黑/白/单色) + if len(colors) <= 8: + return "single-color(%d colors)" % len(colors) + if std < 3.0: + return "flat(std=%.2f, %d colors)" % (std, len(colors)) + return "ok(%dx%d, %d colors, mean=%.1f, std=%.1f)" % (w, h, len(colors), mean, std) + except Exception as e: + return "check-failed(%s)" % str(e)[:60] + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--ep", default="", help="集号,如 EP01") + ap.add_argument("--shot", default="", help="镜号,如 S01") + ap.add_argument("--prompt", default="") + ap.add_argument("--prompt-file", default="") + ap.add_argument("--out", default="", help="输出 PNG;默认 work//images/.png") + ap.add_argument("--width", type=int, default=0) + ap.add_argument("--height", type=int, default=0) + ap.add_argument("--steps", type=int, default=0) + ap.add_argument("--seed", type=int, default=-1) + ap.add_argument("--timeout", type=int, default=0) + ap.add_argument("--force", action="store_true", help="已存在也重跑") + ap.add_argument("--cleanup", action="store_true", + help="导出后清理 ComfyUI 的 history/queue 记录与产物(等价于 cleanup.auto=true)") + ap.add_argument("--no-cleanup", action="store_true", + help="本次强制不清理,覆盖 config 里的 cleanup.auto") + a = ap.parse_args() + + root = find_root() + cfg = load_cfg(root) + host = str(cfg["endpoint"]).rstrip("/") + full = json.load(open(os.path.join(root, "config", "pipeline.json"), encoding="utf-8")) \ + if os.path.isfile(os.path.join(root, "config", "pipeline.json")) else {} + do_cleanup = (a.cleanup or full.get("cleanup", {}).get("auto", False)) and not a.no_cleanup + + pf = a.prompt_file + if not pf and a.ep and a.shot and not a.prompt: + pf = os.path.join(root, "projects", a.ep, "40_prompts", a.shot + ".t2i.txt") + prompt = open(pf, encoding="utf-8").read().strip() if pf else a.prompt.strip() + if not prompt: + return "需要 --prompt / --prompt-file,或备好 projects//40_prompts/.t2i.txt" + + width = a.width or int(cfg["width"]) + height = a.height or int(cfg["height"]) + steps = a.steps or int(cfg["steps"]) + seed = a.seed if a.seed >= 0 else int(cfg["seed"]) + timeout = a.timeout or int(cfg["timeout"]) + if width % 32 or height % 32: + return "宽高必须 32 对齐(当前 %dx%d)" % (width, height) + + if a.out: + out = a.out + elif a.ep and a.shot: + out = os.path.join(root, "work", a.ep, "images", a.shot + ".png") + else: + out = os.path.join(root, "h3_image_out.png") + + h8 = hashlib.sha256(prompt.encode("utf-8")).hexdigest()[:8] + if os.path.exists(out) and os.path.getsize(out) > 100000 and not a.force: + print("SKIP 已存在 %s(--force 可重跑)" % out, flush=True) + return 0 + + sysinfo = get(host, "/system_stats", timeout=20).get("system", {}) + unet = pick_weight(host, "UNETLoader", UNET_PRIORITY) + clip = pick_weight(host, "CLIPLoader", CLIP_PRIORITY) + vae = pick_weight(host, "VAELoader", VAE_PRIORITY) + print("ComfyUI %s @ %s | %dx%d %d步 seed=%d | promptHash=%s" % + (sysinfo.get("comfyui_version", "?"), host, width, height, steps, seed, h8), flush=True) + print("weights unet=%s clip=%s vae=%s" % (unet, clip, vae), flush=True) + + graph = build(prompt, width, height, steps, seed, str(cfg["prefix"]), unet, clip, vae) + t0 = time.time() + # client_id 会被 ComfyUI 持久化在 history 项 prompt[3],是清理时的归属凭证 + cid = "manju-t2i-" + uuid.uuid4().hex[:8] + r = post(host, "/prompt", {"prompt": graph, "client_id": cid}) + if r.get("node_errors"): + raise RuntimeError("节点错误: " + json.dumps(r["node_errors"], ensure_ascii=False)[:3000]) + pid = r["prompt_id"] + print("[submit] prompt_id=%s -> %s" % (pid, out), flush=True) + + item = wait(host, pid, timeout) + size = download(host, find_image(item), out) + verdict = sanity_check(out) + bad = not verdict.startswith("ok") + if bad: + # 废图(纯黑/单色)照样落地,但要显式报警 —— 不能让「completed」等于「可用」 + print("[SANITY] FAIL %s -> %s" % (out, verdict), file=sys.stderr, flush=True) + print("[SANITY] 出图成功但内容异常。H3-Image 在量化档位不对时会静默出纯色图:" + "DCU 禁用 int8_convrot;K8s(30113) 只有 int8_convrot 可用。" + "先看 models.md §2.1 的量化档位表,别急着重跑。", file=sys.stderr, flush=True) + else: + print("[SANITY] %s -> %s" % (out, verdict), flush=True) + + log_path = os.path.join(os.path.dirname(os.path.abspath(out)), "t2i_runs.json") + runs = json.load(open(log_path, encoding="utf-8")) if os.path.exists(log_path) else {} + key = (a.ep + "/" + a.shot) if (a.ep and a.shot) else os.path.basename(out) + runs[key] = {"out": os.path.relpath(out, root), "promptHash": h8, "prompt": prompt, + "model": unet, "endpoint": host, "width": width, "height": height, + "steps": steps, "seed": seed, "promptId": pid, "clientId": cid, + "bytes": size, "sanity": verdict, "sanityOK": not bad, + "seconds": round(time.time() - t0, 1), + "at": time.strftime("%Y-%m-%d %H:%M:%S")} + with open(log_path, "w", encoding="utf-8") as f: + json.dump(runs, f, ensure_ascii=False, indent=2) + print("[ok] %.2f MB in %.1fs" % (size / 1048576, time.time() - t0), flush=True) + if do_cleanup and bad: + # 废图不清服务端 —— 保留 history 与产物当排查证据(量化档位/权重问题要看原始产物) + print("[cleanup] SKIP 自检未通过,保留服务端记录与产物供排查", flush=True) + elif do_cleanup: + try: + sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) + from cleanup_comfyui import after_export + print("[cleanup] " + after_export(root, pid, host, log_path, key, out, cid), + flush=True) + except Exception as e: + # 成片已安全落地;清理失败只提示,绝不影响主流程 + print("[cleanup] FAILED %s(图片已落地,可稍后跑 cleanup_comfyui.py 补清)" + % e, file=sys.stderr, flush=True) + return 1 if bad else 0 + + +if __name__ == "__main__": + try: + sys.exit(main()) + except Exception as e: + print("ERROR: %s" % e, file=sys.stderr, flush=True) + sys.exit(1) diff --git a/scripts/tts.py b/scripts/tts.py new file mode 100644 index 0000000..76b1a44 --- /dev/null +++ b/scripts/tts.py @@ -0,0 +1,102 @@ +#!/usr/bin/env python3 +"""xv 配音:从 30_shots.json 取 line 合成,实测时长回填 duration。 + +用法: python3 tools/tts.py projects/EPxx/30_shots.json +说明: 不加快语速硬塞;duration = max(标称片长, 实测语音 + 0.6s 尾留白)。 +""" +import argparse +import asyncio +import json +import os +import re +import subprocess +import sys + +def _find_root(): + """工作空间根:MANJU_ROOT > cwd 向上找 config/pipeline.json > 脚本上级。""" + env = os.environ.get("MANJU_ROOT") + if env: + return os.path.abspath(os.path.expanduser(env)) + d = os.getcwd() + while True: + if os.path.isfile(os.path.join(d, "config", "pipeline.json")): + return d + nd = os.path.dirname(d) + if nd == d: + break + d = nd + return os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + + +ROOT = _find_root() + + +def ffmpeg_bin(): + import imageio_ffmpeg + return imageio_ffmpeg.get_ffmpeg_exe() + + +def audio_duration(path): + r = subprocess.run([ffmpeg_bin(), "-hide_banner", "-i", str(path)], + stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, text=True) + m = re.search(r"Duration:\s*(\d+):(\d+):([\d.]+)", r.stderr) + if not m: + return None + return int(m.group(1)) * 3600 + int(m.group(2)) * 60 + float(m.group(3)) + + +async def synth(text, out, voice, rate): + import edge_tts + await edge_tts.Communicate(text, voice, rate=rate).save(str(out)) + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("shots", help="30_shots.json 路径") + ap.add_argument("--out-dir", default=None, help="默认 work//audio") + ap.add_argument("--voice", default=None) + ap.add_argument("--rate", default="+0%") + ap.add_argument("--no-writeback", action="store_true") + a = ap.parse_args() + + shots_path = os.path.abspath(a.shots) + cfg = json.load(open(os.path.join(ROOT, "config", "pipeline.json"), encoding="utf-8")) + voice = a.voice or cfg["tts"]["voice"] + nominal = cfg["videoModel"]["nominalSeconds"] + data = json.load(open(shots_path, encoding="utf-8")) + ep = data["episode"] + out_dir = os.path.abspath(a.out_dir) if a.out_dir else os.path.join(ROOT, "work", ep, "audio") + os.makedirs(out_dir, exist_ok=True) + + print("音色: %s | 语速: %s | 输出: %s" % (voice, a.rate, out_dir), flush=True) + + durations = {} + for i, s in enumerate(data["shots"], 1): + sid = s["shotId"] + out = os.path.join(out_dir, "vo_%02d.mp3" % i) + if not (os.path.exists(out) and os.path.getsize(out) > 1000): + asyncio.run(synth(s["line"], out, voice, a.rate)) + d = audio_duration(out) + if d is None: + print("ERROR: 无法解析时长 %s" % out, file=sys.stderr) + return 1 + target = round(max(nominal, d + 0.6), 2) + durations[sid] = {"audio": round(d, 2), "target": target, + "voice": voice, "file": os.path.relpath(out, ROOT)} + print(" %s vo=%5.2fs -> duration=%5.2fs | %s" % (sid, d, target, s["line"]), flush=True) + + with open(os.path.join(out_dir, "durations.json"), "w", encoding="utf-8") as f: + json.dump(durations, f, ensure_ascii=False, indent=2) + + if not a.no_writeback: + for s in data["shots"]: + s["duration"] = durations[s["shotId"]]["target"] + data["targetDuration"] = round(sum(s["duration"] for s in data["shots"]), 2) + with open(shots_path, "w", encoding="utf-8") as f: + json.dump(data, f, ensure_ascii=False, indent=2) + print("已回填 30_shots.json: 总时长 %.2fs" % data["targetDuration"], flush=True) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/validate_shots.py b/scripts/validate_shots.py new file mode 100644 index 0000000..7d0d545 --- /dev/null +++ b/scripts/validate_shots.py @@ -0,0 +1,209 @@ +#!/usr/bin/env python3 +"""xv 分镜清单校验器 —— 零第三方依赖,Python 3.9+。 + +ERROR 阻断进入生成阶段;WARN 不阻断但必须逐条确认。 +规则来源:Toonflow workflow PART A(references/toonflow-workflow-director.md) +""" + +import json +import re +import sys +from pathlib import Path + +def _find_root(): + """工作空间根:MANJU_ROOT > cwd 向上找 config/pipeline.json > 脚本上级。""" + import os as _os + env = _os.environ.get("MANJU_ROOT") + if env: + return Path(env).expanduser().absolute() + d = Path.cwd().absolute() + for p in (d, *d.parents): + if (p / "config" / "pipeline.json").is_file(): + return p + return Path(__file__).absolute().parent.parent + + +ROOT = _find_root() +SHOT_ID_RE = re.compile(r"^S\d{2}$") +EVENT_ID_RE = re.compile(r"^E\d{2}$") +EVENT_SCAN_RE = re.compile(r"\bE\d{2}\b") +SHOT_TYPES = ["大特写", "特写", "近景", "中景", "全景", "远景"] +STATUSES = {"planned", "prompted", "generated", "adopted", "rejected"} +RELATIONS = {"continuous", "partial", "reset"} +FORBIDDEN_STATE = ("同上", "延续上一段", "沿用上一段", "同上一段") + + +def nominal_seconds(): + try: + with (ROOT / "config/pipeline.json").open(encoding="utf-8") as f: + return float(json.load(f)["videoModel"]["nominalSeconds"]) + except Exception: + return 5.06 + + +def load_events(ep_dir): + path = ep_dir / "10_events.md" + if not path.exists(): + return None + return set(EVENT_SCAN_RE.findall(path.read_text(encoding="utf-8"))) + + +def shot_hash(text): + import hashlib + return hashlib.sha256(text.encode("utf-8")).hexdigest()[:8] + + +def validate(path): + errors, warns = [], [] + path = Path(path).resolve() + ep_dir = path.parent + nominal = nominal_seconds() + + try: + data = json.loads(path.read_text(encoding="utf-8")) + except Exception as exc: + return [f"无法读取清单:{exc}"], [], {} + + for key in ("episode", "targetDuration", "shots"): + if key not in data: + errors.append(f"顶层缺少必填字段 {key}") + + shots = data.get("shots") or [] + if not shots: + errors.append("shots 为空") + return errors, warns, {"shots": 0, "total": 0.0, "errors": len(errors), "warns": len(warns)} + + if not re.match(r"^EP\d{2}$", str(data.get("episode", ""))): + errors.append("episode 需为 EPxx 格式") + + events = load_events(ep_dir) + if events is None: + warns.append("未找到 10_events.md,跳过 E## 溯源校验") + else: + for eid in sorted(events): + used = any(eid in (s.get("eventIds") or []) for s in shots) + if not used: + warns.append(f"源节拍 {eid} 未映射到任何镜头(可能漏拍)") + + seen, total = set(), 0.0 + prev = None + for i, s in enumerate(shots): + sid = str(s.get("shotId", f"<第{i + 1}项>")) + if not SHOT_ID_RE.match(sid): + errors.append(f"{sid}: shotId 需为 Sxx 格式") + if sid in seen: + errors.append(f"{sid}: 镜号重复") + seen.add(sid) + if SHOT_ID_RE.match(sid) and int(sid[1:]) != i + 1: + errors.append(f"{sid}: 镜号未按 S01 起顺序编号") + + eids = s.get("eventIds") or [] + if not eids: + errors.append(f"{sid}: 缺 eventIds,禁止无源新增动作") + else: + for eid in eids: + if not EVENT_ID_RE.match(str(eid)): + errors.append(f"{sid}: 非法事件号 {eid}") + elif events is not None and eid not in events: + errors.append(f"{sid}: 事件 {eid} 未登记在 10_events.md") + + if not str(s.get("visual", "")).strip(): + errors.append(f"{sid}: visual 为空") + + dur = s.get("duration") + if not isinstance(dur, (int, float)) or dur <= 0: + errors.append(f"{sid}: duration 非法") + else: + total += dur + if dur > nominal and not s.get("pad"): + errors.append( + f"{sid}: 时长 {dur}s 超过模型标称 {nominal}s,需置 pad=true(tpad clone 补足)" + ) + if dur > 8: + warns.append(f"{sid}: 单镜 {dur}s 偏长,注意长空档") + + if str(s.get("line", "")).strip() and not str(s.get("voice", "")).strip(): + errors.append(f"{sid}: 有台词必须固定音色 voice") + if s.get("status") not in STATUSES: + errors.append(f"{sid}: status 非法") + + st = s.get("shotType") + if st and st not in SHOT_TYPES: + errors.append(f"{sid}: shotType 非法:{st}") + + cont = s.get("continuity") or {} + if cont.get("relation") not in RELATIONS: + errors.append(f"{sid}: continuity.relation 应为 continuous/partial/reset") + initial = str(cont.get("initialState", "")) + if cont.get("relation") in ("continuous", "partial") and not initial.strip(): + errors.append(f"{sid}: 连续关联段必须写绝对 initialState") + for bad in FORBIDDEN_STATE: + if bad in initial: + errors.append(f"{sid}: initialState 含「{bad}」,须重写为绝对初始状态") + + for ref in s.get("refs") or []: + if not (ROOT / ref).exists(): + warns.append(f"{sid}: 参考资产尚未就位 {ref}") + + pf = s.get("promptFile") + if pf: + fp = ep_dir / pf if not str(pf).startswith("/") else Path(pf) + if not fp.exists(): + warns.append(f"{sid}: 提示词文件缺失 {pf}") + elif s.get("promptHash"): + actual = shot_hash(fp.read_text(encoding="utf-8")) + if actual != s["promptHash"]: + errors.append( + f"{sid}: promptHash 与 {pf} 不符(应为 {actual}),改词须换哈希另存" + ) + + if prev: + same_subject = prev.get("subject") and prev.get("subject") == s.get("subject") + if same_subject: + types = SHOT_TYPES + try: + gap = abs(types.index(prev.get("shotType")) - types.index(s.get("shotType"))) + except (ValueError, AttributeError): + gap = 0 + if gap < 2 and prev.get("angle") == s.get("angle"): + warns.append( + f"{sid}: 与前镜主体/景别/角度近似,跨独立生成段易像错误续帧" + ) + prev = s + + target = float(data.get("targetDuration") or 0) + tol = float(data.get("tolerance") or 3.0) + if target and total > target + tol: + errors.append(f"总时长 {total:.2f}s 超出目标 {target + tol:.2f}s") + if target and total < target - tol: + warns.append(f"总时长 {total:.2f}s 低于目标下限 {target - tol:.2f}s") + + summary = { + "episode": data.get("episode"), + "shots": len(shots), + "total": round(total, 2), + "target": target, + "errors": len(errors), + "warns": len(warns), + } + return errors, warns, summary + + +def main(argv): + if len(argv) != 2: + print("用法: validate_shots.py <30_shots.json>", file=sys.stderr) + return 2 + errors, warns, summary = validate(argv[1]) + print(f"[{summary.get('episode', '?')}] {summary['shots']} 镜 / {summary['total']}s " + f"(目标 {summary['target']}s) ERROR={summary['errors']} WARN={summary['warns']}") + for item in errors: + print(f" ERROR {item}") + for item in warns: + print(f" WARN {item}") + if not errors: + print(" 校验通过(WARN 需在生成前逐条确认)") + return 1 if errors else 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv))