v0.3.0

Full Changelog: v0.2.0...v0.3.0

新增

• 文字墨迹覆盖率检查 check_ink.py: 新脚本. 接版面体检落盘的文字框清单, 到已渲染的帧上逐框量"里面到底有没有字", 判据是每框墨迹占比不低于 2%. 此前只能查字与字有没有压, 查不出"画了底板的框里根本没填字", 而后者的现象是逐屏亮度完全正常, 字符图里也像版式的一部分
• 逐屏表增列与空场判定: 逐屏表新增唯一色数与饱和度两列, 并自动判空白帧 (有底色但什么都没画) 与平板帧 (只剩灰阶没有色彩层次). 此前只有平均亮度, 拦不住这两类"没内容"
• 与纯背景差分: 拿每屏帧与纯背景逐像素相减, 报显著差异的包围盒与最靠上那一行, 用来抓水印, 误留的调试框, 忘了删的占位文字这类每帧都存在的缺陷. 相邻帧差分对这类缺陷恒为零, 完全查不出来
• 版面体检加越界档: 除压字外再查每个文字框有没有超出安全边距 (平台进度条与标题栏会遮掉贴边的文字, 逐屏亮度与字符图都看不出来). 边距按画幅短边折算, 下沿对字幕带单独放宽; 命中判不合格
• 单帧成本探针补三条实测路线: 持续负载实测 (笔记本撞功耗墙后尾部会明显变慢, 工期与并行度要用持续值, 用突发值外推会算短), 双渲染同帧比字节哈希核确定性, 以及直接量与核工程里真正会编码的那一帧. 此前只有固定负载的重复基准, 核的也是探针自造的帧
• 成片首帧非黑检查: 片头淡入若在第 0 帧还没完成, 平台取首帧当缩略图时就是一张黑图. 现在成片验收会额外抽第 0 帧报亮度
• 亮度多档量测补三列: 新增近黑占比 (亮底上出现纯黑残留), 近白占比 (暗底上把字写成纯白, 换浅底就隐形), 色带阶跃 (最长同值段与段数). 只给数不给阈值, 是否算问题取决于这一帧有没有大面积渐变
• 引擎能贴外部图片: 画面引擎新增贴图入口, 可以把产品照, Logo, 界面截图放进画面, 带圆角与软投影, 手机与相机存的横竖方向会自动转正. 超采样倍率自动处理, 同一张图在一帧里只读一次
• 立项单从 13 项变为 17 项: 中间插入交付形态, 交付语言与附加交付物三项 —— 交付形态分无旁白, 有旁白, 竖屏, 无声循环, 多语言五种, 每种各自决定节奏, 排版与多出来的验证项; 末尾追加第 17 项'能力缺口声明', 必填, 要求把用户提的每一条交付特征逐项对照能力边界页, 落在"做不了"栏的一律写进表里让用户选处理方式. 此前立项单只问到工程项与品牌三问, 交付形态靠临场猜
• 能力边界页: 按画面, 声音, 数据, 语言, 交付五个维度分"能做 / 勉强 / 做不了"三栏. 这一页是第 17 项的对照表, 也是撞上做不了的特征时唯一的止损点: 本技能最容易发生的失败不是报错, 是照文档指引降级成交付物 (要人物做成文字排版片, 要赛博朋克电子乐做成管弦乐, 要照片做成没有照片的动效片), 而全程没有一处闸拦住
• 三个此前只有文档没有实现的画面原语: 颜色混合, 整层绘制再按不透明度与混合模式合回 (印刷底纹常用), 曲线按拍逐段生长. 文档此前让调用它们的地方会直接报错

修复

• 阻断级: 两条编码路线的退出码语义正好互换 —— 分批路线用 8 表示帧完整性不合格, 6 表示编码失败; 一次编完路线恰好相反. 两条路线在流程文档里并列为可选, 按退出码写自动化判断时同一语义返回不同码. 现在统一为 6 是帧完整性, 8 是编码或混音失败, 定义只在一处
• 阻断级: 成片的色彩标签实际只有三分之一正确. 帧输入是 PNG, 帧本身没有色彩标签, 而编码器只从帧上读标签写进容器, 于是命令里四个标签参数都给了, 成片仍然只有色彩空间是 bt709, 原色与传递函数落回 unknown, 三标签闸恒定判不合格. 现在在滤镜链里给帧打标签, 三个标签全部回读正确. 注意给帧打标签要用只写帧头的做法, 换成真做色彩转换的滤镜会把画质从 55 dB 打到 28 dB, 直接跌出判据
• 阻断级: 自建画字封装会让版面体检整体空转并返回全绿. 体检只认四个方法名, 其余调用直接跳过, 于是四个检查项全打印"无"并正常退出, 落盘结果里待检框与未解析项都是空数组, 看起来像"检查通过且无问题", 严格模式也抓不住. 现在这类调用会进未解析项并给出处置办法, 同时排除了"量字不画字"与带路径的调用, 模板上无误报
• 阻断级: 字形体检的参数拼错会静默假绿. 该检查此前不校验未知参数, 拼错一个开关名会被当成待体检文本, 体检一段错的字符串后几乎必然全过并正常退出. 现在不认识的开关报用法错误
• 阻断级: 一条编码路线的真峰验收恒定失效. 本机 FFmpeg 把真峰量测的标题行与数值分成两行输出, 而该路线只认同行式, 于是每次都报"没有真峰行"并放行. 现在两种行格式都解析
• 判据只打印不拦: 画质检查与亮度检查算出了不合格却无条件正常退出, 按退出码判断的自动化全放行. 现在按合格与不合格返回不同退出码
• 逐屏终检表的偏暗判据与文档不一致: 验收表写的是两个分位数达标其一, 而终检表只有其中一列, 流程文档更是让 Agent 只看那一个. 暗场构图 (大面积暗底加少量亮字) 会被误报为不合格 —— 历史上正是这样把一组 27 屏里的 11 屏判成了问题. 现在表里两个分位数都有, 按达标其一判定
• 编码参数与帧完整性阈值散落多处: 帧文件名此前有八份副本, 字体路径表四份, 编码器参数三条路线各抄一份. 改一处漏其余几处的症状是静默的, 只体现为偏色, 掉帧或残片, 不报错. 现在这些值各只有一处定义, 两条编码路线共用
• 成片级四道硬闸量不出来时全部降级为通过: 色彩标签, 音画等长, 真峰与帧数的核对在量测失败时只警告不计失败. 现在音画等长有独立的回读与判定, 与色彩标签并列成第二道成片流信息硬闸
• 编码命令显式写出固定关键帧间隔与音轨码率: 各批参数不一致会在拼接处掉帧或闪一下; 音轨码率低一档时瞬态密集素材的解码真峰会顶出 0 dBFS 以上. 现在关键帧间隔固定并禁止场景切换自动插帧, 音轨按 384k 走
• 子进程调用缺编码声明: 十余处在非 UTF-8 的 Windows 上会抛解码异常; 另有一处编码与量测的调用没有超时上限, 卡死会让整条合成流程无限期停在那里
• 两处中间产物直写: 版面体检的结果文件与资源探测报告都有紧邻的下游读取方, 写到一半被中断会让下游读到截断内容; 资源探测报告尤其隐蔽, 探测脚本读不到时会退回内置限额而毫无察觉
• 音效临时目录的并发竞态: 目录名固定且不含进程号, 文件名用随机化的字符串哈希, 并发跑会互相删目录与覆盖文件
• 牌堆一致性校验从未真正执行过: 该校验的参数按当前工作目录解析, 从仓库根运行会去找一个不存在的路径. 改为按脚本自身位置解析
• 流程里残留"十阶段": 全文流程是九个阶段 (0 到 8), 但确认门与路由表的措辞仍是十阶段
• 响度判据此前没有任何一处真正检查: 目标点与验收区间两套值并列却从不被比较, 默认路线实测会过冲到区间外且不报错. 现在把两者关系写清, 并把区间接到比较上
• 锚点顺序与"先测后钉"的纪律矛盾: 排程阶段就要钉锚点, 而锚点必须先有配乐, 于是流程强制走那条被判为自证判据的顺序

优化

• 流程补上阶段级可执行细节: 分段渲染阶段给出外部图片的落地写法与四项检查的真实命令 (此前只写"把检查都跑一遍"却没给命令), 逐屏终检阶段给出版面体检与文字墨迹覆盖率的命令 (后者此前全库没有任何一条命令示例, 只躺在脚本清单里), 并把卡点方法论, 转场手法, 文本编码, 性能口径与能力边界页按阶段挂进正文 —— 这些内容此前有索引有正文, 却没有任何一个阶段带 Agent 去读
• 能力清单与流程表补上外部图片与新增验收项: 两个 README 与站点文案此前都没体现引擎已能贴图, 也没体现逐屏表新增的分位数
• 响度口径说清楚: 编码目标点与验收区间此前两套值并列却不说明关系. 现在明确目标点取区间中值, 区间是验收判据, 单遍归一会过冲, 严格时走精确响度闭环
• 单帧耗时的报价与实测对齐: 启动确认门上的标称值是轻负载段的数字, 与重负载段实测差一个数量级. 现在标明前提并要求报价前先量
• 坑表症状索引补漏: 一条"输出侧定位的请求时间因进位越过目标帧"没进症状索引, 而它的现象正是高频的"卡点整体偏一帧"
• 文档格式与措辞: 全部表格的分隔行统一居中; 删掉章节标题里的开发期轮次痕迹; 流程文档里与实现不一致的接口签名逐处改正

兼容性

• 旧工程的场景模块不需要改: 新增的画面原语全是新增 API, 不改变任何既有方法的签名或行为; 不开分层时绘制仍然直接落在画布上
• 两条编码路线的命令行参数名都没有变; 退出码语义被统一, 依赖旧的不一致语义写自动化的地方需要按新的语义表核对一次
• 工程侧配置源 theme.py 没有变, 老工程继续可用
• 立项单从 13 项变为 17 项, 且第 17 项必填. 按既有的"全按推荐"纪律处理即可, 但它需要 Agent 逐条对照能力边界页, 不能静默跳过; 用 v0.2.0 起过的工程, 按新模板重填
• 贴图能力带来三条新的检查盲区: 贴图框的越界与压字没有自动检查, 图片像素里的文字不参与去敏反查, 贴图这一动作本身不留痕迹. 用到贴图时这三条要人工补上

v0.2.0

Full Changelog: v0.1.0...v0.2.0

新增

• 分时确认与三张确认单: 原一张 13 项需求单一次问完, 改为在真正需要答案的时刻分三次问. 立项单只问无法从题材推断的事 (主题, 受众, 看完记住什么, 必现与必不现的词, 有无自备素材, 是否署名) 与纯工程项 (画幅, 帧率, 是否分批, 交付命名, 输出目录), 另加时长档位三选一; 覆盖度与结构单带出处的知识节点清单, 两到三个覆盖方案与重点配比建议; 风格与配乐单给三张候选样图加推荐, 两到三段配乐试听, 配色方向与确认模式. 每一项都给 2 到 4 条具名路径加一条推荐, 用户说"全按推荐"时也会先把候选列出来, 不再静默套默认
• 确认模式三档: 逐步确认, 一次确认, 放手一条龙; 放手一条龙要求把每个岔口选了什么与为什么写进分镜表, 三档下"先出开头 10 秒"这个节点都不省略
• 交互节点总表与任务路由表: 一屏看清每个节点谁在什么时候拍板, 交什么产物, 不拍板会怎样; 新片, 改已有片, 只做某一场或某效果各有自己的短路径, 不再把小活拉成九阶段
• 风格选择从抽签改为三候选: 取三张差别看得见的牌, 各出一张同内容样图拼在一起交给用户, 附一条与题材绑定的推荐; 补齐"选风格的方法"四条判断法 (题材适配, 信息密度, 受众情绪, 制作成本); 用户自带品牌色或点名配色时, 给出牌面配色与用户配色的合并规则 (身份色交给用户, 结构色按牌面的明度关系派生, 明度档位变了要逐条核对实现指导)
• 声音从一条配乐扩成三层: 配乐走逐小节意图表编排 (10 种意图加 2 个别名, 含抽鼓与末段减法两行手法, 不给意图表时回退到按切点分段的配器表); 拟音层由代码自产 14 种音色并按 cue 表落位, 用户素材可逐条替换; 另加按帧导出的音频包络
• 音频包络回画面: 新工具 audio_env.py 导出逐帧 RMS, 平滑包络, 四段频段占比与逐小节曲线, 并给出建议钉关键句的小节号; 场景模块可以按帧取用, 让画面元素跟着音乐实际强弱起伏, 而不是只跟拍号
• 小节播放表: timing.py --bars 从整数升级为播放表 (形如 5-21 14-30 75-end), 锚点钉在原始小节号上, 剪完音乐不必重算锚点; 排程缺口报三条可执行路径 (精简文案, 调大小节数, 回头剪音乐)
• 工程级配置源 theme.py: 身份与署名, 时间网格, 画幅与帧前缀, 色板, 字体与字号, 段落与幕表收拢到工程根一处, 场景模块优先从它取值, 改片只改这一处
• 版面静态体检 check_layout.py: 从场景模块抽出全部文字绘制调用, 按真实墨迹算墨迹框两两查相交, 报硬撞, 太挤与未解析三类; 只在同一函数内比较, 互斥的多屏分支只提示不判不合格
• 单帧成本探针 perf_probe.py: 把一帧按 Pillow 矢量与文字, numpy 后期, 3D 点云, PNG 落盘四段拆开计时, 给绝对毫秒与占比, 并附算子对照表; 配套口径见新文档 references/performance.md
• 新参考文档: routes.md (按题材分流七条路线, 各家能力边界, 什么时候该回来用本技能, 明显不该用的四种情况), example-explainer.md (九阶段端到端汇报范例, 回答"这一步该写到多细"), direction.md (基准片, 故事形状, 三候选结构, 证明外观, 交付前的对照自查)
• 坑表加症状索引: 文件头按现象关键词直接定位条目号, 排查时不必通读

修复

• 阻断级: Windows PowerShell 5.1 下编码脚本的混音步骤必然失败. 码率参数的拼接写法会让 PowerShell 把它拆成两个参数, ffmpeg 把其中的 k 当成输出文件名并报错, 整条流水线在视频编码完成之后失败
• 阻断级: 渲染进程被宿主强杀时留下的 0 字节坏帧会让 ffmpeg 静默停在坏帧处并正常退出, 交付出一条远短于设计的成片. 现在编码前按字节体检帧目录, 编码后按实际解码帧数核对, 两道都不通过就拒绝进入混音; 中断之后重跑之前也要求先做这道体检
• 字形体检把模块与函数的注释性文字以及命令行提示当成上屏文本, 一个场景模块能报出数百条"缺字形", 真问题被淹没. 现在默认跳过注释性文字, 并可只体检真正画到画面上的文本, 项目自定义的封装还能声明字体键
• 逐屏亮度判据对"暗场底色加少量亮字"的构图系统性误报, 实测一组 27 屏里 11 屏被误判, 而构图其实完整. 改为两个分位数达标其一, 并在只有低分位数不达标时说明这是暗场构图的正常现象
• 逐屏终检表在重渲进行中会读到新旧混合的帧并给出假阳性, 把人引向错误的排查方向; 现在开跑前先检查帧目录是否正在被改写, 命中就打印醒目警告
• 逐屏表的"与上一屏差异"列只出数不判定, 两屏误用同一主句时看不出问题; 现在低于阈值会当场点名并给出反查命令
• 起工程时抽到的风格牌无法复现, 与"抽一张, 可复现"的承诺不符; 现在自动生成抽签种子并写进牌面文件头部
• 配乐检查脚本的 BPM 只接受位置参数, 与其余脚本的长选项口径不一致; 现在两种写法都收, 同时给以长选项为准
• 中断之后重跑之前缺少帧完整性体检的指引, 已补进流程文档, 并把两道硬闸的判据与自查命令列成表

优化

• 澄清中文墨迹与字高带的口径: 字高带量的是拉丁字母, 只有约 0.72 个字身, 而中文字形占满 em 框, 墨迹约 1.0 个字身. 用字高带做单行对齐是对的, 但拿它反推相邻元素的纵向间距必然重叠; 现在给出按墨迹留白的经验值 (两个中文大字块之间至少留前一块字号的 0.15 倍)
• 顶杠高度给出反推公式与实测表: 补亮部面积的顶杠不再靠试, 按所需亮部占比与画幅反推高度, 并说明高度与不透明度要一起给
• 补上编码颗粒强度与成片体积的关系表: 颗粒强度从 1 调到 2, 体积跳约 20 倍, 是一个没有预警的悬崖; 现在要求在提高强度之前先量体积
• 渲染耗时的标称值补上复杂度前提与自查方法: 标称值对应的是每帧约 20 到 40 个绘制调用的场景, 场景更重时按实测折算, 不要直接引用
• 硬件编码器的说明改中性表述, 只保留"换完必须重新量 PSNR"这条纪律, 不再暗示画质变差
• 浏览器渲染路线不可用时, 按启动退出码给出排查清单, 并说明该路线不可用不影响十阶段流程, 全程用默认路线即可交付

兼容性

• 需求单结构变更: 原一张 requirements.md 拆为立项单, 并新增 coverage.md 与 style-and-score.md 两张单. 用 v0.1.0 起过的工程, 其 prompts/requirements.md 需要按新模板重填
• 风格选择方式变更: 不再"抽到哪张做哪张", 改为三候选挑定; 直接点名风格与指定种子复现的用法保留
• plan.json 新增键: bars_plan 与 source_bars, 逐屏另有 src_bar 与 src_beat_in_bar; 旧的 plan.json 仍可被逐屏终检读取
• 命令行向后兼容: timing.py --bars 的整数模式与 check_audio.py 的位置参数 BPM 都仍然可用, 输出与改造前一致
• 版本号字面量: 由 0.1.0 升到 0.2.0, 出现在技能 frontmatter 的 metadata.version, 两个 README 的版本徽章与站点版本号
• 环境与依赖不变: Python 标准库, numpy, Pillow, FFmpeg 与中文字体; 不需要浏览器, Node.js 与任何素材库; 默认路线不依赖浏览器渲染, 受限沙箱环境可完整运行

v0.1.0

Full Changelog: https://github.com/JularDepick/Agent-Video-Driver.SKILL/commits/v0.1.0

v0.1.0 发行说明

v0.1.0 是本项目的首个版本, 本文档描述该版本包含的全部功能, 不存在与更早版本的变化对比.

功能

• 完整的 Agent 技能 agent-video-driver: 从一句话需求出发, 经十阶段流程 (环境探测, 简报与提示词, 内容与文案, 风格与分镜, 配乐先行, 分段渲染, 逐屏终检, 编码封装, 客观验收) 产出一条可交付的音视频成片, 全程不使用视频生成模型
• 程序化画面引擎: Python + Pillow 超采样画布逐帧绘制, 抗锯齿, 缓动与节拍原语, 字号反解与字高对齐, 逐字错帧, 落位压印, 发光与光晕, 通用 UI 组件, 转场手法目录; 支持 16:9 / 9:16 / 1:1 三档画幅预设与自定义偶数宽高, 组件坐标由画幅短边派生
• 程序化配乐引擎: 管弦乐与电子两套音色库, 配器表按切点分段取用, 暖调母带链含过采样真峰压制; 低内存机器可降采样合成或分段写盘拼接; 支持用户自备音乐的反推拍表与按小节无缝剪接
• 31 张风格牌堆: 深空霓虹, 冷调纪录片, 温暖纸感, 极简白场, 复古终端, 学术图表, 手绘涂鸦, 电影胶片, 品牌亮色产品片, 丝网印与 riso 四色, 蓝图工程图, 暗房银盐, 纸艺纸感, 瑞士编辑排版, 动态字体, 数据图版, 拼贴剪纸, 逐帧手绘, 等轴2.5D, 扁平矢量, 线条动画, 3D渲染, 形变动画, 贴纸风科普, 赛博朋克HUD, 弥散渐变玻璃拟态, 几何构成包豪斯, 复古Synthwave, 像素风, 液态流动, 综艺花字; 缺省抽签决定风格, 支持指定种子复现与排除上一条, 牌面自动落成项目里的 STYLE.md
• 两道流程安全门: 启动确认门带 13 项需求确认单一次问完 (画幅, 时长, 帧率, BPM, 配乐引擎, 配色, 风格来源, 确认模式, 是否分批, 署名, 命名, 输出目录, 品牌三问按需), 全量渲染与最终合成前各自再确认一次; 重活前自动探测核数, 负载, 内存与磁盘并按限额执行
• 无视觉能力下的验收手段: 字符图构图核对 (亮场墨迹模式与线稿梯度模式), 编码前逐屏终检表 (带幕号与 p95), 屏号到幕号到场景函数的反查, GIF 运动预览, 亮度多张量测落表, 字形体检, 事实与素材的去敏反查, PSNR 复测, 从成片解码回来量真峰
• 编码封装: FFmpeg 编码, 混音, 响度归一, 真峰验收与质检; 长片走分批路线, 支持断点续跑, 指定批次重编与只读进度前端, 帧空洞与批次自检在进门前拦截; 可选硬件编码器并附编码路线对比工具
• 工程脚手架: 一条命令起工程, 建目录, 复制脚本成自包含副本, 生成简报, 分镜表, 屏文案表与场景模块四份骨架并写好顶部常量, --aspect 定画幅
• 纯 Python 3D 点云渲染与隐藏线刻版; 印刷与 riso 路线的纸底, 网点, 分色, 乘法叠印与套印偏移
• 跨平台字体探测: 环境变量目录, fc-list, 系统字体目录三级探测中文字体与等宽字体, 生成 FONT_PATH 片段; 并行渲染按帧区间开独立进程
• 内容与合规底线: 事实必须追到出处, 素材许可逐项核实并署名, 不用 AI 生成真人脸, 画面只依赖时间且全部定种子, 上屏数字与代码实际值对账, 含个人信息的素材走三层去敏并自动推导禁用词反查
• 项目站点与参考成片: GitHub Pages 静态站展示一条 108 秒科普解说片作为参考成片; GitHub Actions 工作流在发布 Release 时自动把技能打包成 zip 上传到 Release assets

兼容性

• 运行环境: Windows (开发验证平台), Python 3.13, Pillow 12, NumPy 2, FFmpeg 7; 只装 Windows PowerShell 5.1 的机器用 powershell -ExecutionPolicy Bypass -File 调用编码脚本, 不要写 pwsh
• 依赖仅 Python 标准库, numpy, Pillow, FFmpeg 与中文字体; 不需要浏览器, Node.js 与任何素材库; zstandard 为可选项, 只影响片尾成本字幕
• 默认路线不依赖浏览器渲染, 受限沙箱环境可完整运行