影片轉短影音是做什麼的？

依賴項

/video-understand 是先決條件。請先執行它，以便短影音使用經過驗證的來源轉錄文稿和正規時間軸。開始之前，請確認它已安裝。如果未安裝，請警告使用者缺少此先決條件，並在處理媒體前停止。

需要在 PATH 上存在 ffmpeg/ffprobe，以及一個安裝了 Pillow 的 Python 環境。在處理媒體前檢查它們。

範圍

此技能包含兩個專案階段：

渲染前規劃： 將理解的轉錄文稿映射到節目時間，撰寫並批准候選片段，並寫入 work/shorts/shorts-plan.json。此階段不產出最終影片。
渲染後最終化： 在每個選定的主序列剪輯被批准且共享的主要交付成果驗證完成後，重新執行 plan.py 以將相同的已批准範圍綁定到該交付成果，然後提取橫向以及可選的直向輸出。

它負責短影音候選片段的判斷、確定性資格審查、橫向提取、與短影音相關的轉錄文稿，以及可選的確定性直向交付。它不會在專案模式下進行轉錄、更改主序列、添加字幕/圖形、調色、發布，或執行連續的主體追蹤。

交付的短影音是 final/final-video.mp4 的衍生產品，但候選規劃在此檔案之前進行。將操作記錄在專案 DAG（有向無環圖）中，但切勿將其添加到 sequences.main.operations 中；主要的交付成果及其原始 vs 最終的比較保持不變。

專案輸入

work/project.json
由 project.source.path 記錄的專案來源
work/understand/transcript.json（以來源時間為準）
work/timeline.json
每個階段活躍的主操作修訂版本

規劃不需要 final/final-video.mp4。最終化和提取需要該精確的專案渲染，且其狀態為 render.status: verified。

prepare_transcript.py --timeline 會呼叫共用的 projectlib.map_transcript_to_timeline。因此，候選/提取時間是實際最終影片上的「節目秒數」。被主剪輯移除的單詞不適用於短影音。每個保留的單詞將保留其 source_range、program_range 和 clip_id。

專案轉錄稿元資料會透過絕對路徑、大小、修改時間和 SHA-256 將專案來源、來源轉錄稿和時間軸綁定在一起。候選審查影格會將其節目時間戳記透過 timeline.json 映射回來源影片。當綁定發生變更時，候選驗證會拒絕。

輸出佈局

work/shorts/
|-- transcript.json
|-- transcript_metadata.json
|-- candidates.json
|-- shorts-plan.json
|-- review/
|   |-- candidate_review.json
|   `-- approved_candidates.json
`-- short-001/
    |-- transcript.json
    |-- extraction-report.json
    `-- vertical-agent/
        |-- agent_vertical_plan.json
        |-- vertical_plan.json
        `-- review/vertical_review.json

work/cache/shorts/                 # 可丟棄的影格/連續畫面/中介媒體

review/06-shorts/
|-- candidates-<review-id>.html              # 不可變更的權威頁面
|-- candidates-<review-id>-question.md
|-- assets/candidates-<review-id>/            # 不可變更的開始/中間/結束影格
|-- candidates.html                           # 非權威的最新別名
|-- candidates-summary.md
|-- short-001-horizontal.jpg
|-- short-001-vertical-preview.mp4
|-- short-001-vertical-contact-sheet.jpg
|-- short-001-vertical-preview-summary.json
|-- short-001-vertical-preview-probe.json
|-- <short-id>-vertical-review-<review-id>.html # 不可變更的權威頁面
|-- <short-id>-vertical-review-<review-id>-question.md
|-- <short-id>-vertical-review.html             # 非權威的最新別名
|-- <short-id>-vertical-review-assets/
|   `-- <review-id>/                             # 不可變更的權威證據
|       |-- preview.mp4                          # 若為 REVIEW_REQUIRED 則不存在
|       |-- contact-sheet.jpg                    # 若為 REVIEW_REQUIRED 則不存在
|       |-- preview-summary.json
|       `-- media-probe.json
`-- shorts-summary.md

final/shorts/
|-- short-001-horizontal.mp4
`-- short-001-vertical.mp4          # 僅在選中並批准時存在

節目轉錄文稿

從儲存庫根目錄執行：

$RepoRoot = (Resolve-Path ".").Path
$SkillRoot = Join-Path $RepoRoot "skills\video-to-shorts"
$ProjectRoot = (Resolve-Path "<project-root>").Path
$Work = Join-Path $ProjectRoot "work"
$ShortsWork = Join-Path $Work "shorts"
$ProjectSource = (Resolve-Path "<project-source-from-work/project.json>").Path
$FinalVideo = Join-Path $ProjectRoot "final\final-video.mp4"
$ShortsReview = Join-Path $ProjectRoot "review\06-shorts"
New-Item -ItemType Directory -Force $ShortsWork,$ShortsReview | Out-Null

python "$SkillRoot\scripts\prepare_transcript.py" $ProjectSource `
  --transcript "$Work\understand\transcript.json" `
  --timeline "$Work\timeline.json" `
  --out $ShortsWork

專案時間軸模式需要正規提供的轉錄文稿。獨立模式可以省略 --timeline；它保留相對於輸入的時間，並可能使用臨時的 video-understand/scripts/transcribe.py 作為備用。不會自動發現轉錄文稿。

創建候選片段

將長片視覺上下文生成到快取中，檢查做出決策所需的每個連續畫面，並手動創建候選片段的 JSON。確定性程式碼驗證編輯判斷；它不會憑空發明候選片段或評分。

python "$SkillRoot\scripts\prepare_visual_context.py" $ProjectSource `
  --timeline "$Work\timeline.json" `
  --out "$Work\cache\shorts\candidate-visual" --interval 15

為了相容性，候選片段的輸入檔名保持為 shorts-candidates.v2。設定 selection.evidence_mode 和每個候選片段的 evidence_mode 為 text_visual。每個候選片段需要：

穩定的 candidate_id、標題和場景類型；
以節目時間表示的完整的 start_time/end_time；
transcript_excerpt 必須精確地等於重疊的轉錄文稿單詞，而不是整個重疊的區段；
所有六個評分項目以及非空白的理由；
非空白的 metadata.editorial_reason；
可選的、已審查的 filler_drop_spans 和視覺證據欄位。

不要提供總 score；驗證器會加總六個維度：

維度	最大值
`hook` (鉤子)	20
`completeness` (完整性)	20
`audience_value` (觀眾價值)	20
`emotion_tension` (情緒張力)	15
`quotability` (可引用性)	15
`pace_editability` (節奏可編輯性)	10

偏好一個完整且可獨立理解的思路，而非較短的片段。在必要時，保留依賴性的採訪者問題、前提、主張支持、反轉或結果。邊界必須落在完整的單詞和思維上。

驗證已創建的檔案：

$CandidateDir = Join-Path $ShortsWork "preview\text_visual"
python "$SkillRoot\scripts\candidates.py" `
  --out $CandidateDir `
  --candidates "$CandidateDir\candidate-input.json" `
  --transcript "$ShortsWork\transcript.json" `
  --project-root $ProjectRoot

這會寫入相容性預覽檔案、持久化的 work/shorts/candidates.json，以及 review/06-shorts/candidates.{html,summary.md}。

審查模式

候選片段選擇和交付模式是一個由雜湊值綁定的大門。交付模式只能是 horizontal_only（僅橫向）或 horizontal_and_vertical（橫向與直向）。

以人工模式開啟綁定的互動頁面：

python "$SkillRoot\scripts\interaction.py" candidate-open --out $ShortsWork --review-out $ShortsReview

該命令會列印一個權威的、作用域為審查 ID 的頁面。回條會透過 SHA-256 將該頁面、其候選片段 JSON、轉錄文稿、來源媒體、固定問題以及每個提取的影格綁定在一起。candidates.html 只是一個非權威的便利別名，指向最新的頁面。使用當前作業系統的原生命令開啟列印的權威路徑：

# Windows PowerShell
Start-Process (Resolve-Path -LiteralPath "<printed-authoritative-page>")
# macOS
open "<printed-authoritative-page>"
# Linux
xdg-open "<printed-authoritative-page>"
# 代理：呈現權威頁面並 STOP。

如果開啟失敗，請重試原生命令，如果仍然無法開啟，則報告失敗。在呈現頁面後不要繼續操作。該頁面最初所有候選片段的核取方塊和兩個交付模式選項都是未選取的狀態。使用者必須選擇 1-5 個候選片段和一個交付模式。綁定的頁面絕不會靜默地選取候選片段。

若要批准，請將頁面生成的此精確結構化摘要原樣複製到 candidate-answer 中：

Shorts candidate review
Review: <review-id>
Candidates: text_visual/cand-001, text_visual/cand-002
Delivery: horizontal_and_vertical

若要修訂，請將頁面生成的此精確結構化摘要原樣複製：

Shorts candidate review
Review: <review-id>
Decision: revise
Changes: <non-empty requested changes>

記錄後續回應，無需改寫：

python "$SkillRoot\scripts\interaction.py" candidate-answer `
  --out $ShortsWork --response-file "<verbatim-summary-file>"

當使用者明確委派決策時：

python "$SkillRoot\scripts\interaction.py" candidate-open `
  --out $ShortsWork --review-out $ShortsReview --decision-mode agent `
  --delegation-note "User delegated shorts selection and vertical approval."

python "$SkillRoot\scripts\interaction.py" candidate-agent-approve `
  --out $ShortsWork `
  --candidates "text_visual/cand-001" `
  --delivery horizontal_and_vertical `
  --rationale "The selected range has a self-contained hook, explanation, and payoff."

代理會開啟並檢查相同的權威頁面，使用明確的候選片段引用、明確的交付模式和非空白的理由。代理絕不會撰寫虛假的人類回應或 user_response。人類模式和代理模式互斥；人類回答指令在代理模式下會失敗，而代理批准指令在人類模式下會失敗。回條驗證會重新檢查審查、頁面和媒體雜湊值。重新生成的來源、候選片段、轉錄文稿、頁面、問題、影格或已批准候選片段的工件會使批准失效。

正規計劃

python "$SkillRoot\scripts\plan.py" `
  --out $ShortsWork --project-root $ProjectRoot

work/shorts/shorts-plan.json 使用整數 schema_version: 1。它記錄了：

target: derived, timebase: program 和 timeline_id；
規劃期間的 delivery_status: awaiting_main_render；
用於候選審查的專案來源和時間軸綁定；
來自活躍主序列的精確 depends_on / based_on 修訂版本；
選擇模式、理由、交付模式和審查 ID；
穩定的短影音 ID；
明確的 program_range 和映射的 source_ranges；
評分/編輯證據、批准的填充詞刪除以及節目時間的保留區間；
工作轉錄稿/報告路徑以及 ../final/shorts/*.mp4 交付路徑。

第一次執行是規劃階段的結束。在此處停止，並按照正規順序繼續處理請求的字幕、內容卡片、圖形動畫和其他剩餘的主序列操作。不要執行 extract_shorts.py，也不要從此技能創建 final.mp4。

在共享渲染器驗證 final/final-video.mp4 之後，重新執行相同的 plan.py 命令。它會重新驗證已批准的專案來源和時間軸，刷新完整的活躍操作修訂版本，添加已驗證的主渲染指紋，並將狀態設定為 delivery_status: ready。時間軸的變更需要新的候選片段和批准；僅影響像素的操作（如內容卡片和字幕）則不需要。

資格審查保持確定性：分數至少 70，完整性至少 15，估計輸出持續時間 20-90 秒，有效的精確摘錄，與排名較高的短影音重疊不超過 50%，且最多輸出五個片段，除非另行配置。

只有孤立的、語義上空的猶豫詞，且具有安全的單詞邊界時，才可以被批准作為填充詞刪除。被拒絕/不安全的區間會連同原因保留在計劃中。總刪除量不得超過 15%，且任何保留區間的長度不得短於 0.15 秒。

橫向提取

python "$SkillRoot\scripts\extract_shorts.py" `
  --video $FinalVideo --out $ShortsWork `
  --project-root $ProjectRoot

在提取之前，腳本會重新檢查主渲染指紋、專案渲染狀態、完整的當前主操作清單及其修訂版本、候選片段回條、已批准的候選片段雜湊值以及來源影片。awaiting_main_render 狀態的計劃會被拒絕。每個保留區間都會變成自己的 seeked -ss/-t/-i 輸入；ffmpeg 會將這些輸入連接起來，並執行一次 H.264/AAC 編碼。它不會針對每個保留區間解碼完整的影片。

選定的最終轉錄文稿單詞和媒體剪切結束點是分開的邊界。提取會在選定內容之後保留至少 0.25 秒的結尾音頻，目標是 0.30 秒。--no-refine-boundaries 僅停用語義短語對齊；它永遠不會停用強制性的結尾處理。如果來源在可以保留所需的結尾處理之前結束，則提取失敗，而不是將短影音標記為已驗證。

相對於短影音的轉錄文稿會排除被刪除的單詞，將後續單詞移動到連續的從零開始的時鐘上，並保留輸入的節目/來源證據。橫向媒體直接前往 final/shorts；工作目錄中僅包含其轉錄文稿和報告。

直向規劃

直向交付從已批准的橫向輸出開始。以間隔 1 秒生成密集的視覺證據，當有動作時則以 0.5 秒的間隔生成。檢查每個連續畫面並撰寫以下策略之一：

STATIC_CROP：一個穩定固定的 9:16 裁切。
SCENE_CROP：場景範圍的固定裁切，對於需要完整橫向資訊的場景僅使用 LETTERBOX。
LETTERBOX：在模糊/變暗的填充背景上顯示完整的清晰前景。
REVIEW_REQUIRED：證據無法支持確定性固定裁切；正式渲染被阻止。

主持人場景應保持頭部和軀幹穩定且大。幻燈片、產品、群組和圖表必須保留必要資訊。不要聲稱進行了連續追蹤。裁切變更應發生在場景邊界。

每個計劃片段完全覆蓋短影音時間線，具有一個策略，並記錄其場景邊界證據、推理以及用於支持圖形的推薦視覺資產（例如標題安全區域）。vertical_plan.json 中的每個片段定義了 method、crop（適用時）、scene_has_transition 和 asset_recommendations。計劃不接受連續追蹤或超過 3 秒的慢速平移/縮放。對於 REVIEW_REQUIRED，證據模式設定為 text 而非 text_visual。

直向預覽

python "$SkillRoot\scripts\vertical_preview.py" `
  --shorts-plan "$ShortsWork\shorts-plan.json" `
  --out "$ShortsWork" --review-out "$ShortsReview" `
  --project-root $ProjectRoot --gpu

為每個批准的直向短影音生成富媒體預覽。對於 REVIEW_REQUIRED 策略，它會跳過預覽媒體，但仍會生成無媒體的審查頁面和總結。會產生 preview-probe.json 審計。支援可選的 --gpu 硬體加速。

直向審查與批准

python "$SkillRoot\scripts\vertical_preview.py" `
  --shorts-plan "$ShortsWork\shorts-plan.json" `
  --out "$ShortsWork" --review-out "$ShortsReview" `
  --project-root $ProjectRoot --review

在人類批准之前，直向輸出會保持等待狀態。每個短影音都會獲得一個不可變更的權威審查頁面和使用者提示。頁面包括預覽、連續畫面以進行視覺檢查，以及批准/修訂/拒絕選項。批准需要在同一運行中串聯執行 extract_shorts.py。

最終的 final/shorts/short-001-vertical.mp4 路徑由 plan.py 決定。

直向提取

python "$SkillRoot\scripts\extract_vertical.py" `
  --shorts-plan "$ShortsWork\shorts-plan.json" `
  --out "$ShortsWork" --review-out "$ShortsReview" `
  --project-root $ProjectRoot

每個短影音獨立渲染，並輸出到列印的路徑。

代理直向規劃 mcp

當 decision-mode agent 存活時，short-plan-agent.json 裝載物會使用 vertical-agent 包裝。

載入 agent 計畫工具：

{
  "method": "load_vertical_plan_agent",
  "params": {
    "agent": {
      "name": "vertical-shorts-planner",
      "url": "",
      "description": "Plans vertical crops for short-001"
    }
  }
}

從 vertical-agent/agent_vertical_plan.json 載入 agent 回應。

記錄 agent 批准的回應，並將證據打包為 vertical-agent/vertical_plan.json。

python "$SkillRoot\scripts\vertical_preview.py" `
  --shorts-plan "$ShortsWork\shorts-plan.json" `
  --out "$ShortsWork" --review-out "$ShortsReview" `
  --project-root $ProjectRoot --vertical-agent-plan-out "vertical-agent/vertical_plan.json"

這會彙整視覺證據並記錄 agent 計畫。

影片轉短影音