shortdrama

一句话题材 → 本地出成片。薄编排层：不改动 minimax-h3-turing / ComfyUI / ai-2080ti22g 三个既有仓库，只在这里新增编排代码。

• 建设方案（权威设计文档）：docs/自动化短剧平台建设方案.html
• 目标机器：RTX 2080 Ti 22GB (sm_75) · 32GB RAM · 1TB NVMe，全本机模型
• 关键红线：单卡显存唯一硬瓶颈 → 全流程阶段串行 + 显存门控；成片档只允许 tiers.reproducible_only()

安装与分发（PyPI）

pip install shortdrama-pipeline              # 核心（引擎 + 门禁 + 审片工作台 + MCP）
pip install 'shortdrama-pipeline[gate]'       # + opencv / onnxruntime（人脸门禁）
pip install 'shortdrama-pipeline[scene]'      # + transformers（场景一致性 CLIP）
pip install 'shortdrama-pipeline[render]'     # + torch / realesrgan（超分）
pip install 'shortdrama-pipeline[tts]'        # + edge-tts

装完即得命令：shortdrama（主 CLI）、shortdrama-preflight、shortdrama-gate-faces、 shortdrama-gate-scene、shortdrama-gate-release、shortdrama-dashboard、shortdrama-mcp。

从源码装：pip install .（本仓库根）；开发用 pip install -e '.[dev]' （-e 时 skill 软链指向仓库 → 改 skill 立即同步到 agent 目录）。

让 agent 认识这套产线（skill 随包分发）：

shortdrama-install-skill            # 软链到 ~/.pi/agent/skills/shortdrama-production/SKILL.md
shortdrama-install-skill --dry-run  # 只看会写哪

装完下次启动 agent 才会加载（当前会话是启动时的快照）。

包内容：shortdrama/（引擎）、shortdrama/tools/（36 个门禁/装配/审核工具）、 shortdrama/studio.html（审片工作台前端）、prompts/、skills/、docs/。 不在包内：本机专用的 bash 编排脚本（tools/*.sh，硬编码 /home/a/ai-work 布局）与 shortdrama/tools 之外的开发目录 —— 它们是"这台机器的 SOP"，不是通用库。

打包约定（后续新代码一律照此）

语言	形态	位置	发布
Python	可导入包 + console_scripts	shortdrama/（工具进 shortdrama/tools/）	PyPI：shortdrama-pipeline
JS/TS	可发布 npm 包（ESM + 类型声明）	仓库根 js/ 或独立子目录	npm：@shortdrama/*
Shell	本机编排脚本	tools/*.sh	不发布（绑定本机布局）

规则：

1. 功能代码不写在仓库根的散脚本里 —— 要么进包（Python/TS），要么明确标注"本机专用"。
2. 重依赖走 optional-dependencies，别让 pip install 就拉 CUDA 大包。
3. 可选依赖（cv2/onnxruntime/transformers）惰性导入，保证缺依赖时模块仍可 import。
4. 每次发版 bump pyproject.toml 的 version + 更新 CHANGELOG。

Web 工作台（产线控制台）

./sd studio /home/a/ai-work/duanju --series 深夜便利店 --host 0.0.0.0 --port 8096 --token <token> → 手机访问 http://<局域网IP>:8096/?k=<token>

标签页	作用
分镜审片 / 定妆选图 / 放映	逐镜判定、挑定妆图、看片
交付审批 / 任务看板	审批与阶段触发（pid + 日志）
成片与质检	成片规格、质检报告、内容语义门禁（人脸存疑 / 场景离群）、审片汇总页与门禁 JSON 直达
AI 助手	内嵌 Pi Web（web 版 pi-agent，与本会话同一套 ~/.pi/agent 会话库）

顶部「⚙ 设置」（写入 ~/.pi/shortdrama.json，环境变量 SHORTDRAMA_* 优先）： ComfyUI 地址 / 超时 / HF 镜像 / ESRGAN tile / 整集真超分开关 / 铺量是否保留 ComfyUI / 工作台令牌 / Pi Web 地址。

命令速查（先准入 → 再冒烟 → 才铺量）：

shortdrama-preflight  <job>      # 15 秒，0 阻断才允许出片
bash   tools/smoke.sh      <job> 10   # 15 分钟，1 镜走全链路
bash   tools/rollout.sh    <job>      # 铺量（自动起 ComfyUI → 渲 → 停 → 超分 → 配音 → 门禁）
bash   tools/gate.sh       <dir>      # 验收（规格 5 关 + 人脸 + 场景 + 元数据）
shortdrama-dashboard  <job>      # 逐镜审片汇总页 → job/qc/dashboard.html

目录

目录	内容
docs/	建设方案 HTML（设计权威源）+ SOP-短剧生产.md（实操 SOP）
shortdrama/	主代码包：episode.py（一集七阶段驱动）、assets.py（产物清单/静态页）、studio.py/board.py（审片 Web / 看板）、loudness.py/grade.py/bgm.py（响度/亮度/BGM）、facecheck.py/textcheck.py（角色与剧本检查）、tview.py（终端看图）
prompts/	提示词模板（剧本 schema / 定妆出图）
tools/	运维与发布工具（详见下表）：make_voice.py（TTS 配音对轨）、make_release.py（封面/元数据/发布清单）、build_ass.py（精确安全区字幕）、check_discipline.py（提示词纪律机器检查）、apply_patches.py（审片结论落数据）、compare_old_new.py/rollback_shots.py（重出新旧复审与回滚）、gpu_watch*.py（显卡值班）、release_all.sh（一键发布流水线）
patches/	归档的补丁与审片结论（改词/补字幕/逐镜结论表），供复现
skills/	pi-agent skill：shortdrama-production/SKILL.md（已软链到 ~/.pi/agent/skills/）
jobs/	预留的任务目录（实际任务在 /home/a/ai-work/duanju/：一集一个子目录，含 story.json / shots.json / cast/ / frames/ / clips/ / voice/ / episode.mp4 / report.json / qc/review.md / cover_*.jpg / release_meta.json）
logs/	运行日志

工具速查（workspace/shortdrama/tools/）

工具	干什么
episode.py（在 shortdrama/）	一集八阶段：lint→cast→pick→shots→frames→render→review→assemble→qc
make_voice.py	TTS 配音：台词/旁白/信息卡三分类 + 剪静音 + 自适应语速 + 对轨混音
esrgan_x4.py	真超分（Real-ESRGAN x4，BGR 通道 + 官方归一化 + 分块 0.67GB）
make_release.py	封面（抽帧+叠字）+ 平台元数据 JSON + RELEASE.md
build_ass.py	自写 ASS 字幕（PlayRes=交付分辨率 → 安全区精确；台词/旁白/道具三样式）
check_discipline.py	提示词 5 纪律机器检查（按 t2i / ref2va 路线分层）
check_consistency.py	剧本↔分镜↔clips↔manifest 四方对账
compare_old_new.py	重出前后的新旧片并排对比图（逐镜复审）
rollback_shots.py	变差镜一键回滚旧片
write_verdicts.py	审片结论写回 qc/review.md
apply_patches.py	审片结论落数据（改词/补字幕/摘待重出的镜）
gpu_watch.py / gpu_watch_until_change.py	显卡值班（cron 每 5 分钟 / 状态变化即报）
gate.sh	交付门禁五关（一致性/纪律/质检/审片/齐全性）
finalize.sh	一键收尾（合成→配音→质检→封面→门禁）
verify_shots.py	改前/改后并排验收图

复用（不重复造轮子）

需求	直接用
ComfyUI 客户端 / 档位 / 工作流	../minimax-h3-turing 的 h3turing 包
多镜驱动 / 拼接	../minimax-h3-turing/scripts/shortvideo.py
1080p 上采样	../minimax-h3-turing/scripts/upscale_video.py
中文出图 → H3 桥	../minimax-h3-turing/scripts/zimage_to_h3.py
渲染执行体	../ComfyUI（:8188）

里程碑（详见方案 §12）

里程碑	工期	交付物
M0	0.5 天	基线数据表（h3turing doctor 全绿 + bench 基线）
M1	1 天	render.py：3 镜 clips、重试、单镜粒度续跑
M2	1–1.5 天	llm.py + story.py + shots.py + prompts/：10 题材 ≥8 份 schema 合法
M3	1 天	cast.py：定妆图候选挑选，3 镜人脸/服装一致
M4	1 天	assemble.py：1920×1056 / 24fps / 带字幕 / 不削波
M5	1–1.5 天	job.py + gate.py + sd CLI：一条命令出片 + 显存门控
M6	1 天	qc.py + sd batch：质检黑帧/静音/削波/缺镜，批量 5 集
P2（可选）	2–3 天	本地 TTS 配音 + 对轨

当前状态（2026-11-05 实测）：M1–M6 的能力已由 shortdrama/episode.py 一条流水线覆盖 （cast/pick/shots/frames/render/review/assemble/qc 八阶段），另有 tools/ 提供 TTS 配音、 发布打包、纪律检查；已实跑产出 3 集 × 35 镜 × 两画幅 = 6 个成片（/home/a/ai-work/duanju/）。 P2（本地 TTS 配音）已做（Kokoro-82M，见 tools/make_voice.py）。 未做：批量 5 集的自动排期、GPU 显存门控（靠"渲染前停 LLM 进程"的纪律代替）。

文档

• docs/产品设计文档.html —— 产品是什么、给谁用、流程与界面规格、数据契约、验收标准
• docs/自动化短剧平台建设方案.html —— 建设方案：架构、决策、约束、里程碑、实测数据
• docs/SOP-短剧生产.md —— 实操 SOP：每一步命令、纪律、踩坑

常用命令

# 开工自检
../minimax-h3-turing/scripts/h3turing.local.sh doctor --models-dir ../models

# 渲染执行体（防黑屏参数固定）
bash ../minimax-h3-turing/scripts/h3_launch.local.sh

# 查 ComfyUI 队列 / GPU
curl -s http://127.0.0.1:8188/queue | head -c 400
nvidia-smi --query-gpu=name,temperature.gpu,memory.used,memory.total,utilization.gpu --format=csv

跑一集（已实践：D202611_001）

一集 = 一个目录（目录即状态）。六阶段都能单独重跑，渲染是单镜粒度续跑。

EP=/home/a/ai-work/duanju/D202611_001
EPY=/home/a/ai-work/.venv/bin/python
SCRIPT=workspace/shortdrama/shortdrama/episode.py

$EPY $SCRIPT $EP lint      # 剧本预检（毁集级错误在秒级挡下）
$EPY $SCRIPT $EP cast      # 定妆候选图（Z-Image 中文 t2i，约 10s/张）
#   ↓ agent 看图挑人 → 写 $EP/cast/selection.json
$EPY $SCRIPT $EP pick      # → cast/<id>.png（主）+ <id>_alt.png（备）
#   ↓ P2 台词：代码选镜、LLM 只写字（合并不覆盖）；只改文本 → 不用重渲
$EPY shortdrama.pipeline.add_dialogue --root /home/a/ai-work/duanju --episode E01
$EPY $SCRIPT $EP shots     # story.json → shots.json（自动加 <Picture 1> 前缀）
$EPY $SCRIPT $EP frames    # 每镜 1 张关键帧图（约 10s/镜）→ frames/NN.png
#   ↓ agent 看 qc/keyframes_sheet.png 审片：构图/人物/光线对不对（改图 10s vs 改视频 210s）
$EPY $SCRIPT $EP render    # 逐镜出镜（H3 ref2va/t2v，约 210s/镜）
$EPY $SCRIPT $EP review    # 关键帧拼图 + 视频抽帧拼图 + clips/manifest.json（一屏审片）
$EPY $SCRIPT $EP assemble  # 拼接 → 3x 放大 → 烧字幕 + BGM + 统一响度/亮度 → episode.mp4
$EPY $SCRIPT $EP qc        # 黑帧/静音/削波/时长/分辨率/字幕覆盖率 → report.json

• 剧本由 pi-agent 按 prompts/story.md 写（不用本地 LLM 服务，省掉一整套起停与解析）。
• 详细步骤与踩坑：docs/SOP-短剧生产.md；agent 用法：skills/shortdrama-production/SKILL.md。
• 审片 + 任务看板走本地 Web（./sd studio /home/a/ai-work/duanju --port 8095）：选图 / 逐镜判定 / 看成片 / 逐阶段触发。 终端等价物：./sd board /home/a/ai-work/duanju --episode E01（看阶段）、--run render（触发）。
• 方案 v2（2026-11-04，按 3 集实跑修订）：docs/自动化短剧平台建设方案.html §4.3 Web 模式（pi-agent 作 agent 内核）、§4.4 阶段任务卡 T0–T7、§15.7 实测数据。
• 实操流程：docs/SOP-短剧生产.md（七阶段 T0–T7 + 任务看板 + 交付审批）。
• 交付审批：sd approval <job>（提交/批准/驳回；批准时客观门禁重跑，成片改动后批准自动失效）。

审片服务（独立常驻 · systemd）

审片台（审片 + 任务看板 + 放映 + 交付审批）做成 systemd user service： 独立于任何会话、重启自动拉起、崩溃自动重拉，开机自启（Linger=yes）。

bash tools/serve_review.sh install    # 安装 + 启动（首次生成固定令牌）
bash tools/serve_review.sh url       # 打印访问 URL
bash tools/serve_review.sh status    # 看状态
bash tools/serve_review.sh logs      # 看日志
bash tools/serve_review.sh stop      # 停

• 令牌固定存 ~/.config/shortdrama/studio.token（600），重启后 URL 不变。
• 服务范围：一个实例 = 一个剧集根目录（SHORTDRAMA_ROOT）+ 该目录下所有系列 （--series auto，自动发现 D202611_001 这类前缀）→ 换项目只改环境变量，不用改代码：

  SHORTDRAMA_ROOT=/home/a/ai-work/duanju SHORTDRAMA_PORT=8095 bash tools/serve_review.sh install
  

  要同时看不同项目（比如别的剧集仓库），就再装一个实例、换端口（单元名加后缀）。
• 纯看文件（不限短剧）：./sd assets serve <任意目录> --port 8092（只读、无令牌）。
• 写操作（挑图 / 逐镜判定 / 审批）必须带令牌；读操作（看片）局域网开放。
• 想只给外部人看片：用静态资产页 ./sd assets serve <job> --port 8092（纯只读、无令牌）。

静态服务（方案文档）

bash docs/serve.sh          # → http://<本机IP>:8091/
PORT=8092 bash docs/serve.sh

8090 端口是 ai-2080ti22g/docs/serve.sh，那份服务也覆盖本方案（旧 URL 仍可用）。

资产可见性（已实现）

产物在文件系统里，不引入数据库（方案 D9/D11：文件即状态，避免第二个真相源）。给的是"只读视图"：

./sd assets ls                  # 终端列出产物（含 sha256 / 体积 / 时间）
./sd assets json --out a.json   # 机器可读清单
./sd assets html                # 生成只读静态页（默认 <root>/_assets.html）
./sd assets serve --port 8092   # 生成 + 起本地服务 → http://127.0.0.1:8092/_assets.html

• 默认根目录 ../ComfyUI/output；也可指向某个 jobs/<job-id>/
• 产物旁挂 <file>.json（sidecar）时，页面直接显示该次运行的 seed / tier / 耗时
• 页面不写任何东西：挑图、审片的选择仍写回 job 目录里的文件

测试（必须用 .venv 的 python：部分测试要 imageio-ffmpeg 提供的 ffmpeg，系统 python3 没装会报错）： /home/a/ai-work/.venv/bin/python -m unittest discover -s shortdrama/tests