Cindy 视频剪辑伙伴 delivery.md 交付模板实战：从剪辑计划、时间线校验到 NOT

【免费下载链接】cindy

Consider it done. The open-source AI agent that works out of the box · 想到，就能做到。开源、开箱即用的 AI Agent。

项目地址：https://gitcode.com/GitHub_Trending/cind/cindy

在 Cindy 的「视频剪辑伙伴」中，delivery.md是一份"剪辑计划（待审）"交付骨架：它把素材权利、目标规格、逐段切点、禁用项和渲染后检查压缩到一页纸内，让用户在动手渲染前就能审阅取舍。本文以该模板为主线，结合同一伙伴包内的video-editor-ops规程、timeline_check.py离线校验脚本与宿主装载逻辑，讲清每一栏该填什么、脚本如何校验、以及为什么"没做的事必须写 NOT_RUN"。

一、模板在伙伴包中的位置与装载链路

模板文件位于伙伴包内：

apps/desktop/resources/bot-packages/video-editor/0.5.1/ ├── manifest.json ├── knowledge/method.md └── skills/ ├── video-editor-ops/ │ ├── SKILL.md │ └── templates/delivery.md ← 本文主角 ├── video-editor-evidence/ │ ├── SKILL.md │ ├── scripts/timeline_check.py │ └── templates/{input.json,contract.md} └── video-editor-getting-started/SKILL.md

在 manifest.json 中，video-editor-ops这个 Skill 通过resources字段显式声明了模板：

{ "slug": "video-editor-ops", "bodyPath": "skills/video-editor-ops/SKILL.md", "scripts": [], "resources": ["skills/video-editor-ops/templates/delivery.md"] }

宿主并不会因此"随便读一个文件"，而是做了三重约束（见 nativePackage.ts）：

bodyPath必须严格等于skills/<slug>/SKILL.md，slug 必须匹配^[a-z0-9][a-z0-9-]*$；
bodyPath、scripts、resources三项合并后不得重复，且每一项都必须以skills/<slug>/为前缀；
该前缀下的实际文件集合必须与声明列表一一相等——多一个文件、少一个文件都会以INVALID_PACKAGE拒绝。

也就是说，templates/delivery.md不是可选的随手引用，它被写进了包契约；每个文件的内容还会走read()与manifest.integrity.files的 SHA-256 校验。装载后，文件由 validateBotSkillFiles 进一步检查路径合法性（拒绝反斜杠、.、..与绝对路径），再落到<userData>/bot-skills/<botId>/skills/<slug>/下，由引擎按目录挂载。测试 nativePackage.test.ts 中的SHIPPED_ONLY列表把这套文件清单固化为回归断言，因此模板内容与路径都属于可验证的交付事实。

一个值得注意的细节：video-editor-getting-started在 nativePackage.ts 中被filter掉——它是宿主的开场管线，只以问候形式出现，不会作为可列出的 Skill 卡片展示。真正进入工作流的，是video-editor-ops（规程）与video-editor-evidence（时间线检查）。

二、模板原文逐行拆解

模板全文如下（这就是你在伙伴工作目录中会拿到的骨架）：

# 视频剪辑伙伴 # 剪辑计划（待审） 素材/权利： 目标：时长/比例/fps/用途 | 段落 | 素材id | in/out | 原话 | 切法及理由 | B-roll/音乐权利 | |---|---|---|---|---|---| 禁用项： 渲染后检查：切点/字幕/同步/黑帧/音量/导出；未做项目明确NOT_RUN。

它看起来极简，但每一行都对应 SKILL.md 操作顺序中的一个强制动作：

模板要素	对应规程步骤	约束含义
`# 剪辑计划（待审）`	第 3 步"先交剪辑计划"	计划是待审状态，用户批准前不得渲染
`素材/权利：`	第 1 步"登记实际素材 id、时长、分辨率、来源权利"	素材必须真实登记，权利状态显式声明
`目标：时长/比例/fps/用途`	第 3 步"目标比例和时长"	四个维度共同决定输出规格与帧边界
表格六列	第 2、3 步"依真实转录取段落""段落顺序、in/out、字幕处理、B-roll/音乐来源"	逐段的因果链必须可审阅
`禁用项：`	第 1 步"用户禁用项"	用户的绝对禁止项必须落到纸面
`渲染后检查：`	第 6 步"逐段检查首尾、切点、字幕、同步、静音/黑帧与导出参数"	未执行项必须显示为`NOT_RUN`

2.1 素材/权利栏

填写的不是"一批素材"，而是可核对的清单：素材 id、时长、分辨率、来源与权利。规程明确要求区分"事实/推断/未知"，所以没有核实到的内容只能写未知，不能凭经验补全。若素材放在云盘（例如 Google Drive），规程允许用用户已有的云盘工具下载到任务目录，且默认只读；ffprobe只在"工具实际存在且获准读取所选文件"时才可用，不自动安装。

这与timeline_check.py的权利字段是同一套语义：源素材的rights只接受CLEARED或UNKNOWN两个值（timeline_check.py）。模板没有"大概没问题"这种中间态。

2.2 目标栏

时长/比例/fps/用途四项缺一不可：

时长对应脚本的maxDuration，是总时长的硬上限；
比例与用途决定竖屏口播的构图与交付渠道；
fps是整条时间线唯一允许的帧率基准，直接决定帧边界计算。

fps 的取值范围被限定在0 < fps <= 240，maxDuration必须为正数。混合帧率素材必须在计划里先统一，否则脚本算出的帧号没有意义。

2.3 六列表格：段落、素材 id、in/out、原话、切法及理由、B-roll/音乐权利

段落：输出顺序。脚本用游标累加的方式把段落顺序直接映射为成片时间线，计划表里的行序就是成片播放序。
素材 id：必须能在素材清单里找到，否则脚本报missing source reference。
in/out：原素材的入点与出点，不是成片时间。知识文档 method.md 特别强调："source in/out 是原素材时间，timeline frame 是成片帧，二者不同"，混用是剪辑计划最常见的误判来源。
原话：必须来自真实转录。规程第 2 步写明"没有转录不能伪造说过的话"；脚本对transcript的要求是"必须是字符串"，空串可以通过结构校验，但语义上空转录本身就该在人工审查时被打回。
切法及理由：为什么在这里进、在这里出——保留原意与关键限定词，而不是为凑时长硬切。这列是给用户批准用的，脚本不校验。
B-roll/音乐权利：素材、肖像、音乐与生成图片要分别核权（见 method.md）。未获许可的音乐或素材不能进成片。

2.4 禁用项栏

用户说过"绝对不要的处理"（跳切、变速、花字、某类转场……）必须逐条写出。它是后续修订的判据，也是交付时自检的清单；口头答应不算落地。

2.5 渲染后检查栏

模板给出的检查项是：切点 / 字幕 / 同步 / 黑帧 / 音量 / 导出，并附一句关键约定——未做项目明确 NOT_RUN。这与脚本输出的固定字段一致：render: "NOT_RUN"、syncAndCaptionAccuracy: "NOT_EVALUATED"。规程第 6 步还要求"记录真实版本和未测项""保留原素材与可回退版本""只交本地可审阅文件，不自动发布"。

三、把计划变成可校验输入：input.json 契约

delivery.md的表格是给人看的，timeline_check.py的输入是给它自己看的。二者字段一一对应，转换时只需机械映射。契约模板见 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 }

字段形状由 contract.md 定义：顶层只允许fps、sources、clips、maxDuration四个键，sources行只允许id、duration、rights，clips行只允许source、in、out、transcript。脚本用record()做精确集合比较（timeline_check.py），多一个或少一个字段都直接失败；重复 id、重复 JSON key 同样拒绝。

对应的delivery.md填写示例（数据即上面这份合成样例，可直接对照）：

# 视频剪辑伙伴 # 剪辑计划（待审） 素材/权利： - clip-a｜时长 20s｜分辨率 1080x1920（示例）｜来源：用户提供｜权利：CLEARED 目标：时长 ≤10s / 9:16 / 30fps / 竖屏口播短视频 | 段落 | 素材id | in/out | 原话 | 切法及理由 | B-roll/音乐权利 | |---|---|---|---|---|---| | 1 | clip-a | 1.0-4.0 | 这是合成转录，不是真实用户口播。 | 保留开场完整陈述，结尾落在句末停顿 | 无 B-roll；背景音乐 UNKNOWN，暂不入片 | | 2 | clip-a | 8.0-10.0 | 第二段合成转录。 | 承接上段语义，掐掉中间冗余过渡 | 无 | 禁用项：无跳切、无变速、不加花字 渲染后检查：切点 NOT_RUN / 字幕 NOT_RUN / 同步 NOT_RUN / 黑帧 NOT_RUN / 音量 NOT_RUN / 导出 NOT_RUN

注意示例中把 B-roll 与音乐的权利单独标注为UNKNOWN并明确"暂不入片"——这比笼统写"有版权"更符合模板意图。

四、运行时间线校验：命令、输出与退出码

脚本的使用方式在 video-editor-evidence/SKILL.md 中规定为先检查脚本、再从 stdin 传 JSON：

cd apps/desktop/resources/bot-packages/video-editor/0.5.1 python3 skills/video-editor-evidence/scripts/timeline_check.py \ < skills/video-editor-evidence/templates/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": 150, "source": "clip-a", "startFrame": 90, "transcript": "第二段合成转录。"} ]}

退出码为0。可以看到三个关键结论：

帧号由脚本计算，不由人算。startFrame = round(cursor * fps)、endFrame = round((cursor + duration) * fps)（timeline_check.py），3s 段落在 30fps 下为 0–90，2s 段落接续为 90–150。由于 Python 的round()采用"四舍六入五成双"，手工按普通四舍五入复算极小概率会差一帧，以脚本输出为准。
durationSeconds是累加值，不是maxDuration；样例 5.0 秒未超 10 秒上限。
render恒为NOT_RUN。脚本只做计划结构检查，不碰媒体、不渲染，因此它给的任何"通过"都不等于成片可用。

4.1 语义缺口不会被静默吞掉

把rights改为UNKNOWN、并把第二段拉到 8–14（总长 9s、上限 8s）后，脚本仍以0退出，但blockers变成：

{"blockers": ["DURATION_EXCEEDS_TARGET", "UNCLEARED_SOURCE:clip-a"], ...}

也就是说：结构合法与语义合规是两回事。当前实现只会产出三类 blocker（timeline_check.py）：

blocker	触发条件	处置
`UNCLEARED_SOURCE:<id>`	该素材`rights != "CLEARED"`	先补授权，或从成片候选中剔除
`EMPTY_TIMELINE`	`clips`为空	计划尚未成立，不能提交审批
`DURATION_EXCEEDS_TARGET`	累计时长 >`maxDuration`	回表重排 in/out，而不是改大目标敷衍

4.2 结构错误以退出码 2 终止

把某段的out写成超出素材时长（例如素材 20s 却写in:19, out:21），脚本走异常分支：

INVALID_INPUT: clip outside source duration

退出码2。同类失败还包括：顶层/行内字段集合不符、fps超出(0,240]、maxDuration <= 0、素材duration <= 0、权利值不在白名单、素材引用缺失、重复 id、重复 JSON key、非有限数值（NaN/Infinity）、输入超过 1 MiB（timeline_check.py）。

还有一个容易踩的边界：in < out且区间合法，仍可能因为"短于一帧"被拒。当round(end*fps) == round(start*fps)时报clip shorter than a timeline frame——这正是 method.md 提醒的"极短片段可能四舍五入成 0 帧，需拒绝"。

4.3 脚本的运行边界

按 SKILL.md 的说明与源码实现，该脚本：只依赖 Python 3.10+ 标准库；只经 stdin/stdout 通信；不访问网络与 Home 目录；不写文件；不执行子进程；安装与打包过程不会执行它；单次输入上限 1 MiB，数组最多 10000 条。因此它可以安全地在计划评审阶段反复运行，但它不产生任何凭证、授权、测试或连通性证明。

五、从计划到成片：模板如何驱动后续动作

模板不是"填完就归档"的表单，它串联着规程的剩余步骤：

先计划后制作。ops 第 3 步"先交剪辑计划"，第 5 步才在"用户批准计划后"动手；这段顺序在模板里体现为标题的"（待审）"。
工具缺失时交付缺口，不承诺渲染。若本机没有获准使用的视频工具，正确产出是"批准后的剪辑计划 + 缺口说明"，而不是伪造一个输出文件。规程同时禁止自行安装依赖、禁止把缺失的 Whisper/SyncNet 说成可用。
逐段自检，然后如实记录。首尾、切点、字幕原话、同步、静音/黑帧、导出参数——没做的写NOT_RUN，没测的写未测，不因为"看起来没问题"改成 PASS。
保留可回退版本。原素材与历史版本不得被覆盖，"交付"只意味着交付一个本地可审阅的文件，不自动发布。
事实/推断/未知分开。ops 的"输出与持续协作"一节要求使用本模板，并明确三类信息不得混写，这也和method.md的口径一致。

5.1 两个常见误判

把结构 PASS 当成成片 PASS：blockers: []只说明时间段没越界、引用没缺失、总时长没超标、权利状态已声明；它明确不评价音画同步与字幕准确度（输出字段直接写NOT_EVALUATED）。
把渲染成功当成内容正确：method.md 的原话是"渲染成功也不能代替目检"。模板末行的六项检查就是目检清单，缺一项就得写NOT_RUN。