vosjs/vos-cut

從錄製證據中剪輯影片

你正在剪輯某人的錄製（一個 vosso take：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   # fetch, digest, plan, frames, render, push, pull

憑證，按此順序，切勿打印：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"。 你刪除的提案會被放入 rejected（[{id, lane, in, out}]，包含通道和其來源範圍）， 這樣就不會重新規劃，並且由 plan --reuse 攜帶的重新錄製也不會再次提出該節奏； 當人類刪除一個自動範圍時，工作室會自行處理。
• 用圖層而不是鏡頭來指示。 當剪輯指向一個元件（按鈕、卡片、程式碼區塊） 且縮放會放大像素時，將其重繪為 doc.json 中的一個 html 圖層（overlays[] 中的 kind: "html"：標記、以產品自身類型編寫的 CSS、以 1080p px 為單位的設計框）， 放在其主體旁邊，而不是覆蓋在上面。你的倉庫中有產品的真實元件；請使用它們。 標記必須是格式良好的 XML，並且 vos validate 會指出無法渲染的內容；CSS 動畫 在掛鐘時間運行，應使用 anim 和 motion 代替。
• 文件的單位是複製過來的，切勿轉換。 一個時刻的 focus 是縮放範圍的 cx/cy；其 rect 是縮放必須包含的內容。source 範圍是錄製秒數（縮放/速度/傾斜/段落）；output 範圍 是渲染秒數（疊加層/音頻）。任何地方的像素值都是 #1 錯誤。
• 人類的編輯是神聖的。 摘要中的 doc.manual 統計了人類決策的範圍； 如果推送觸及到一個從你的基準點之後被人類編輯過的節點，則會出現 protected_conflict。 除非需求明確指出某個節點，否則保留他們的數值。
• 獨自進行三輪，然後交給人類。 一輪 = 編輯 → 驗證 → 靜態幀 → 判斷。 如果無法在三輪內完成，則推送最佳的一輪並說明原因。
• 需求優先；資料夾中的配方其次；這些預設規則最後。 如果配方中有一行與最近的成員矛盾，在你的備註中稱其為過時，而不是遵從它。

1. 查看

vos fetch <vosId> --media        # 一個你未錄製的託管錄製（doc + 錄製檔案目錄）
vos 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 佔據影格大部分的點擊簇是 一個拖動（瞄準、滾動、移動東西），而不是目標；以及一個 activity 保持在 ~0.1 以上的「空閒」間隔是 影片在播放，而不是空閒。這兩者都不需要規劃器的提案。

如果涉及一個資料夾，在你做出任何決定之前，請讀取其中的所有 .md 檔案（自身的和繼承的）。

2. 敘述

在你的工作筆記中寫下 3-6 個節奏，每個節奏包含其時刻 id、它展示了什麼（來自裁切） 以及它是為了什麼（來自配方、頁面標題、said 或需求）。例如：

B1 m01-m04  畫廊：瀏覽，選擇一個程式            （全景，一個卡片縮放）
B2 m05-m06  混音器開啟工作室                    （這個場景是亮點）
B3 m07-m12  旋鈕：在混音面板上拖動五個滑塊      （一個保持的縮放，中間部分 2× 速度）
B4 m13-m14  結果播放完畢                        （放開，穩定）

錄製沒有附帶需求？從錄製中推斷一個（它展示了什麼，會在哪裡展示， 應該多長）並在版本備註中說明它，這樣如果需求錯了，人類可以在剪輯前糾正它。

如果需求指定了一個節奏（「讓匯出部分更乾脆」），首先將其映射到時刻 id， 並且不要觸碰它們之外的任何東西。

3. 以例外方式決策

對於每個節奏，根據 plan 和配方：

• 縮放。 當規劃器的範圍適合該節奏時保留它；當相鄰的提案屬於同一個節奏時，將它們合併 為一個保持的範圍（每個節奏一個縮放，永遠不是每個點擊一個）；對於一個不是節奏的點擊， 刪除規劃器的提案；對於規劃器跳過的一個單獨點擊，如果裁切顯示它是一個關鍵時刻， 則添加一個範圍。根據矩形確定縮放級別：小控件需要 1.8-2.2，面板 需要 1.4-1.6；當目標佔據影格的大部分寬度時，取景質量檢查決定了級別，請遵從它。 cx/cy = 時刻的 focus。你創建的 id：u1、u2...。在編輯器錄製中，縮放出現範圍的通道， 而不是被拖動的畫布。在導航點擊之前釋放縮放，以便頁面切換以全景播放。
• 速度。 保留打字/空閒/滾動的提案；在 activity 較低且沒有節奏需要的段落， 或拖動簇下方添加 2×-3× 的速度；永遠不要在節奏的高潮部分或在播放期間使用。
• 傾斜。 僅當相機風格有傾斜（tiltStyle/風格的個性）並且節奏值得一個標點時使用。 每個 ~5 秒一個姿勢，範圍 ±5..18°。
• 裁剪。 開頭和結尾：裁剪到第一個和最後一個重要的內容 （segments），在結尾留下約 0.5 秒的穩定時間。加載畫面被裁剪掉。
• 文字。 每個有話要說的節奏一個標題，以一定的節奏（每 5-10 秒一個， 每個持續 2.5-4 秒，永遠不要同時出現兩個），使用產品的用語和影片的意圖； 位置為下三分之一 y ≈ 0.82；時間單位為輸出秒；永遠不要重疊在點擊的控件上（驗證會警告）。 當其下方的背景為淺色時（例如編輯器的時間線），為其添加一個 box， 並在每個標題出現的瞬間對其進行判斷。一個解釋流程的影片只有一個標題太稀疏了； 只有在配方或需求說不需要文字時，零個標題才是正確的。
• 風格。 在一個系列中，在剪輯之前使用 vos plan --style <seed>： 它會複製種子的 zoomStyle/zoomParams/speedParams/tiltStyle/frame/ cursor/cam/export，並在它們下面重新規劃自動範圍。 永遠不要在配方中重述這些數字；種子的文件是它們的家。

將補丁寫入 doc.json 的編輯，永遠不要重寫。保留你不理解的每個欄位。

4. 驗證

vos validate <take>                                   # 確保乾淨；閱讀取景警告，修正它們
vos digest <take> --no-frames                         # 重新調整時間後：新的輸出時間，相同的影格
vos frames <take> --at-moments --at-zooms --times 0,25%,50%,75%,100%
vos frames <take> --times <every caption start + 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，並在報告完成之前查看它。

6. 重新剪輯（人類已查看）

vos pull 會打印他們更改內容的差異摘要（「縮放 z3：級別 2.2→1.6；疊加層 c1 已移除」）。那就是反饋， 以數據自身的語言給出：重新剪輯他們的話要求的內容，而不是他們的手已經修復的內容。 統計輪數。「很好」是他們的詞語，也是種子的唯一退出條件。

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>    # 適用於：任何，種子：無

配方以大寫字母命名，就像 CLAUDE.md 一樣：它是集合在剪輯任何東西之前讀取的檔案。 你歸檔的內容會以其中詞幹大寫的形式儲存，因此終端和檔案庫是一致的。

CUT.md 說明了數字無法表達的內容：節奏詞彙、什麼需要標題以及什麼永遠不需要、保持長度、 標題/結束慣例、時長範圍、要跳過的內容以及人類糾正到種子中的決策（從差異中讀取）。 BRAND.md：排版、調色板、背景、音樂、任何文字的語氣。後來的成員：拉取資料夾、摘要、 從種子 --style 規劃、根據 CUT.md 剪輯、推送 --folder；一個在兩個成員中重複出現的修正 （或人類為所有成員說明的修正）會被附加在 ## 代理備註 下方，標明日期， 並且其上的規則會被重寫以匹配（vos recipe push <file> --asset <id> 原地替換； 先前的內容被保留）。永遠不要沉默地重寫所有者的行。