vosjs/vos-cut

从证据中剪切录制片段

你正在剪切某人制作的录制片段（vosso 录制片段：recording.webm + cursor.json + meta.json + doc.json），而不是录制新的片段。从脚本 录制属于 product-video 技能；程序式录制属于 vos-create/vos-remix。

工作循环是：查看 → 叙述 → 例外决定 → 验证 → 推送 →（人工审查）→ 重新剪切。 每一步都指明了执行该操作的命令。文档是 doc.json；其字段和单位的约定在 https://vos.so/llms-full.txt。这里永远不会重新录制人工的录制片段： 剪切无法修复画面，如果画面无法支撑需求，你需要在备注中说明并停止。

设置

npm i -D @vosjs/cli   # 获取、摘要、规划、帧、渲染、推送、拉取

凭据按以下顺序使用，切勿打印：VOS_API_KEY，然后是 ~/.config/vos/credentials 的第一行，最后是 vos login（浏览器登录，为这台机器生成密钥）。密钥仅创建 私有工作区，且永远不能发布。digest、frames 和 render 需要 Chromium。

0. 覆盖以下所有内容的基本规则

• **永远不要读取视频。**你的眼睛是 vos digest：digest.json，然后是 sheet.png，最后只有在必须做决定时才查看裁剪图。一个 90 秒的录制片段大约有 35 个时刻，如果读取每张图像，则大约需要 25-40k 图像 token；而工作表加上 关键裁剪图大约需要 10k。完成事件会打印此估计值。
• **通过例外进行编辑。**规划器（缩放、速度、倾斜）已经回答了每个点击、 打字过程、滚动和空闲间隙所在的位置。摘要中的 plan 保存了它们的时间跨度， proposed 标明了每个时刻下有哪些建议。保留、合并、删除或重新调整这些建议； 只添加规划器无法知道的内容（哪个单独的点击值得一个节拍、一个字幕、一段不无聊 但也不空闲的快进）。你触摸的每个时间跨度都带有 "source": "manual"。 你 DROP（删除）的建议会进入 rejected（[{id, lane, in, out}]，包括其泳道 和来源范围），这样就不会重新规划，也不会重新录制（plan --reuse 携带的） 该节拍；当人工删除自动生成的跨度时，工作室会自行写入。
• **用图层定位，而不是用摄像头。**当剪切指向一个组件（按钮、卡片、代码块） 并且缩放会放大像素时，将其重绘为 doc.json 中的 HTML 图层（overlays[]， kind: "html"：标记、产品自身样式的 CSS、1080p 像素下的设计框） 放置在主体旁边，而不是覆盖在其上。你已经在仓库中拥有产品的真实组件； 使用它们。标记必须是格式良好的 XML，vos validate 会指出哪些无法渲染； CSS 动画按挂钟时间运行，应避免使用，转而使用 anim 和 motion。
• **文档的单位，复制，永远不要转换。**时刻的 focus 是缩放跨度的 cx/cy； 其 rect 是缩放必须包含的内容。source 范围是 footage 秒（缩放/速度/倾斜/片段）； output 范围是渲染秒（覆盖层/音频）。任何地方的像素值都是 #1 错误。
• **人工编辑是神圣的。**摘要中的 doc.manual 记录了人工决定的时间跨度； 如果推送触及了自你基础版本 409 以来人工编辑过的节点，则显示为 protected_conflict。除非需求明确指定了该节点，否则保留他们的值。
• **三轮独立，然后找人工。**一轮 = 编辑 → 验证 → 帧 → 判断。如果三轮内无法 完成，则推送最佳轮次并说明原因。
• **需求决定；文件夹的配方其次；这些默认值最后。**如果最近成员的配方行 与需求矛盾，则在你的备注中说明已过时，而不是遵守。

1. 查看

vos fetch <vosId> --media        # 一个托管的、你没有录制的录制片段（文档 + 视频素材主目录）
os pull <take> --media          # 一个已链接到 vos.so 的录制片段目录
vos folder pull <slug> --media   # 项目的录制片段，包含配方
vos plan <take> --style <seed doc.json|vosId>   # 在系列中：通过数据继承种子的风格
vos digest <take> [--transcript whisper.json] [--style <seed>]

按以下顺序读取：

1. digest.json → take（时长、页面、是否有光标/麦克风）、moments （id、类型、来源/输出窗口、焦点、矩形、活动、建议、语音）、 plan、doc.manual。如果 hasCursor: false（浏览器录制的录制片段） 则仅列出头部/尾部/场景：通过 activity 安排节奏，仅在需求指定位置时 才缩放，并在备注中说明录制片段没有光标轨迹。
2. sheet.png → 按时间顺序排列的裁剪图，带有嵌入的 id。这是影片概览。
3. m<nn>.crop.png 用于需求或配方认为关键的时刻； m<nn>.full.png 仅用于上下文（什么页面、什么部分）。

读取裁剪图：焦点是什么（控件、字段、内容）；它说什么（标签、输入的值）； 点击的结果是否在下一个时刻的帧或紧随其后的 scene 时刻中可见。scene 是 帧差异跳跃（导航、对话框）；查看其完整帧以命名它。

裁剪图能说明但点击列表不能说明的两件事：一个 rect 占据大部分帧的点击簇 是 DRAG（瞄准、擦洗、移动某物），而不是目标；一个 activity 保持在 ~0.1 以上 的“空闲”间隙是视频正在 PLAYING（播放），而不是空闲。这两者都不需要规划器的建议。

如果涉及文件夹，在决定任何事情之前，请读取其中的 EVERY（每个）.md 文件（自身和继承的）。

2. 叙述

将 3-6 个节拍写入你的工作笔记，每个节拍包含其时刻 ID、它所 SHOWS（展示）的内容 （来自裁剪图）以及它的 FOR（目的）（来自配方、页面标题、said 或需求）。 示例：

B1 m01-m04  画廊：浏览，选择一个节目            (广角打开，一个卡片缩放)
B2 m05-m06  Remix 打开工作室                     (场景是高光时刻)
B3 m07-m12  旋钮：在混音面板上拖动五个滑块     (一个保持缩放，中间 2 倍速)
B4 m13-m14  结果播放完毕                        (释放，稳定)

没有需求伴随录制片段？从录制内容推断一个需求（它展示什么、在哪里展示、 应该多长），并在版本备注中 STATE IT（陈述它），以便人工在需求错误时在剪切前进行 修正。

如果需求指定了一个节拍（“让导出部分更活泼”），首先将其映射到时刻 ID， 并且不要触及这些时刻之外的内容。

3. 决定，通过例外

针对每个节拍，对照 plan 和配方：

• **缩放。**当规划器的跨度能框住节拍时保留它；当多个相邻建议属于同一个节拍时 合并成一个保持跨度（每个节拍一个缩放，绝不是每个点击一个）；删除非节拍点击 上的建议；当裁剪图显示某个被略过的单独点击是关键时，添加跨度。根据矩形确定 级别：小控件需要 1.8-2.2，面板需要 1.4-1.6；当目标是帧宽度的大部分时， 取景 lint 决定级别，遵守它。cx/cy = 时刻的 focus。你创建的 ID： u1、u2… 在编辑器录制中，缩放跨度出现的 LANE（泳道），而不是正在被拖动的 画布。在导航点击之前释放缩放，以便页面切换以宽屏显示。
• **速度。**保留打字/空闲/滚动上的建议；在 activity 低且无需节拍的片段上添加 2×-3×，或在拖动簇下添加；永远不要在节拍的高光时刻上添加，也绝不要在播放时添加。
• **倾斜。**仅当摄像机风格有倾斜（tiltStyle/风格的个性）并且节拍需要标点符号时。 大约每 5 秒一个姿势，±5..18°。
• **修剪。**头部和尾部：剪到第一个和最后一个重要的内容（segments）， 在结尾留下约 0.5 秒的稳定画面。加载屏幕被剪掉。
• **文本。**每个有要说的内容的节拍一个字幕，以一定的节奏（每 5-10 秒一个， 持续 2.5-4 秒，永远不要同时出现两个），使用产品的措辞和视频的意图； 字幕底部 y ≈ 0.82；使用 OUTPUT 秒；永远不要在点击的控件上（validate 会警告）。 当背景颜色浅时（例如编辑器的时间线），为其添加一个 box，并在每个字幕的 瞬间对其进行评判。对于一个解释流程的影片来说，每个影片一个字幕太稀疏； 只有当配方或需求说不要文本时才为零字字幕。
• **风格。**在系列中，在剪切之前使用 vos plan --style <seed>：它复制种子的 zoomStyle/zoomParams/speedParams/tiltStyle/frame/cursor/cam/ export，并重新规划其下的自动跨度。绝不要在配方中重述这些数字；种子的文档是 它们的归宿。

将补丁写为对 doc.json 的 EDITS（编辑），而不是重写。保留你不理解的每个字段。

4. 验证

vos validate <take>                                   # 确保干净；读取取景警告，修复它们
vos digest <take> --no-frames                         # 重新调整时间后：更新 OUTPUT 时间，相同帧
vos frames <take> --at-moments --at-zooms --times 0,25%,50%,75%,100%
os frames <take> --times <每个字幕开始时间 + 1>        # 每个字幕在其自身背景上
vos render <take> check.webm --range a..b --draft     # 变化最大的节拍

将静态帧与 https://vos.so/llms-full.txt 中的质量循环和文件夹的标准进行判断： 模糊度、色度、光标、文本清晰度、首帧和尾帧作为海报；精彩镜头在 3 秒内出现； 结尾稳定；大约每 5 秒不超过一次全帧闪光（ffmpeg -vf "select='gt(scene,0.12)'" 用于计数）。moment-<id> 静态帧及其 <id>.crop.png 共享一个 ID：“那里有什么” 与“剪切显示了什么”并列。

5. 推送

vos push <take> --label "<概要，祈使句，不超过 60 个字符>" --note "<你剪切所依据的需求；包含来源秒数的节拍；你删除和添加的内容>" [--folder <slug>]

基准来自 vos.json。409 stale_base → vos pull，在其上重新应用，再次推送。 409 protected_conflict → 保留人工的值，除非需求指定了该节点（仅在这种情况下 使用 --override <id>）。400 错误会打印字段及其限制。然后执行 GET /api/vos/<id>， 跟随 contentUrls.thumbnail，并在报告完成之前 LOOK（查看）它。

6. 重新剪切（人工审查后）

vos pull 会打印他们更改内容的差异摘要（“缩放 z3：级别 2.2→1.6；覆盖层 c1 已删除”）。 这就是反馈，以数据自己的语言表述：根据他们的 WORDS（话语）要求的内容重新剪切， 并且不要触动他们的 HANDS（手动操作）已经修正过的内容。计算轮次。“好”是 他们的话，也是种子退出的唯一条件。

7. 记住（仅在人工签署种子后）

归档它并写下规则；数字留在种子的文档中。

vos folder create "<系列>" --desc "<用途，不超过 200 个字符>"
vos folder move <vosId> --to <slug>
vos recipe push CUT.md --folder <slug>      # 应用对象：录制片段，种子：<vos id>
vos recipe push BRAND.md --folder <slug>    # 应用对象：任意，种子：none

配方的命名使用大写字母，就像 CLAUDE.md：它是集合在剪切任何内容之前读取的文件。 你归档的文件将以词干大写的方式存储，因此终端和存储系统保持一致。

CUT.md 说明数字无法说明的内容：节拍词汇、何时需要字幕以及何时永远不需要、 保持时长、标题/结尾约定、长度范围、应跳过什么以及人工修正进种子的决定（从差异 中读取）。BRAND.md：字体、调色板、背景、音乐、任何文本的语气。后来的成员： 拉取文件夹、摘要、从种子规划 --style、根据 CUT.md 剪切、推送 --folder； 跨两个成员（或人工为所有成员声明的一个）重复出现的修正会追加到 ## Agent notes 下，带日期，并且上面的规则会被重写以匹配（vos recipe push <file> --asset <id> 会原地替换；保留之前的正文）。永远不要静默地重写所有者的行。