Cindy 视频剪辑伙伴时间线检查:video-editor-evidence 输入契约与 timeline_check.py 实战解析

原创2026-10-25 13:49:541,954 阅读
文章标签:人工智能AI Agent代码智能体大模型AI 技能Agent 记忆工具调用MCP Clients多智能体浏览器控制GUI 自动化本地部署插件系统桌面应用移动开发前端跨平台语音任务调度交互助手

Cindy 视频剪辑伙伴时间线检查:video-editor-evidence 输入契约与 timeline_check.py 实战解析

在 Cindy 桌面端内置的「视频剪辑伙伴」Bot 包中,video-editor-evidence 技能承担一项范围极小但边界极严的职责:把一份剪辑计划(时间线、素材引用、权利声明)转换成可核对的连续帧区间,并显式暴露结构性问题。本篇围绕该技能的输入契约 contract.md,逐条落实字段形状、校验规则、退出码与负例,并结合 timeline_check.py 与 Bot 包加载链路,说明这份契约在真实运行中如何被约束、被验证,以及哪些结论它不能提供。

契约要解决的问题:把“计划”变成可核对的帧区间

契约正文只有一段实质性描述,但它同时划定了三类边界:

  1. 输入边界:检查对象是“原创剪辑计划”的时间线、素材引用和权利声明,字段形状由 input.json 定义。
  2. 输出边界:输出连续帧区间(startFrame / endFrame),而不是成片、不是渲染结果、不是音画同步结论(render: NOT_RUN、syncAndCaptionAccuracy: NOT_EVALUATED)。
  3. 信任边界:输入中的状态、来源与许可都是显式声明,脚本不核实远端内容——它不会去云盘取素材、不会读媒体元数据、不会联网确认授权。

这三条边界在 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 会做三件事:

  1. bodyPath 必须严格等于 skills/<slug>/SKILL.md,slug 必须匹配 ^[a-z0-9][a-z0-9-]*$;
  2. bodyPath + scripts + resources 的引用集合必须与该目录下的全部文件一一对应(数量相等、无遗漏、无越界前缀),contract.md 因此不能被“顺手多放”;
  3. 所有文件交给 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 这一个显式声明字段,它无法区分“素材权利”和“音乐权利”,也无法判断声明的真伪——这正是“脚本不核实远端内容”的边界所在。

自检清单:把契约用对

在上交或复用这份检查前,可以按以下顺序自查:

  1. 字段集是否精确:顶层只有 fps、sources、clips、maxDuration;每个 source 只有 id、duration、rights;每个 clip 只有 source、in、out、transcript。不要夹带 asOf、备注或自定义字段。
  2. 未知是否显式:拿不准授权就写 "UNKNOWN",让它出现在 blockers 里;不要留空、不要写 null、不要写 "PENDING"。
  3. 时间单位是否一致:duration、in、out、maxDuration 全部为秒;fps 为全片统一帧率且不超过 240。
  4. 是否可能被舍入成 0 帧:高 fps 下的极短片段会直接导致 exit 2,需先合并或延长片段。
  5. 是否区分了检查与验收:把 render 与 syncAndCaptionAccuracy 原样带进交付记录,不把 exit 0 说成“已交付成片”。
  6. 是否留存了负例:至少保留一条结构错误(exit 2)与一条语义缺口(blockers 非空但 exit 0)的真实输出,作为交付根 validation 的一部分。
  7. 是否只读运行:直接从 stdin 喂入选择后的 JSON,不让脚本接触网络、Home 目录或媒体文件——这既是契约承诺,也是该技能可安全用于本地数据处理的前提。

把这份契约当作接口说明、把脚本当作它的可执行副本,再把它放回 video-editor-ops 的六步流程里,video-editor-evidence 的价值就很清晰:它用最小的输入面,把“剪辑计划是否结构自洽、权利是否声明清楚、帧区间是否连续可用”变成一段可复现的 JSON,而不是一段无法核对的自然语言承诺。

登录后查看全文
cindy