Cindy 视频剪辑伙伴时间线检查:video-editor-evidence 输入契约与 timeline_check.py 实战解析
Cindy 视频剪辑伙伴时间线检查:video-editor-evidence 输入契约与 timeline_check.py 实战解析
在 Cindy 桌面端内置的「视频剪辑伙伴」Bot 包中,video-editor-evidence 技能承担一项范围极小但边界极严的职责:把一份剪辑计划(时间线、素材引用、权利声明)转换成可核对的连续帧区间,并显式暴露结构性问题。本篇围绕该技能的输入契约 contract.md,逐条落实字段形状、校验规则、退出码与负例,并结合 timeline_check.py 与 Bot 包加载链路,说明这份契约在真实运行中如何被约束、被验证,以及哪些结论它不能提供。
契约要解决的问题:把“计划”变成可核对的帧区间
契约正文只有一段实质性描述,但它同时划定了三类边界:
- 输入边界:检查对象是“原创剪辑计划”的时间线、素材引用和权利声明,字段形状由
input.json定义。 - 输出边界:输出连续帧区间(
startFrame/endFrame),而不是成片、不是渲染结果、不是音画同步结论(render: NOT_RUN、syncAndCaptionAccuracy: NOT_EVALUATED)。 - 信任边界:输入中的状态、来源与许可都是显式声明,脚本不核实远端内容——它不会去云盘取素材、不会读媒体元数据、不会联网确认授权。
这三条边界在 SKILL.md 中被进一步固化:脚本“只用 Python 3.10+ 标准库,不访问网络/Home,不写文件,不执行子进程。安装与打包不会执行它。成功 exit 0,输入结构/引用错误 exit 2;语义缺口在输出字段中保持可见。输入 ≤ 1 MiB,最多 10000 条;所有示例都是合成数据。输出不是凭证、授权、测试或真实连接证明。” 参见 SKILL.md。
配套的方法参考文档把这一点讲得更直白:剪辑计划校验不能证明口型、字幕和音频正确,渲染成功也不能代替目检;source in/out 是原素材时间,timeline frame 是成片帧,二者不同;帧边界要用统一 fps,极短片段可能四舍五入成 0 帧,需拒绝。见 method.md。
契约字段总览:四个顶层键,一个都不许多
脚本通过 record() 做精确字段集校验,任何多写或少写都会抛错:
def record(value, fields):
require(isinstance(value, dict) and set(value) == set(fields.split()), "unexpected or missing fields")
顶层调用为 record(data, "fps sources clips maxDuration")(timeline_check.py)。因此顶层 JSON 必须且只能包含这四个键。
| 字段 | 类型/取值范围 | 脚本级约束 | 失败信息 |
|---|---|---|---|
fps |
有限数值 | 0 < fps <= 240,且 type() 必须为 int/float(布尔值被拒) |
fps out of range / finite number required |
sources |
数组,≤10000 条 | 每条为精确三字段记录 id duration rights |
bounded array required / unexpected or missing fields |
sources[].id |
非空字符串 | 去空白后非空;全局不可重复 | nonempty text required / duplicate id: <id> |
sources[].duration |
有限数值 | > 0 |
positive source duration required |
sources[].rights |
枚举 | 仅 "CLEARED" 或 "UNKNOWN" |
invalid rights state |
clips |
数组,≤10000 条 | 每条为精确四字段记录 source in out transcript |
unexpected or missing fields |
clips[].source |
字符串 | 必须命中 sources 中的 id |
missing source reference |
clips[].in / out |
有限数值 | 0 <= in < out <= source.duration |
clip outside source duration |
clips[].transcript |
字符串 | 必须是字符串(允许空串,表示未提供口播文本) | transcript must be supplied text |
maxDuration |
有限数值 | > 0,单位与 duration 一致(秒) |
positive maxDuration required |
契约中“null 表示未知”的表述需要结合实现理解:在这个脚本的具体 schema 里,未知状态用 rights: "UNKNOWN" 表达,而字段值写成 null 会直接撞上类型校验(rights 判为 invalid rights state,transcript 判为 transcript must be supplied text)。也就是说,“未知”是一种显式声明,不是缺省值。
可运行的最小输入:templates/input.json
仓库自带的示例就是合成数据,可直接作为 stdin 输入(input.json):
{
"fps": 30,
"sources": [
{
"id": "clip-a",
"duration": 20,
"rights": "CLEARED"
}
],
"clips": [
{
"source": "clip-a",
"in": 1,
"out": 4,
"transcript": "这是合成转录,不是真实用户口播。"
},
{
"source": "clip-a",
"in": 8,
"out": 10,
"transcript": "第二段合成转录。"
}
],
"maxDuration": 10
}
按 SKILL.md 给出的调用方式,先检查脚本,再从 stdin 传入 JSON:
python3 scripts/timeline_check.py < selected-input.json
在仓库根目录直接运行示例可以复现如下输出(实测):
{"blockers": [], "durationSeconds": 5.0, "render": "NOT_RUN", "syncAndCaptionAccuracy": "NOT_EVALUATED", "timeline": [{"durationSeconds": 3, "endFrame": 90, "source": "clip-a", "startFrame": 0, "transcript": "这是合成转录,不是真实用户口播。"}, {"durationSeconds": 2, "endFrame": 90, "source": "clip-a", "startFrame": 90, "transcript": "第二段合成转录。"}]}
注意两段 startFrame / endFrame 首尾相接(0–90、90–150),这正是契约里“输出连续帧区间”的落点:帧区间由成片时间线游标决定,而不是由原素材的 in/out 决定。
从秒到帧:游标累加与取整规则
核心计算只有几行,但每一行都对应一条契约约束(timeline_check.py):
blockers, timeline, cursor = [], [], 0.0
for row in items(data["clips"]):
record(row, "source in out transcript")
require(row["source"] in sources, "missing source reference")
source = sources[row["source"]]
start, end = number(row["in"]), number(row["out"])
require(0 <= start < end <= source["duration"], "clip outside source duration")
require(isinstance(row["transcript"], str), "transcript must be supplied text")
if source["rights"] != "CLEARED": blockers.append("UNCLEARED_SOURCE:" + row["source"])
duration = end - start
frame_start, frame_end = round(cursor * fps), round((cursor + duration) * fps)
require(frame_end > frame_start, "clip shorter than a timeline frame")
timeline.append({"source": row["source"], "startFrame": frame_start, "endFrame": frame_end,
"durationSeconds": duration, "transcript": row["transcript"]})
cursor += duration
几个容易被忽略的细节:
in/out不是绝对时间轴上的位置。它们的差值end - start才是该段在成片里占用的长度;cursor从0.0开始按片段顺序累加,因此输出帧区间永远从 0 开始连续排列,与你从原素材的哪一秒开始取无关。- 帧号使用 Python
round()(银行家舍入),不是int()截断。契约与方法文档都提示:极短片段可能被舍入成 0 帧,脚本用require(frame_end > frame_start, "clip shorter than a timeline frame")直接拒绝这种片段,而不是静默产出一个空区间。实测in: 0, out: 0.0166在fps: 30下即报INVALID_INPUT: clip shorter than a timeline frame(exit 2)。 fps是全局统一值,脚本不接受逐片段帧率。这是“帧边界要用统一 fps”的代码化表达。sources[].duration只用于越界判断,不会被换算成帧;素材真实时长不参与cursor。
输出字段与“语义缺口”
输出是固定形状的 JSON,由 json.dumps(..., ensure_ascii=False, sort_keys=True, allow_nan=False) 序列化,键名排序稳定,便于比对与留存:
| 输出字段 | 含义 | 生成方式 |
|---|---|---|
timeline[] |
连续帧区间列表 | 每段含 source、startFrame、endFrame、durationSeconds、transcript |
timeline[].durationSeconds |
out - in 的秒数 |
保留原始数值(示例中为整数 3、2) |
durationSeconds |
全片总时长 | cursor 累加结果 |
blockers[] |
语义缺口清单 | sorted(set(blockers)),去重且有序 |
render |
渲染状态 | 恒为 "NOT_RUN" |
syncAndCaptionAccuracy |
同步与字幕准确度 | 恒为 "NOT_EVALUATED" |
blockers 只会出现三种取值:
| blocker | 触发条件 | 性质 |
|---|---|---|
UNCLEARED_SOURCE:<id> |
引用的素材 rights != "CLEARED"(即 UNKNOWN) |
权利缺口,每段一条,最终按集合去重 |
EMPTY_TIMELINE |
clips 为空数组 |
结构合法但无内容 |
DURATION_EXCEEDS_TARGET |
总时长 cursor > maxDuration |
超出目标时长 |
关键区分:blockers 非空并不导致进程失败。脚本把它作为输出字段返回,exit code 仍是 0。契约里“语义缺口在输出字段中保持可见”说的就是这件事。实测给一个 rights: "UNKNOWN"、总长 3 秒但 maxDuration: 1 的输入,得到 {"blockers": ["DURATION_EXCEEDS_TARGET", "UNCLEARED_SOURCE:a"], ...} 且退出码为 0;而空 clips 只产出 ["EMPTY_TIMELINE"]。
退出码与负例:什么算“输入结构/引用错误”
脚本把所有可捕获异常统一映射为 INVALID_INPUT: <message> 打到 stderr,并以 exit 2 结束:
raw = sys.stdin.buffer.read(1048577)
require(len(raw) <= 1048576, "input exceeds 1 MiB")
data = json.loads(raw, object_pairs_hook=unique_object,
parse_constant=lambda _: (_ for _ in ()).throw(ValueError("nonfinite JSON")))
print(json.dumps(compute(data), ensure_ascii=False, sort_keys=True, allow_nan=False))
捕捉的异常类型是 (ValueError, TypeError, KeyError, OverflowError)(timeline_check.py)。契约中“具体输出与负例记录在交付根 validation 中”提示的正是:交付时要把这些失败样例与真实输出一起归档,而不是只写一句“检查通过”。
以下负例均在本仓库中实测,可直接复现:
| 负例输入特征 | 退出码 | stderr |
|---|---|---|
顶层多写一个字段(如 asOf) |
2 | INVALID_INPUT: unexpected or missing fields |
片段多写一个字段(如 extra) |
2 | INVALID_INPUT: unexpected or missing fields |
sources 中 id 重复 |
2 | INVALID_INPUT: duplicate id: a |
rights 为 "PENDING" 等其他值 |
2 | INVALID_INPUT: invalid rights state |
fps 写成布尔值 true |
2 | INVALID_INPUT: finite number required |
transcript 缺失或非字符串 |
2 | INVALID_INPUT: transcript must be supplied text |
in >= out 或 out > source.duration |
2 | INVALID_INPUT: clip outside source duration |
| 片段长度舍入后不足 1 帧 | 2 | INVALID_INPUT: clip shorter than a timeline frame |
transcript 为空字符串 "" |
0 | (合法:表示未提供口播文本) |
| JSON 中出现重复键 | 2 | invalid JSON object key ...(由 unique_object 抛出) |
NaN / Infinity 字面量或数值 |
2 | nonfinite JSON / finite number required |
| 输入超过 1 MiB | 2 | input exceeds 1 MiB |
“不允许重复 id / 未声明字段”这两条并不是抽象约定,而是 indexed() 与 record() 的直接行为;连 JSON 层面的重复键也会被 object_pairs_hook 拦下,避免“后值覆盖前值”造成的隐式歧义。
关于契约里的日期条款:asOf 与脚本实现的差异
contract.md 末句写明:“日期按 ISO 日历日,不读取机器当前时间;asOf 必须由本轮材料明确。”这是 Bot 包 evidence 技能的通用模板措辞——同一句话也出现在其他包的契约里(例如 ad-spend-watch 的 contract.md),而那边的脚本确实包含 asOf 字段并用 date.fromisoformat 解析。
但 video-editor-evidence 的 schema 是 fps sources clips maxDuration,没有 asOf。实测在输入里加 "asOf": "2026-10-15" 会得到 INVALID_INPUT: unexpected or missing fields(exit 2)。因此对这个技能而言:
- 时间计算全部基于“秒”的相对量(
in、out、duration、maxDuration),不读取系统时间,也没有“今天”这类隐含基准; - “日期按 ISO 日历日、不读机器当前时间”的精神仍然成立——脚本不调用任何时间 API;
- 如果交付文档需要记录检查发生的日期,应写在交付侧的 validation 记录里(ISO 日期,来自本轮材料),而不是塞进本技能的输入 JSON。
这一差异也说明:契约描述的是“这一类 evidence 技能的共性纪律”,具体字段形状必须以本包的 input.json 与脚本为准——契约自己就写了“字段形状见 input.json”。
契约在 Bot 包中的位置:打包期如何被约束
这份契约不是随手放的 Markdown,它受打包校验约束。video-editor 包在 manifest 中把该技能登记为:
{"slug":"video-editor-evidence","name":"时间线检查",
"description":"检查原创剪辑计划的时间线/素材引用和权利声明,输出连续帧区间;不处理媒体或渲染。",
"bodyPath":"skills/video-editor-evidence/SKILL.md",
"scripts":["skills/video-editor-evidence/scripts/timeline_check.py"],
"resources":["skills/video-editor-evidence/templates/input.json",
"skills/video-editor-evidence/templates/contract.md"]}
见 manifest.json。加载侧 nativePackage.ts 会做三件事:
bodyPath必须严格等于skills/<slug>/SKILL.md,slug必须匹配^[a-z0-9][a-z0-9-]*$;bodyPath + scripts + resources的引用集合必须与该目录下的全部文件一一对应(数量相等、无遗漏、无越界前缀),contract.md因此不能被“顺手多放”;- 所有文件交给
validateBotSkillFiles校验路径安全(拒绝反斜杠、./..、绝对路径),并在写入时用0o600权限落盘(可执行文件才用0o700)。
包级还有更外层的硬约束:单文件 ≤ 2 MiB、总大小 ≤ 16 MiB、文件数上限 200,manifest.integrity.files 记录每个文件的 SHA-256,packageHash 由规范化 JSON 计算;BOT_PACKAGE_VERSION 固定为 0.5.1,包 ID 必须在 BOT_PACKAGE_IDS 白名单内。测试 nativePackage.test.ts 验证了“每个 package 的 *-evidence 目录下恰好一个脚本,且实际发布文件集合与预期的 SHIPPED_ONLY 清单完全一致”——也就是说,contract.md、input.json、SKILL.md、脚本四件套是刻意最小化的分发面。
从源码结构看,这套设计让契约、示例和实现三者被绑在一起:契约改字段 → 示例必须同步 → 脚本 record() 会立刻拒绝旧输入 → 打包校验仍能通过但运行时会失败。契约因此具有可执行性,而不只是文档。
与剪辑交付流程的衔接:PASS 之后仍要做什么
video-editor-ops 技能把本技能放在第 4 步:先登记素材、按真实转录选段、交剪辑计划,然后用 timeline_check.py 核对时间段是否越界、引用是否缺失、是否出现极短帧段、总时长与权利状态(video-editor-ops/SKILL.md)。它同时明确:“这是计划结构检查,不是音画同步验收。”
因此正确的解读方式应当是:
blockers: []只表示结构上没有发现越界、缺失引用、空时间线、超时长或权利未清;- 它不表示素材真的存在、真的已获授权、真的能解码,也不表示
transcript是真实口播; render: "NOT_RUN"与syncAndCaptionAccuracy: "NOT_EVALUATED"是输出的一部分,任何转述都不应省略它们;- 成片交付仍需逐段检查首尾、切点、字幕原话、同步、静音/黑帧与导出参数,并区分事实、推断与未知(交付模板见 delivery.md)。
方法文档里还有一句值得单独强调:真实用户素材、肖像、音乐与生成图片要分别核权。脚本只能看到 sources[].rights 这一个显式声明字段,它无法区分“素材权利”和“音乐权利”,也无法判断声明的真伪——这正是“脚本不核实远端内容”的边界所在。
自检清单:把契约用对
在上交或复用这份检查前,可以按以下顺序自查:
- 字段集是否精确:顶层只有
fps、sources、clips、maxDuration;每个source只有id、duration、rights;每个clip只有source、in、out、transcript。不要夹带asOf、备注或自定义字段。 - 未知是否显式:拿不准授权就写
"UNKNOWN",让它出现在blockers里;不要留空、不要写null、不要写"PENDING"。 - 时间单位是否一致:
duration、in、out、maxDuration全部为秒;fps为全片统一帧率且不超过 240。 - 是否可能被舍入成 0 帧:高 fps 下的极短片段会直接导致 exit 2,需先合并或延长片段。
- 是否区分了检查与验收:把
render与syncAndCaptionAccuracy原样带进交付记录,不把 exit 0 说成“已交付成片”。 - 是否留存了负例:至少保留一条结构错误(exit 2)与一条语义缺口(blockers 非空但 exit 0)的真实输出,作为交付根 validation 的一部分。
- 是否只读运行:直接从 stdin 喂入选择后的 JSON,不让脚本接触网络、Home 目录或媒体文件——这既是契约承诺,也是该技能可安全用于本地数据处理的前提。
把这份契约当作接口说明、把脚本当作它的可执行副本,再把它放回 video-editor-ops 的六步流程里,video-editor-evidence 的价值就很清晰:它用最小的输入面,把“剪辑计划是否结构自洽、权利是否声明清楚、帧区间是否连续可用”变成一段可复现的 JSON,而不是一段无法核对的自然语言承诺。