Agent-Video-Driver
不依赖任何素材库与剪辑软件, 画面和音乐都由代码算出来, 再用 FFmpeg 封装成片.
本技能只规定方法与纪律, 不固定风格, 风格库见 references/styles.md.
一, 两道确认门 (都不可跳过)
门一, 启动确认门
接到视频任务后, 先向用户报告代价并取得明确同意, 再开始任何渲染:
| 必须告知的代价 | 典型量级 |
|---|---|
| Token 消耗 | 单条 30s 片约 5 到 10 万 output token, 90s 以上分段片更高, 长会话缓存命中也会累计到百万级 |
| 中间帧图片 | 30s@30fps 约 900 张 PNG, 1080p 下约 200MB, 90s 以上约 3000 张 |
| 渲染耗时 | 1080p@30fps 约 0.08 到 0.12 秒每帧, 单进程 3000 帧约 5 分钟 |
| 机器占用 | 全量渲染与最终合成都会长时间吃满 CPU, 开发机上会明显卡顿, 按限额跑可以缓解 |
| 会话占用 | 一个会话只做一个视频任务, 中途插入别的任务会污染上下文并拖慢每一步 |
同时确认四件事: 时长与分辨率, 确认模式 (逐步确认或一次确认), 是否需要作者署名 (默认不加), 交付文件命名. 逐步确认适合事实与审美需要用户发言权的题材, 一次确认适合判据客观的题材; 两种模式下"先出开头 10 秒"这个节点都不省略. 用户未确认前只做环境探测与分镜草案, 不渲染.
门二, 合成确认门 (每次跑重活之前单独确认)
门一的同意不覆盖这一步. 全量渲染与最终合成是仅有的两个把 CPU 长时间吃满的动作, 各自之前都要再确认一次:
- 先探测本机资源, 拿到限额建议与风险提示
python scripts/resources.py --for render --frames <帧数>
python scripts/resources.py --for encode --frames <帧数>
- 把核数, 当前负载, 可用内存, 目标盘剩余空间, 建议的线程数与编码预设, 以及是否建议拦截, 一并报告给用户
- 用户明确同意后才动手; 未同意时只跑探测, 不做任何编码或全量渲染
- 动手时一律按探测给出的限额执行, 不按满核跑
scripts/assemble.ps1 把这道门做进了脚本本身: 不带 -ConfirmAssembly 时只打印确认门并退出, 退出码 3 表示"正在等待用户二次确认".
-ProbeOnly 只探测不编码. 探测判定空间不足或负载过高时, 脚本会拒绝开工, 要强行开工必须显式加 -Force.
二, 八阶段流程
0 探测环境 -> 1 简报与提示词 -> 2 内容与文案 -> 3 风格与分镜
-> 4 配乐先行 -> 5 分段渲染 -> 6 编码封装 -> 7 客观验收
细节与每阶段的产出物见 references/workflow.md.
每阶段结束都要落一个可检查的产物, 不要一口气写完再跑.
阶段 1 到 3 的提示词按 references/prompt-scaffolding.md 的七模块填, 填完与产出一起给用户看.
阶段 5 与阶段 6 开工前各走一次合成确认门 (见第一节的门二).
三, 目录与文件规范
<工作目录>/
├── .skill/<技能名>/ # 技能本体, 一个技能一个目录 bundle
├── prompts/ # brief.md 与各阶段提示词
├── script.md # 屏文案表, timing.py 的输入
├── storyboard.md # 分镜表与启动确认门
├── credits.md # 外部素材的署名与许可
├── temp/ # 一切中间产物, 帧序列, plan.json, 试渲染, 校验图
├── <产物目录>/ # 只放最终交付文件与可直接复用的源脚本
└── audio/ # 配乐 WAV (可并入产物目录)
- 中间帧必须落在
temp/下, 交付前清理, 不要把 3000 张 PNG 留在根目录 - 相对路径优先, 脚本内不要写死绝对路径
- 一个视频一个命名前缀, 帧目录与成片名对应, 避免多任务互相覆盖
- 更多约定见
references/conventions.md
四, 风格不固定, 但配乐默认走管弦乐
本技能给的是引擎, 不是模板. 开片前先选风格, 再选配色与音色, 最后才写分镜.
references/styles.md 提供八种可直接套用的风格, 含配色十六进制, 字体, 运动语法, 配乐音色与适配题材:
深空霓虹 / 冷调纪录片 / 温暖纸感 / 极简白场 / 复古终端 / 学术图表 / 手绘涂鸦 / 电影胶片.
配乐默认用 scripts/orchestra.py 的管弦乐音色库. 理由是它同时满足两条硬要求:
- 不刺耳: 音色靠谐波堆叠而非宽带噪声, 实测刺耳区 (2 到 6kHz) 占比 1.2%, 谱心 418Hz
- 不单调: 十段式配器表加动机变奏加力度弧线, 实测每 10 秒 RMS 起伏 2.80 倍
需要更轻更现代的听感时才换 scripts/music.py 的键盘与电子音色.
无论用哪套, 都不许出现这三种情况: 全片一套配置跑到底, 高频占比过半, 或持续声部盖住拍点.
五, 脚本清单
| 脚本 | 作用 |
|---|---|
scripts/check_env.py | 探测 ffmpeg, Python 库, 字体, 磁盘, 沙箱限制, 渲染路线可用性 |
scripts/resources.py | 重活前的资源探测与限额建议: 核数, 负载, 内存, 磁盘, 建议线程数与编码预设 |
scripts/check_text.py | 字形体检: 位图比对找出会变豆腐块的字符 |
scripts/beats.py | 从音频反推 BPM, 拍点, 小节线, 逐小节响度变化 |
scripts/timing.py | 把屏文案表排到拍网格, 产出 plan.json 与分镜用的时间表 |
scripts/canvas.py | 画面引擎: 超采样画布, 缓动, 发光, 文字, 通用 UI 组件, 渲染驱动 |
scripts/dsp.py | 共享 DSP 基元: 滤波, 混响, 总线压缩, 暖调母带, 写 WAV |
scripts/orchestra.py | 管弦乐配乐引擎 (默认推荐) |
scripts/music.py | 键盘与电子配乐引擎 (备选) |
scripts/sfx.py | 音效轨混音: 按 cue 表把用户自备音效混成一条轨 |
scripts/check_audio.py | 配乐客观检查: 卡点, 频段, 脉冲, 单调性一次跑完 |
scripts/preview.py | 无视觉能力下的画面验收: 把帧降采样成彩色字符图, 支持前后帧对比 |
scripts/qa.py | 按 plan.json 逐屏抽帧, 锚点前后帧对比, 拼总览图 |
scripts/tokens.py | 统计本会话 token 与成本, 供片尾字幕使用 |
scripts/assemble.ps1 | 编码, 混音, 响度归一, 质检 |
templates/scene_module.py | 场景模块骨架: 逐拍触发, 分段调度, 区间渲染 CLI |
templates/storyboard.md | 分镜表与确认门模板 |
templates/brief.md | 简报模板, 全片唯一的一份背景 |
templates/stage-prompt.md | 阶段提示词模板, 七模块 |
templates/screen-script.md | 屏文案表模板, timing.py 的输入 |
画面默认走 Python + Pillow 逐帧渲染. 浏览器渲染路线在受限沙箱下不可用, 原因与规避见 references/pitfalls.md.
六, 内容底线 (Must hold, 四条不可协商)
- 事实有出处: 每个年份, 人名, 数字, 引语都要能追到可靠来源, 并在工作目录里记下链接; 追不到的直接删掉, 估算要标注, 二手说法要写清是谁的说法
- 素材可用: 引入外部图, 字体, 音效, 现成配乐时逐项核实许可, 署名写进
credits.md; 未采用的候选素材也要列出并写明原因 - 不画真人脸: 不用 AI 生成真人的脸; 用了 AI 生成的画面要按平台要求勾选"AI 生成内容"标注
- 画面只依赖时间: 所有随机性必须定种子, 同一帧每次渲出来必须一样
判定规则, 汇报格式与发布前清单见 references/content-and-rights.md.
七, 十四条工程铁律 (都是踩过的坑)
- 先做配乐再做画面, 画面切点必须等于配乐切点, 不要反过来迁就画面
- 所有入场动画以拍为单位写死, 禁止用秒数近似, 卡点差一帧观众就能看出来
- 单位坐标与像素坐标必须显式分开, 混用会让整场戏塌到左上角
- 段落调度用区间映射, 写完必须打印每段的起止帧核对, 差一段整片错位
- 帧序列不要写进根目录, 也不要留在磁盘上过夜, 交付前删干净
- 分区间并行渲染要开独立进程各写各的, 不要用共享队列, 沙箱会拦命名管道
- 混音先看频段占比, 高频占比过半就是刺耳, 低频占比过半就是浑浊
- 总线压缩的时间常数不能短于 0.3 秒, 否则压缩器会把拍点本身压平
- 任何时长不小于小节且每小节都出现的声部都会变成声墙, 掩掉拍点
- 文本要过三层编码关; 画面引擎已按字做字形回退, 但回退链也覆盖不到的字符仍会静默画成豆腐块, 所以每段渲染完必须看字形审计报告, 缺字形就改写法或换字体
- 编码后必须量 PSNR, 低于 45dB 说明码率给少了
- 无视觉能力时不要凭想象交付, 用字符图逐帧核对构图再用客观指标兜底
- 会话里只做一条片, 第二条另开会话, 否则缓存与上下文都会失控
- 全量渲染与最终合成前先探测资源并按限额跑, 不按满核跑, 且这两步各自要用户再确认一次
完整坑表与复现条件见 references/pitfalls.md, 文本编码见 references/text-and-encoding.md.
八, 验收标准 (交付前必须全绿)
| 项 | 判据 |
|---|---|
| 时长 | 精确到帧, 30s 片必须 30.000s |
| 卡点 | 逐帧差分峰值落在小节线正负 1 帧内, 且锚点屏的前后帧差异峰值落在切点帧 |
| 响度 | 集成响度 -16 到 -14 LUFS, 真峰值不高于 -1.0 dBFS |
| 画质 | 编码后与源帧 PSNR 高于 45dB |
| 构图 | 每个段落至少抽 2 帧做字符图核对, 每屏至少 1 帧进总览图 |
| 体积 | 1080p 每 30s 控制在 15MB 以内 (CRF 18 到 20) |
| 字形 | 渲染期审计报告里没有"回退链也找不到字形"的项 |
| 内容 | 上屏每一行文字都能在已核实的内容里找到出处 |
方法见 references/verification.md.
九, 署名策略
- 视频产物默认不加作者信息, 由工作流在启动确认门里问一次, 用户要才加
- 若用户要求署名, 只在片尾卡出现, 并同时给出可替换的常量位置
- 本技能作者 JularDepick, 版本见 frontmatter 的 metadata
十, 参考文档索引 (按推荐阅读顺序)
| 顺序 | 文档 | 内容 | 什么时候读 |
|---|---|---|---|
| 1 | references/workflow.md | 八阶段流程, 每阶段产出物, 分段经验值 | 接到任务后第一份 |
| 2 | references/prompt-scaffolding.md | 简报与阶段提示词的七模块, 角色分工, 子代理交接 | 开工写提示词时 |
| 3 | references/narrative.md | 开场语法, 单屏字数与阅读速度, 叙事线索与节奏 | 写文案时 |
| 4 | references/content-and-rights.md | 事实来源判定, 素材许可, 署名, 发布前清单 | 查资料与配图时 |
| 5 | references/styles.md | 八种风格与配乐对应, 选风格的四条判断法 | 定风格时 |
| 6 | references/beat-sync.md | 三层对齐, 段内事件写法, 卡点验证 | 写分镜之前 |
| 7 | references/audio-engine.md | 两套配乐引擎, 音色库, 编排骨架, 客观判据 | 做配乐时 |
| 8 | references/visual-engine.md | 画面引擎 API, 通用组件, 图形配方, 性能 | 写场景时 |
| 9 | references/text-and-encoding.md | 三层编码关与字形体检 | 写任何上屏文本前 |
| 10 | references/verification.md | 各类验收手段与交付自检清单 | 交付前 |
| 11 | references/pitfalls.md | 踩坑的现象, 原因与规避 | 出问题或复盘时 |
| 12 | references/conventions.md | 目录, 命名, 代码, 文档, 协作规范 | 建项目结构时 |
排序只由本表承担, 文件名不带序号.
新增参考文档时在表里插一行即可, 不需要重命名任何既有文件.
新增脚本放进 scripts/, 新增骨架放进 templates/, 并在本表与脚本清单里各加一行.