视频质控 (video-qa) 是做什么的?
对照预定故事板审核演示MP4,并返回一份像专业人工审核员会写出的、带时间戳的检查清单。两层结构:确定性探测器(deterministic probe)(ffmpeg/ffprobe/node — 机械检测,无需模型推理)和分析子代理(fresh analysis subagent),它基于探测器的紧凑JSON报告和一组有限的视频帧截图,对照脚进行推理。
硬性规则:分析始终在全新的子代理中运行
调用方(你,在主线程中)执行最小操作:
- 定位输入文件。
- 运行探测器脚本。
- 创建一个全新的独立子代理(使用
Agent工具)来执行分析。 - 将子代理的问题清单返回给用户。
切勿在调用方线程中直接读取提取的帧或对报告进行推理。 关键在于令牌隔离:一段5分钟的视频会产生约50帧和一个大型JSON报告;对其推理会消耗数万令牌(包括图像和分析文本)。如果这些内容进入调用方的上下文,将会污染会话的其余部分。子代理吸收这些信息,只返回简短的问题清单。这是强制性的,不是“方便时再执行”——每次调用video-qa都必须交办。请参阅references/handoff.md。
第1步 — 收集输入
你需要:
- 视频路径 — 待质检的MP4文件(审核员将观看的最终剪辑/成片)。
- 故事板/脚本 — 按顺序排列的预期节拍、时间预期以及每个片段应显示的内容。如果用户未提供,请索取(或者要求提供它所来自的issue或
demo-video故事板)。不要凭空编造节拍。 - 预期卡片 — 按顺序排列的脚本化卡片(封面、议程、每个插页、回顾)。将它们写入一个小的JSON文件,用于
--cards-file参数:一个由{ "label": "Cover (title + subtitle)" }条目组成的数组(为文字较多的卡片添加"minRead": <秒>以覆盖阅读时间条)。这用于驱动确定性的卡片交叉检查——这是一个一等输出,因为卡片是脚本化的旁白。 - 品牌标识 — 卡片/背景颜色和光标/注释颜色,以便探测器能分类品牌卡片,子代理能检查对比度。如果未指定,使用默认值:询问;不要猜测品牌。
第2步 — 运行确定性探测器
node ${CLAUDE_PLUGIN_ROOT}/skills/video-qa/scripts/probe.mjs \
--video "<视频的绝对路径.mp4>" \
--out "<工作目录>/video-qa-report.json" \
--frames-dir "<工作目录>/video-qa-frames" \
--card-rgb 15,81,255 \ # 品牌卡片颜色,格式为 R,G,B(例如 #0F51FF)
--cards-file "<工作目录>/cards.json" # 预期的故事板卡片,按顺序排列
使用临时的<工作目录>(例如在/tmp下),不要使用用户的仓库。探测器会写入JSON报告和有限帧集,并打印报告路径。它会运行三个全视频滤镜通道(冻结检测、场景剪切、运动检测)以及每个场景的采样——预算时间约为视频实际时长(wall-clock duration)的1-1.5倍。可调参数(均为可选,内置合理默认值):--card-tol、--demo-freeze、--annot-freeze、--card-min-read(阅读时间条,2.5秒)和--annotate-rgb R,G,B——注释标注颜色。当指定时,一个包含该颜色的“看这里”注释环的静止区域被视为有意的节奏控制(annotated: true),并且不会计入主要死区计数,而是作为非缺陷处理。有关每个探测器测量什么以及阈值设置的依据,请参阅references/detectors.md。
注释检测仅限于死区(dead-air)区域,因此annotatedRegionCount: 0并不意味着“视频中没有注释”。 只有当环与静止/冻结的时间段重合时,环才会被标记;如果构建过程修剪了死区(或者环在运动画面中播放),环仍然会渲染在屏幕上,但没有任何死区区域会携带它——因此从结构上说,该计数必然为0。切勿仅凭此数字就报告注释缺失;如果某个节拍脚本要求标注一个环,请通过该片段的帧(每个场景的span-*帧,或在注释时间戳处提取帧)来确认。
在交办之前,检查打印的摘要(片段数量、死区区域、故障数量、帧数量和cardCheck.countMatches)。如果cardSpans为0,则--card-rgb很可能不正确——请修正并重新运行,否则每个卡片都会被读作ui,导致冻结/死区/卡片分类毫无意义。如果cardCheck显示数量不匹配,这是一个真实的发现(卡片缺失或多余),而非探测器错误——让子代理根据帧来确认。
第3步 — 交办给分析子代理
使用Agent工具(subagent_type: general-purpose)创建一个全新的子代理。根据references/analysis-prompt.md构建其提示词,并替换以下内容:
{{REPORT_PATH}}→ 第2步中--out的路径。{{FRAMES_DIR}}→--frames-dir的路径。{{OUT_FINDINGS}}→ 你将读取的发现文件路径(例如<工作目录>/video-qa-findings.md)。{{STORYBOARD}}→ 第1步中的预期节拍,逐字引用。{{BRANDING}}→ 第1步中的品牌规则。
在子代理的初始提示中,作为一条明确的指令告诉子代理在行动的最后一步将其发现写入{{OUT_FINDINGS}}。读取该文件是可靠的获取路径:生成的代理的最终文本消息并不总是能被调用方接收到,而后续的“将你的发现发给我”的提示也常常落在一个空闲的代理上,它不会重新参与对话。该文件只包含问题清单(不含帧),因此不会破坏令牌隔离。子代理仍然读取报告和帧并逐节拍推理;它只是将结果持久化到你可以读取的文件中。
第4步 — 传递结果
读取发现文件({{OUT_FINDINGS}})并将问题清单原样返回给用户(它已经是交付格式)。不要添加任何你自己关于帧的推理——按照设计,你从未查看过它们。如果用户希望将其作为带有品牌标识的HTML产物,那是后续的单独操作。
在将“无法确定”项视为缺陷之前,先进行抽查。 探测器采样的是有限的帧集(几十帧,而非每一帧),因此一个确实发生的节拍可能正好落在两个采样点之间,并返回“无法确定”或“看似页面跳转/未显示”的标志——这是采样间隔造成的缺口,而非真正的缺失。这些是最容易出错的发现。对于每个此类项,在它应该出现的精确时间戳处提取几帧(例如ffmpeg -ss <t> -i video.mp4 -frames:v 1 …)并直接确认,然后再将其报告为缺陷。只报告完整视频中确实缺少的内容;将确认存在的节拍降级为✅标记,并注明已在采样集之外验证。
它能捕捉到的(以及它无法捕捉的)
- 可靠且机械性检测: 死区/冻结的UI区域(运动密度扫描)、场景/片段结构、品牌卡片与UI分类、故障簇(杂散的刷新/页面跳转闪烁)、总体的对比度/亮度统计信息。
- 子代理对有限帧的推理: 偏离脚本的管道UI(管理后台、日志、错误跟踪)——包括节拍之间以及片段中段重新加载时的短暂登录/加载/空状态/管理界面闪烁,这些被视为精修缺陷,而非可接受的过渡;过度剪辑/硬切(静音修剪切掉了真实的运动——光标瞬移无轨迹、页面过渡生硬跳跃、动作中途剪切),这些看起来不真实;缺失/错误的节拍;导航风格作为一等检查项(是否在产品中浏览进入 vs 页面跳转进入深层页面);卡片评判标准是其是否呈现到位(可读的持续时长、不被矛盾/空白的相邻卡片削弱),而非仅看存在与否,封面与议程卡片通过内容区分;错误的屏幕数据(计数、损坏的行);缺失的注释;品牌/对比度陷阱。
- 盲点: 在其他活跃区域中缺失的屏幕字幕(加载动画被视为运动),以及某个操作是真的失败了还是被剪辑出画面。子代理会将这些问题标记为“无法确定”。
references/validation-notes.md记录了该技能相对于参考测试集的经人工审核的黄金清单的评分情况。