ZJU-REAL/Easel / skills/builtin/short-drama
short-drama
Verified制作多集 AI 微短剧:建立剧集圣经和角色参考,完成分集剧本、逐镜 I2V、对白审计、配音字幕 BGM 与成片,保持跨镜跨集一致性。 当用户说“AI/横屏/竖屏/微短剧、拍短剧、分集剧本、连续剧情视频、做几集短剧”时使用。 单条非剧情视频用 auto-short-video;只写单条脚本用 video-script;只生成一个视频片段用 ai-video-gen。
| File | Kind | Size |
|---|---|---|
| EASEL-META.md | markdown | 2.9 KB |
| SKILL.md | skill md | 24.1 KB |
| references/causal-beats.md | markdown | 3.2 KB |
| references/character-consistency.md | markdown | 3.3 KB |
| references/dialogue-craft.md | markdown | 4.2 KB |
| references/drama-review-rubric.md | markdown | 5.1 KB |
| references/four-act-drama.md | markdown | 2.7 KB |
| references/genre-hooks-handbook.md | markdown | 5.4 KB |
| references/native-audio-workflow.md | markdown | 6.1 KB |
| references/satisfaction-and-villain.md | markdown | 3.8 KB |
| references/series-bible-schema.md | markdown | 5.5 KB |
| references/shot-prompt-format.md | markdown | 6.4 KB |
| references/story-engine.md | markdown | 5.8 KB |
| references/vertical-pacing.md | markdown | 2.0 KB |
| scripts/drama_ops.py | script | 40.8 KB |
| scripts/dubbing.py | script | 46.1 KB |
scripts/drama_ops.py
View on GitHub#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""drama_ops.py — AI 短剧的确定性资产/编排管理(纯标准库)。
短剧的**创意**(剧集策划/剧本/分镜 prompt)交给 LLM;生成动作(生图/生视频/配音)
委派给 ai-image-gen / ai-video-gen / tts-voiceover 等已有 SKILL。本脚本只做**确定性 IO**:
搭剧集目录、维护角色/场景/道具参考图索引(跨镜跨集一致性的骨架)、校验分镜 JSON、
把逐镜生成的片段拼成 assemble.py 可吃的 storyboard、跟踪多集生成进度(控费)。
子命令:
scaffold 搭一部剧的目录骨架 + series-bible 模板
ref add 登记一张参考图到 ref_index.json(自动分配 C/S/P 编号)
ref list 列出参考图索引
ref review 记录对定妆图的肉眼视觉复核(看到的形象+是否符合设定;generate 前必做)
shots validate 校验某集 shots.json 结构(镜头/引用/时长)
generate 逐镜图生视频:脚本读每镜 generation_prompt 自己调 ai_video.py(强制喂台词、幂等控费)
storyboard 把某集 shots.json(已填 clip 路径)转成 assemble.py 的 storyboard.json
progress 登记/查看逐集生成进度(planned/done)
selftest 自检
用法举例:
drama_ops.py scaffold --series "逆袭甜妻"
drama_ops.py ref add --series "逆袭甜妻" --kind character --name 林策 --image refs/lin.png --desc "男主,冷峻" --style "都市港风"
drama_ops.py ref list --series "逆袭甜妻"
drama_ops.py shots validate --series "逆袭甜妻" --episode 1
drama_ops.py storyboard --series "逆袭甜妻" --episode 1 -o outputs/逆袭甜妻/episodes/ep01/storyboard.json
drama_ops.py progress record --series "逆袭甜妻" --episode 1 --shot 3 --status done
"""
from __future__ import annotations
import argparse
import json
import subprocess
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[3] / "shared" / "scripts"))
import ai_video # noqa: E402
DEFAULT_ROOT = "outputs"
_KIND_PREFIX = {"character": "C", "scene": "S", "prop": "P"}
_SERIES_BIBLE = """# 剧集圣经(series bible)
> 据题材填满。**深度字段(行动模型/可跟随四问/反派阶梯…)不是可选项**——照 `series-bible-schema.md`
> 填,写完过 `drama-review-rubric.md` 的 A(故事引擎)+ B(人物可跟随)门。只写「年龄外貌性格」不合格。
## 1. 一句话卖点
> 谁 + 遇到什么 + 有多爽/多虐/多反转。先读 `genre-hooks-handbook.md` 定题材 + 核心爽点。
## 1.5 核心矛盾(一句话)
> 全剧单一主冲突:谁和谁、为了什么、对抗到底。
## 1.6 戏剧承诺(写角色/剧情前先过 A 门)
> 当【主角】用【惯常策略】追求【当前目标】时,【对抗机制】迫使其付出【核心代价】;
> 系列反复兑现【观众回报】,直到【终止性转变】发生。
> — 过 `story-engine.md` 承诺自检(swap-test / 阻力有筹码 / 主角能动性 / 中段有回报)。
## 2. 世界观 / 设定
> 时代/场景/规则/金手指。竖屏微短剧要极简。
## 3. 角色表(外貌一致性 + 人物深度,逐角色一节)
### C0X <姓名>
- **外貌关键词**(喂参考图 prompt):年龄/发型/脸型/服装/气质,越具体越稳
- **行动模型(8 字段,治扁平)**:表层目标 / 保护对象 / 自我解释 / 惯常策略 / 筹码 / 盲区 / 底线与越线 / 可变事实
- **want / need / wound / flaw**:外在目标 vs 内在需要 + 创伤与错误信念 + 缺陷
- **弧光**:从头到尾变化了什么(主角必填)
- **可跟随四问**:ep1 内可见地答出其一(承受的具体不公 / 替谁扛 / 共同渴望 / 想借的本事)
- **关系(双向)**:A 需要 B 什么 / 怕 B 看见什么 / 用什么约束 B(反向亦然)
- **voice sheet**:词汇/口头禅/句长/语气/回避词(保台词过 swap-test)
- **音色档案**:性别 · 年龄段 · 气质 · 身份 · 语速(喂选角,具体到能选出唯一音色,别只写「男声」)
## 4. 剧情主线
> 起点 → 主要矛盾 → 高潮 → 结局。单线清晰,忌多线。
## 4.5 情绪曲线 & 爽点节奏表
> 情绪曲线:憋屈→释放→甜→揪心→大爽,别一路平/一路爽。
| 集 | 主爆点(爽/虐点)| 情绪 |
|---|---|---|
| 1 | | |
## 4.6 反派阶梯(治工具人 / 爽点通胀,见 `satisfaction-and-villain.md`)
| 层 | 角色 | 出场 | 筹码 / 威胁 | 三段式安排 |
|---|---|---|---|---|
| 小反派 | | 前15% | | 速败退场 |
| 中反派 | | 15–45% | | 小胜→受挫→翻盘 |
| 大反派 | | ~45%+ | | 高潮对决 |
## 5. 分集大纲(每集必有:一个反转点 + 一个集末钩子;集间因果咬合)
| 集 | 剧情(一句话)| 本集反转点 | 集末钩子 cliffhanger |
|---|---|---|---|
| 1 | 建立人物 + 抛核心冲突 | | 让人必须看下一集的悬念 |
## 6. 统一视觉风格前缀(一致性关键,抄进每个 shots.json 的 style_prefix)
> 风格 + 画幅(9:16竖屏) + 色调,如「都市港风,9:16竖屏,冷色调,电影质感,浅景深」。
"""
def _die(msg: str, code: int = 1) -> None:
print(f"ERROR: {msg}", file=sys.stderr)
sys.exit(code)
def _series_dir(root: str, series: str) -> Path:
if not series.strip():
_die("--series 剧名不能为空")
return (Path(root).expanduser() / series).resolve()
def _ep_dir(base: Path, episode: int) -> Path:
return base / "episodes" / f"ep{episode:02d}"
def _load_json(p: Path, default):
return json.loads(p.read_text(encoding="utf-8")) if p.exists() else default
def _write_json(p: Path, obj) -> None:
p.parent.mkdir(parents=True, exist_ok=True)
p.write_text(json.dumps(obj, ensure_ascii=False, indent=2), encoding="utf-8")
# ── scaffold ──────────────────────────────────────────────────────────
def scaffold(root: str, series: str) -> dict:
base = _series_dir(root, series)
for sub in ("refs", "episodes"):
(base / sub).mkdir(parents=True, exist_ok=True)
created = []
bible = base / "series-bible.md"
if not bible.exists():
bible.write_text(_SERIES_BIBLE, encoding="utf-8")
created.append("series-bible.md")
ri = base / "ref_index.json"
if not ri.exists():
_write_json(ri, {"series": series, "refs": []})
created.append("ref_index.json")
return {"base": str(base), "created": created}
# ── ref index ─────────────────────────────────────────────────────────
def ref_add(root: str, series: str, kind: str, name: str,
image: str, desc: str, style: str) -> dict:
base = _series_dir(root, series)
if not base.exists():
_die(f"剧目录不存在,请先 scaffold:{base}")
if kind not in _KIND_PREFIX:
_die(f"--kind 只能是 {list(_KIND_PREFIX)}")
ri = base / "ref_index.json"
data = _load_json(ri, {"series": series, "refs": []})
prefix = _KIND_PREFIX[kind]
existing = [r for r in data["refs"] if r["code"].startswith(prefix)]
code = f"{prefix}{len(existing) + 1:02d}"
entry = {"code": code, "kind": kind, "name": name,
"desc": desc, "image": image, "style": style}
data["refs"].append(entry)
_write_json(ri, data)
return entry
def ref_list(root: str, series: str) -> list:
base = _series_dir(root, series)
return _load_json(base / "ref_index.json", {"refs": []}).get("refs", [])
def ref_review(root: str, series: str, code: str, observation: str,
matches: bool = True) -> dict:
"""记录对某参考图的**肉眼视觉复核**:你实际看到的形象 + 是否符合设定。
观察写不出=没真看图。generate 会拦「角色定妆图未复核」,逼先看再往下。"""
obs = (observation or "").strip()
if len(obs) < 6:
_die("--observation 太短:请写你**实际看到**的形象(发型/年龄/服装/气质…)并判断是否符合设定,"
"别敷衍——这是防止不看图就往下走。")
base = _series_dir(root, series)
ri = base / "ref_index.json"
data = _load_json(ri, {"series": series, "refs": []})
hit = next((r for r in data["refs"] if r.get("code") == code), None)
if not hit:
_die(f"参考图 {code} 不在索引里(先 ref add 登记)。已登记:{[r.get('code') for r in data['refs']]}")
hit["reviewed"] = True
hit["review_observation"] = obs
hit["review_matches"] = bool(matches)
_write_json(ri, data)
return hit
def _unreviewed_character_refs(root: str, series: str, shots: list) -> list[str]:
"""本集 shots 引用到的**角色定妆图**里,还没肉眼复核(或复核判不符)的 code。"""
refs = {r.get("code"): r for r in ref_list(root, series)}
used = {c for sh in shots for c in (sh.get("refs") or [])}
bad = []
for code in sorted(used):
r = refs.get(code)
if r and r.get("kind") == "character" and not (r.get("reviewed") and r.get("review_matches")):
bad.append(code)
return bad
# ── shots 校验 ────────────────────────────────────────────────────────
def _norm_line(s: str) -> str:
"""粗归一(去标点/空格、繁→简、小写)用于判断 generation_prompt 是否已含台词。"""
s = s or ""
try:
import zhconv
s = zhconv.convert(s, "zh-cn")
except Exception: # noqa: BLE001
pass
return "".join(ch for ch in s.lower() if ch.isalnum())
def validate_shots(shots: dict, known_codes: set[str] | None = None,
dialogue_texts: dict | None = None) -> list[str]:
"""校验某集 shots 结构,返回问题清单(空=通过)。纯函数,供测试。
dialogue_texts({idx: 台词})非空时启用**生视频前硬门**:有台词的镜必须已由 `prepare`
写入 generation_prompt 且其中含该台词——否则生视频时模型不知道要说什么、台词全对不上。"""
problems: list[str] = []
if "episode" not in shots:
problems.append("缺 episode 字段")
lst = shots.get("shots")
if not isinstance(lst, list) or not lst:
problems.append("shots 为空或非列表")
return problems
if not shots.get("style_prefix"):
problems.append("缺 style_prefix(统一风格前缀,保画面一致)")
idxs = []
for i, sh in enumerate(lst):
tag = f"镜头[{i}]"
if "idx" not in sh:
problems.append(f"{tag} 缺 idx")
else:
idxs.append(sh["idx"])
if not sh.get("prompt") and not sh.get("desc"):
problems.append(f"{tag} 缺 prompt/desc")
refs = sh.get("refs", [])
if not refs:
problems.append(f"{tag} 未引用任何参考图(refs 空,角色/场景一致性无保障)")
elif known_codes is not None:
for c in refs:
if c not in known_codes:
problems.append(f"{tag} 引用了未登记的参考 {c}")
if idxs and sorted(idxs) != list(range(min(idxs), max(idxs) + 1)):
problems.append(f"镜头 idx 不连续:{sorted(idxs)}")
if dialogue_texts:
by_idx = {sh.get("idx"): sh for sh in lst}
for idx, texts in dialogue_texts.items():
sh = by_idx.get(idx)
if sh is None:
continue
# 一镜可多句:texts 为该镜逐句列表(兼容旧的单串)。逐句校验,别拼接后当整串找子串——
# native-first 的 gp 里各句之间夹着「角色X逐字说」等文本,拼接串不是连续子串会误判。
texts = [texts] if isinstance(texts, str) else list(texts)
gp = sh.get("generation_prompt") or ""
if not gp:
problems.append(f"镜{idx} 有台词但没 generation_prompt——**没跑 dubbing.py prepare**;"
"直接拿 prompt(只有画面、没台词)生视频,模型不会说台词、台词必对不上。先跑 prepare。")
continue
# native-first 契约会把每句台词逐字写进 gp;dub-reserve 契约不含台词(合法)。
if "逐字" in gp or "native-first" in gp or "逐字说" in gp:
gpn = _norm_line(gp)
for text in texts:
if _norm_line(text) and _norm_line(text) not in gpn:
problems.append(f"镜{idx} 的 generation_prompt 声称逐字却未含台词「{text}」——可能改了 lines 没重跑 prepare。")
return problems
def cmd_shots_validate(root: str, series: str, episode: int, pre_video: bool = False) -> int:
base = _series_dir(root, series)
sp = _ep_dir(base, episode) / "shots.json"
if not sp.exists():
_die(f"未找到 {sp}(先写好本集分镜 shots.json)")
shots = _load_json(sp, {})
known = {r["code"] for r in ref_list(root, series)}
dialogue_texts = None
if pre_video:
# 生视频前硬门:核对有台词的镜是否已由 prepare 写好含台词的 generation_prompt
lines = _load_json(_ep_dir(base, episode) / "lines.json", {}).get("lines", [])
dialogue_texts = {}
for ln in lines:
idx = ln.get("shot")
if idx is not None and ln.get("speaker") and ln.get("speaker") != "旁白":
dialogue_texts.setdefault(idx, []).append(str(ln.get("text") or ""))
problems = validate_shots(shots, known, dialogue_texts)
if problems:
print(f"⚠️ 第 {episode} 集分镜有 {len(problems)} 个问题:")
for p in problems:
print(f" - {p}")
return 1
print(f"✅ 第 {episode} 集分镜校验通过({len(shots['shots'])} 个镜头)")
return 0
# ── 脚本驱动逐镜生视频(把 generation_prompt 强制喂给视频模型)────────────
def _resolve_media(rel: str | None, ep: Path, base: Path) -> Path | None:
"""按 原样(CWD)→ episode 目录 → series 目录 找文件;找不到返回 None。"""
if not rel:
return None
for cand in (Path(rel), ep / rel, base / rel):
if cand.is_file():
return cand
return None
def cmd_generate(root: str, series: str, episode: int, only: list[int] | None,
force: bool, provider: str | None, model: str | None,
ratio: str, dry_run: bool) -> int:
"""逐镜图生视频——**脚本读每镜 generation_prompt 自己调 ai_video.py**,把台词契约强制
喂给视频模型,agent 无从传成「只有画面的 prompt」(治反复出现的「没喂台词→全 dub→直接 TTS」)。
先过生视频前硬门(有台词的镜必须已由 dubbing.py prepare 写好含台词的 generation_prompt),
再逐镜生成;已有 clip 的镜跳过(幂等控费),失败镜记 progress=failed 不影响其它镜。"""
base = _series_dir(root, series)
ep = _ep_dir(base, episode)
sp = ep / "shots.json"
if not sp.exists():
_die(f"未找到 {sp}(先写好本集分镜 shots.json)")
shots_data = _load_json(sp, {})
shots = shots_data.get("shots", [])
if not shots:
_die("shots 为空")
locked = shots_data.get("video_generation") or {}
locked_provider = str(locked.get("provider") or "").strip() or None
locked_model = str(locked.get("model") or "").strip() or None
if provider and locked_provider and provider != locked_provider:
_die(f"视频 provider 与 prepare 锁定值冲突:prepare={locked_provider},generate={provider}。"
"请使用同一 provider,或带新 provider 重新跑 dubbing.py prepare。")
provider = provider or locked_provider
try:
provider = ai_video.resolve_provider(provider)
resolved_model = ai_video.resolve_model(provider, model or locked_model, image=True)
except SystemExit:
_die("未指定视频 provider。请在 Web 配置 VIDEO_PROVIDER,或 prepare/generate 都传 --provider。")
if model and locked_model and model != locked_model:
_die(f"视频 model 与 prepare 锁定值冲突:prepare={locked_model},generate={model}。"
"请使用同一模型,或带新模型重新跑 dubbing.py prepare。")
if locked_provider and (provider != locked_provider or resolved_model != (locked_model or resolved_model)):
_die("当前视频 provider/model 与 prepare 阶段不一致,请重新跑 dubbing.py prepare 后再生成。")
model = resolved_model
# 硬门:生视频前必须先 prepare(有台词的镜要有含台词的 generation_prompt)。复用 validate_shots。
lines = _load_json(ep / "lines.json", {}).get("lines", [])
dialogue_texts: dict = {}
for ln in lines:
idx = ln.get("shot")
if idx is not None and ln.get("speaker") and ln.get("speaker") != "旁白":
dialogue_texts.setdefault(idx, []).append(str(ln.get("text") or ""))
known = {r["code"] for r in ref_list(root, series)}
problems = validate_shots(shots_data, known, dialogue_texts or None)
if problems:
_die("生视频前硬门未过——先跑 `dubbing.py prepare`(把台词写进 generation_prompt)"
"或修分镜,再来 generate:\n - " + "\n - ".join(problems))
# 硬门:生视频前必须**肉眼复核角色定妆图**(做完图别跳过看视觉形象就往下)。
# 每个被引用的角色定妆图要用 `ref review` 记录「实际看到的形象 + 是否符合设定」,写不出=没真看。
unreviewed = _unreviewed_character_refs(root, series, shots)
if unreviewed:
_die(f"这些角色定妆图还没肉眼复核(或复核判不符):{unreviewed}。\n"
f"做完定妆图必须**看图确认形象符合设定**再生视频——别跳过视觉验证。逐个记录:\n"
f" drama_ops.py ref review --series \"{series}\" --code C0X --observation \"看到的:<发型/年龄/服装/气质>,符合<角色>设定\"\n"
f"(形象不符就重生成定妆图再复核,别拿跑偏的形象往下生视频。)")
only_set = set(only) if only else None
ai_video_script = Path(__file__).resolve().parents[3] / "shared" / "scripts" / "ai_video.py"
if not ai_video_script.is_file():
_die(f"找不到 ai_video.py:{ai_video_script}")
# 组装计划(跳过已有 clip 的镜,除非 --force / --only 指定)
plan: list[tuple] = []
for s in shots:
idx = s.get("idx")
if only_set is not None and idx not in only_set:
continue
if s.get("clip") and _resolve_media(s.get("clip"), ep, base) and not force:
continue
frame = _resolve_media(s.get("frame"), ep, base)
if not frame:
_die(f"镜{idx} 没有可用首帧图(frame)——先按步骤15用 ai-image-gen 生成首帧、写回 shots.json 的 frame。")
prompt = (s.get("generation_prompt") or s.get("prompt") or s.get("desc") or "").strip()
if not prompt:
_die(f"镜{idx} 没有 generation_prompt/prompt——无法生视频。")
plan.append((idx, s, frame, prompt))
if not plan:
print("✅ 无需生成(目标镜都已有片段;--force 可强制重生成)")
return 0
# 控费:先报计划(多镜 × 生视频按量计费)
print(f"# 第{episode}集 生视频计划:{len(plan)} 镜 → {provider}:{model or '默认'}(按量计费)")
for idx, s, frame, _ in plan:
d = s.get("gen_duration") or s.get("target_duration")
tag = "含台词契约" if s.get("generation_prompt") else "⚠️仅画面(未 prepare?)"
print(f" 镜{idx}: 首帧={frame.name} 档={d or '默认'}s prompt={tag}")
if dry_run:
print("(--dry-run:仅列计划,未生成)")
return 0
failed: list = []
for idx, s, frame, prompt in plan:
clip_out = ep / "shots" / f"clip_{idx:02d}.mp4"
clip_out.parent.mkdir(parents=True, exist_ok=True)
cmd = [sys.executable, str(ai_video_script), "image2video", "--image", str(frame),
"--prompt", prompt, "--audio", "auto", "--ratio", ratio, "-o", str(clip_out)]
d = s.get("gen_duration") or s.get("target_duration")
if d:
cmd += ["--duration", str(int(float(d)))]
if provider:
cmd += ["--provider", provider]
if model:
cmd += ["--model", model]
print(f"▶ 镜{idx} 生视频…")
r = subprocess.run(cmd)
if r.returncode == 0 and clip_out.is_file() and clip_out.stat().st_size > 0:
s["clip"] = str(clip_out.resolve()) # 绝对路径:align/storyboard/assemble 各 CWD 都能解析
_write_json(sp, shots_data) # 每镜写回,断点续跑
progress_record(root, series, episode, idx, "done")
print(f"✅ 镜{idx} → {clip_out}")
else:
failed.append(idx)
progress_record(root, series, episode, idx, "failed")
print(f"❌ 镜{idx} 生视频失败(见上)", file=sys.stderr)
if failed:
_die(f"以下镜生视频失败:{failed}。修复后重跑(已成功的镜会自动跳过)。")
print(f"✅ 第{episode}集 {len(plan)} 镜生视频完成,clip 已写回 shots.json;"
f"下一步 dubbing.py audit → align。")
return 0
# ── storyboard(转 assemble.py 输入)──────────────────────────────────
def build_storyboard(shots: dict, size: str = "1080x1920",
narration: str | None = None, bgm: str | None = None,
subtitle: str | None = None, pad_mode: str = "trim",
audit: dict | None = None) -> dict:
"""把某集 shots(已填 clip/frame 路径)转成 assemble.py 的 storyboard。纯函数。
pad_mode 默认 "trim"(自然):片段够长裁到需要、短则只冻结尾巴,**绝不慢放/循环**——
每镜画面 = 完整片段(align 已把片段实测时长写回 duration),台词只占其中一段,自然播放。
另外汇总每镜的定时音效 `sh["sfx"]`=[{file, at(镜内秒), volume}],按镜头累计起点换算成
**全局 at** 收进 board["sfx"],供 assemble 在成片音轨上定点叠入(枪声/椅子/脚步等占非台词时间)。
"""
out_shots = []
audit_by_shot = {x.get("shot"): x for x in (audit or {}).get("shots", [])}
sfx_global: list[dict] = []
cum_start = 0.0 # 已累计到当前镜的全局起点(= 前面各镜 duration 之和)
for sh in shots.get("shots", []):
item = {"caption": sh.get("caption", "")}
if sh.get("clip"):
item["video"] = sh["clip"]
verdict = audit_by_shot.get(sh.get("idx"), {})
# native = 整轨原音(模型原声+环境音)直通、优先用模型原声;dub = 换独立 TTS 配音,
# **该镜原生轨在 assemble 里整轨丢弃**(无人声分离时保留会与配音双重人声)。
# regenerate 镜应先重生成拿好原声再来;万一漏到此处按 dub 处理。
item["audio_mode"] = "native" if verdict.get("decision") == "native" else "dub"
# 逐镜对齐:dubbing align 已把每镜时长写回 shots.json 的 duration;
# 带上它,assemble 才能把片段精确做到该时长,与配音/字幕对齐。
if sh.get("duration"):
item["duration"] = sh["duration"]
elif sh.get("frame"):
item["image"] = sh["frame"]
if sh.get("duration"):
item["duration"] = sh["duration"]
else:
continue # 该镜头还没生成素材,跳过
dur = float(sh.get("duration") or 0.0)
for fx in (sh.get("sfx") or []):
if not fx.get("file"):
continue # 只汇总已有音效文件的(纯描述留给 ai-music 生成后再填 file)
sfx_global.append({"file": fx["file"],
"at": round(cum_start + float(fx.get("at") or 0.0), 3),
"volume": fx.get("volume", 0.9)})
cum_start += dur
out_shots.append(item)
board = {"size": size, "shots": out_shots, "pad_mode": pad_mode,
"audio_policy": "native-first"}
if narration:
board["narration"] = narration
if bgm:
board["bgm"] = bgm
if subtitle:
board["subtitle"] = subtitle
if sfx_global:
board["sfx"] = sfx_global
return board
# ── progress ──────────────────────────────────────────────────────────
def progress_record(root: str, series: str, episode: int, shot: int | None,
status: str) -> dict:
base = _series_dir(root, series)
if not base.exists():
_die(f"剧目录不存在:{base}")
pf = base / "progress.json"
data = _load_json(pf, {"series": series, "episodes": {}})
ep_key = str(episode)
ep = data["episodes"].setdefault(ep_key, {"status": "planned", "shots": {}})
if shot is None:
ep["status"] = status
else:
ep["shots"][str(shot)] = status
_write_json(pf, data)
return {"episode": episode, "shot": shot, "status": status}
def progress_show(root: str, series: str) -> str:
base = _series_dir(root, series)
data = _load_json(base / "progress.json", {"series": series, "episodes": {}})
lines = [f"# {data.get('series','')} 生成进度", ""]
for ep in sorted(data["episodes"], key=lambda x: int(x)):
info = data["episodes"][ep]
done = sum(1 for s in info.get("shots", {}).values() if s == "done")
total = len(info.get("shots", {}))
lines.append(f"- 第 {ep} 集 [{info.get('status','?')}] 镜头 {done}/{total} done")
return "\n".join(lines) if len(lines) > 2 else "(暂无进度)"
# ── selftest ──────────────────────────────────────────────────────────
def _selftest() -> int:
import tempfile
ok = True
def chk(name, cond):
nonlocal ok
print(f"[{'PASS' if cond else 'FAIL'}] {name}")
ok = ok and cond
with tempfile.TemporaryDirectory() as td:
r = scaffold(td, "测试剧")
base = Path(r["base"])
chk("scaffold", (base / "series-bible.md").is_file()
and (base / "ref_index.json").is_file())
c1 = ref_add(td, "测试剧", "character", "林策", "refs/a.png", "男主", "港风")
c2 = ref_add(td, "测试剧", "character", "苏晚", "refs/b.png", "女主", "港风")
s1 = ref_add(td, "测试剧", "scene", "天台", "refs/s.png", "夜景天台", "港风")
chk("ref 自动编号 C01/C02/S01",
c1["code"] == "C01" and c2["code"] == "C02" and s1["code"] == "S01")
chk("ref list", len(ref_list(td, "测试剧")) == 3)
# shots 校验:坏的
bad = {"episode": 1, "shots": [{"idx": 1, "desc": "x"}]}
probs = validate_shots(bad, {"C01"})
chk("validate 抓 无风格前缀+无refs", any("style_prefix" in p for p in probs)
and any("参考图" in p for p in probs))
# 好的
good = {"episode": 1, "style_prefix": "港风9:16", "shots": [
{"idx": 1, "prompt": "a", "refs": ["C01"]},
{"idx": 2, "prompt": "b", "refs": ["C01", "S01"]}]}
chk("validate 通过", validate_shots(good, {"C01", "S01"}) == [])
chk("validate 抓未登记ref", any("未登记" in p for p in
validate_shots({"episode": 1, "style_prefix": "x",
"shots": [{"idx": 1, "prompt": "a", "refs": ["C99"]}]},
{"C01"})))
# 生视频前硬门:有台词的镜没 generation_prompt(没跑 prepare)→ 拦
dlg = {1: "你终于来了"}
chk("pre-video 抓 没跑prepare(缺generation_prompt)",
any("没跑" in p and "prepare" in p for p in
validate_shots(good, {"C01", "S01"}, dlg)))
okgood = {"episode": 1, "style_prefix": "港风", "shots": [
{"idx": 1, "prompt": "a", "refs": ["C01"],
"generation_prompt": "画面…必须逐字说:「你终于来了」…"},
{"idx": 2, "prompt": "b", "refs": ["C01", "S01"]}]}
chk("pre-video 通过(gen_prompt 含台词)", validate_shots(okgood, {"C01", "S01"}, dlg) == [])
# generate:脚本驱动生视频——门必须拦「有台词却没跑 prepare」
epg = _ep_dir(base, 1)
epg.mkdir(parents=True, exist_ok=True)
_write_json(epg / "lines.json", {"lines": [{"speaker": "林策", "text": "你终于来了", "shot": 1}]})
_write_json(epg / "shots.json", {"episode": 1, "style_prefix": "港风",
"shots": [{"idx": 1, "prompt": "画面", "refs": ["C01"], "frame": "shots/f1.png"}]})
try:
cmd_generate(td, "测试剧", 1, None, False, "xhs-maas", "happyhorse-1.0-i2v",
"9:16", dry_run=True)
gate_fired = False
except SystemExit:
gate_fired = True
chk("generate 拦 没跑prepare(缺generation_prompt)", gate_fired)
# 补上 generation_prompt + 首帧 → dry-run 只列计划、返回 0,不真发
(epg / "shots").mkdir(parents=True, exist_ok=True)
(epg / "shots" / "f1.png").write_text("x", encoding="utf-8")
_write_json(epg / "shots.json", {"episode": 1, "style_prefix": "港风",
"video_generation": {"provider": "xhs-maas", "model": "happyhorse-1.0-i2v"},
"shots": [{"idx": 1, "prompt": "画面", "refs": ["C01"], "frame": "shots/f1.png",
"generation_prompt": "画面…必须逐字说:「你终于来了」…", "gen_duration": 5}]})
# 定妆图未复核 → generate 拦(做完图别跳过看视觉形象)
try:
cmd_generate(td, "测试剧", 1, None, False, "xhs-maas", "happyhorse-1.0-i2v",
"9:16", dry_run=True)
vgate = False
except SystemExit:
vgate = True
chk("generate 拦 定妆图未肉眼复核", vgate)
# 复核 C01 后 → dry-run 通过
ref_review(td, "测试剧", "C01", "看到:冷峻短发西装男,符合男主设定")
try:
rc = cmd_generate(td, "测试剧", 1, None, False, "xhs-maas", "happyhorse-1.0-i2v",
"9:16", dry_run=True)
except SystemExit:
rc = 99
chk("generate dry-run 通过(prepare+首帧+定妆复核齐)", rc == 0)
try:
cmd_generate(td, "测试剧", 1, None, False, "agnes", "agnes-video-2.5-flash",
"9:16", dry_run=True)
model_gate = False
except SystemExit:
model_gate = True
chk("generate 拦 provider/model 与 prepare 锁定值冲突", model_gate)
try:
ref_review(td, "测试剧", "C01", "ok") # 太短
short_rejected = False
except SystemExit:
short_rejected = True
chk("ref_review 敷衍观察(太短)被拒", short_rejected)
# storyboard
shots = {"episode": 1, "shots": [
{"idx": 1, "clip": "ep01/s1.mp4", "duration": 3.2, "caption": "开场"},
{"idx": 2, "frame": "ep01/s2.png", "duration": 3, "caption": "转折"},
{"idx": 3, "caption": "还没生成"},
{"idx": 4, "clip": "ep01/s4.mp4", "duration": 4.0, "caption": "换配音镜"}]}
# native → 整轨原音直通(用模型原声);dub(人声坏了换配音)→ audio_mode=dub,原生轨在 assemble 里丢弃、纯 TTS
audit = {"shots": [{"shot": 1, "decision": "native"},
{"shot": 4, "decision": "dub"}]}
board = build_storyboard(shots, narration="v.mp3", bgm="b.mp3", audit=audit)
chk("storyboard 映射 video/image + 跳过未生成 + video 带 duration + 默认 trim + native/dub 音频模式",
len(board["shots"]) == 3 and board["shots"][0]["video"] == "ep01/s1.mp4"
and board["shots"][0]["duration"] == 3.2
and board["shots"][1]["image"] == "ep01/s2.png"
and board["narration"] == "v.mp3"
and board["pad_mode"] == "trim"
and board["shots"][0]["audio_mode"] == "native"
and board["shots"][2]["audio_mode"] == "dub")
# progress
progress_record(td, "测试剧", 1, 1, "done")
progress_record(td, "测试剧", 1, 2, "done")
progress_record(td, "测试剧", 1, None, "done")
chk("progress", "第 1 集" in progress_show(td, "测试剧"))
print("✅ selftest 通过" if ok else "❌ selftest 失败")
return 0 if ok else 1
def main() -> int:
ap = argparse.ArgumentParser(
description="AI 短剧确定性资产/编排管理",
formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__)
sub = ap.add_subparsers(dest="cmd", required=True)
ps = sub.add_parser("scaffold", help="搭剧集骨架")
ps.add_argument("--series", required=True)
ps.add_argument("--root", default=DEFAULT_ROOT)
pr = sub.add_parser("ref", help="参考图索引")
rsub = pr.add_subparsers(dest="refcmd", required=True)
ra = rsub.add_parser("add", help="登记参考图")
ra.add_argument("--series", required=True)
ra.add_argument("--root", default=DEFAULT_ROOT)
ra.add_argument("--kind", required=True, choices=list(_KIND_PREFIX))
ra.add_argument("--name", required=True)
ra.add_argument("--image", required=True)
ra.add_argument("--desc", default="")
ra.add_argument("--style", default="")
rl = rsub.add_parser("list", help="列参考图")
rl.add_argument("--series", required=True)
rl.add_argument("--root", default=DEFAULT_ROOT)
rv = rsub.add_parser("review", help="记录对定妆图的肉眼视觉复核(generate 前必做)")
rv.add_argument("--series", required=True)
rv.add_argument("--root", default=DEFAULT_ROOT)
rv.add_argument("--code", required=True, help="参考图编号(如 C01)")
rv.add_argument("--observation", required=True,
help="你**实际看到**的形象(发型/年龄/服装/气质…)+ 是否符合设定;写不出=没真看图")
rv.add_argument("--mismatch", action="store_true",
help="形象与设定不符(标记后 generate 仍会拦,应重生成定妆图再复核)")
psh = sub.add_parser("shots", help="分镜")
ssub = psh.add_subparsers(dest="shotcmd", required=True)
sv = ssub.add_parser("validate", help="校验某集分镜")
sv.add_argument("--series", required=True)
sv.add_argument("--root", default=DEFAULT_ROOT)
sv.add_argument("--episode", type=int, required=True)
sv.add_argument("--pre-video", dest="pre_video", action="store_true",
help="生视频前硬门:额外校验有台词的镜已由 prepare 写好含台词的 generation_prompt"
"(防止拿只有画面的 prompt 生视频导致台词全对不上)")
pg = sub.add_parser("generate", help="逐镜图生视频(脚本读 generation_prompt 自己调 ai_video.py,强制喂台词)")
pg.add_argument("--series", required=True)
pg.add_argument("--root", default=DEFAULT_ROOT)
pg.add_argument("--episode", type=int, required=True)
pg.add_argument("--only", help="只生成这些镜(逗号分隔 idx,如 1,3,5)")
pg.add_argument("--force", action="store_true", help="已有 clip 也重生成(默认跳过控费)")
pg.add_argument("--provider", help="视频 provider(默认 env VIDEO_PROVIDER)")
pg.add_argument("--model", help="视频模型(覆盖默认)")
pg.add_argument("--ratio", default="9:16", help="画幅(默认 9:16 竖屏)")
pg.add_argument("--dry-run", dest="dry_run", action="store_true",
help="只列生成计划、不真发(控费预检)")
pb = sub.add_parser("storyboard", help="转 assemble.py storyboard")
pb.add_argument("--series", required=True)
pb.add_argument("--root", default=DEFAULT_ROOT)
pb.add_argument("--episode", type=int, required=True)
pb.add_argument("-o", "--output", required=True)
pb.add_argument("--size", default="1080x1920")
pb.add_argument("--narration")
pb.add_argument("--bgm")
pb.add_argument("--subtitle")
pb.add_argument("--pad-mode", dest="pad_mode", default="trim",
choices=["trim", "auto", "stretch", "loop", "freeze"],
help="片段短于台词时长时的补足方式(默认 trim=自然,不慢放不循环)")
pb.add_argument("--allow-static", dest="allow_static", action="store_true",
help="放行「只有关键帧图、没生成视频片段」的镜头(会是静态图,很垃圾)——"
"默认硬拦,逼你先对每镜跑 ai-video-gen 图生视频")
pp = sub.add_parser("progress", help="生成进度")
psub = pp.add_subparsers(dest="pcmd", required=True)
pre = psub.add_parser("record")
pre.add_argument("--series", required=True)
pre.add_argument("--root", default=DEFAULT_ROOT)
pre.add_argument("--episode", type=int, required=True)
pre.add_argument("--shot", type=int)
pre.add_argument("--status", default="done",
choices=["planned", "done", "failed"])
psw = psub.add_parser("show")
psw.add_argument("--series", required=True)
psw.add_argument("--root", default=DEFAULT_ROOT)
sub.add_parser("selftest", help="自检")
a = ap.parse_args()
if a.cmd == "selftest":
return _selftest()
if a.cmd == "scaffold":
r = scaffold(a.root, a.series)
print(f"✅ {r['base']}(新建 {len(r['created'])} 个)")
return 0
if a.cmd == "ref":
if a.refcmd == "add":
e = ref_add(a.root, a.series, a.kind, a.name, a.image, a.desc, a.style)
print(f"✅ {e['code']} {e['name']} → {e['image']}")
elif a.refcmd == "review":
e = ref_review(a.root, a.series, a.code, a.observation, matches=not a.mismatch)
flag = "✅ 符合" if e["review_matches"] else "⚠️ 不符(应重生成定妆图)"
print(f"{flag} {e['code']} {e['name']} 复核记录:{e['review_observation']}")
else:
for r in ref_list(a.root, a.series):
rv = "✓看过" if r.get("reviewed") else "·未复核"
print(f" {r['code']} [{r['kind']}] {r['name']} {rv} — {r.get('desc','')} → {r['image']}")
return 0
if a.cmd == "shots" and a.shotcmd == "validate":
return cmd_shots_validate(a.root, a.series, a.episode, getattr(a, "pre_video", False))
if a.cmd == "generate":
only = [int(x) for x in a.only.replace(",", ",").split(",") if x.strip()] if a.only else None
return cmd_generate(a.root, a.series, a.episode, only, a.force,
a.provider, a.model, a.ratio, a.dry_run)
if a.cmd == "storyboard":
base = _series_dir(a.root, a.series)
sp = _ep_dir(base, a.episode) / "shots.json"
if not sp.exists():
_die(f"未找到 {sp}")
shots_data = _load_json(sp, {})
# 静态图硬闸门:有关键帧图(frame)却没生成视频片段(clip)的镜头 = 会是静态图冒充视频(很垃圾)
static = [s.get("idx") for s in shots_data.get("shots", [])
if s.get("frame") and not s.get("clip")]
if static and not a.allow_static:
_die(f"镜 {static} 只有关键帧图、没有视频片段(clip)——成片会是**静态图**,不是短剧!\n"
f"请先对每镜用 ai-video-gen 图生视频(image2video)把首帧驱动成动态片段,"
f"把 clip 路径写回 shots.json 再合成。\n"
f"(确实要做静态图片短剧才加 --allow-static。)")
audit = _load_json(_ep_dir(base, a.episode) / "clip-audit.json", {})
board = build_storyboard(shots_data, a.size,
a.narration, a.bgm, a.subtitle, a.pad_mode, audit)
_write_json(Path(a.output).expanduser(), board)
vids = sum(1 for s in board["shots"] if s.get("video"))
print(f"✅ {a.output}({len(board['shots'])} 个镜头,{vids} 个动态片段)")
return 0
if a.cmd == "progress":
if a.pcmd == "record":
r = progress_record(a.root, a.series, a.episode, a.shot, a.status)
print(f"✅ 第 {r['episode']} 集"
+ (f" 镜头 {r['shot']}" if r['shot'] is not None else "")
+ f" [{r['status']}]")
else:
print(progress_show(a.root, a.series))
return 0
return 1
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |