影片加入內容卡片 是做什麼的？
將已核准的語義時刻轉化為一個統一的 HyperFrames 圖形覆疊。使用共用的證據與標準時間軸；請勿在此技能內重新轉錄或重新分析原始素材。
相依性
/video-understand 是一項先決條件。請先執行此技能，以便卡片使用已驗證的語義證據與標準時間軸。
開始前，請確認它已安裝。若未安裝，請警告使用者缺少此先決條件，並在處理媒體前停止。
需要 ffmpeg 在 PATH 中，以及 Python 和 Node.js >= 22（用於 npx hyperframes，按需擷取）。hyperframes render/snapshot 會驅動無頭 Chrome——它會管理自己的 chrome-headless-shell，並在快取版本無法使用時回退到系統 Chrome（設定 CHROME 可覆蓋）。請在處理媒體前檢查這些項目。
輸入
work/project.json：操作版本與相依性work/understand/understanding.json：已審核的語義時刻與證據work/timeline.json：來源到節目的對應，或無剪輯時的身分時間軸- 當對比度或色調是根據該色調評估時，可選的已選色彩校正版本
此技能在沒有剪輯或色彩校正時仍然有效。當字幕啟用時，請先執行它們，依賴它們的當前版本，並將其佔用區域視為硬性排除區域。內容卡片必須在圖形動畫之前，當兩者都啟用時。這些相對規則適用於每一組選定的配對。僅宣告實際使用的相依性，並在 based_on 中記錄其當前版本。
將每個主要或前景人物、講者、演示者、受訪者或語義重要人物的可見臉部與頭部輪廓視為整個卡片提示的硬性排除區域，包括進場與出場。偶爾僅為背景、非敘事或視覺重點的人物可豁免；不確定的情況請保護。如果卡片與受保護的臉部或頭部重疊，請先重新定位，然後縮放或重新設計。當沒有符合規定的放置位置時，則跳過該卡片。
工作檔案
work/content-cards/cards-plan.json # 持久的編輯計畫
work/cache/content-cards/index.html # 程式碼即編輯的合成
work/cache/content-cards-overlay.mov # 透明渲染貢獻
review/03-content-cards/card-stills/ # 每張卡片一張有用的靜止影像
review/03-content-cards/content-cards-preview.mp4 # 可選的短提示視窗
review/03-content-cards/content-cards-summary.md
review/03-content-cards/content-cards-review.html # 本地候選審查面板
review/03-content-cards/content-cards-review-assets/ # 每個候選一張來源幀
review/03-content-cards/content-cards-review.json # 已驗證的人員選擇
可重複使用的審查頁面已提交在
skills/video-add-content-cards/assets/content-cards-review.html。
填入的 HTML、螢幕截圖、覆疊與預覽渲染均為可重現的。
將計畫保留在 cache/ 外部。它必須包含重新生成可處置的 HTML 和 Alpha 資產所需的所有可見字串、時間、放置位置、視覺處理值、渲染器合成路徑、渲染器資產路徑以及來源 FPS（刪除 work/cache/ 後）。記錄一個計畫層級的 renderer_recipe，包含來源範例/模板、合成輸出路徑、渲染引擎以及每個本地執行時期資產的輸出路徑、確切版本、來源和 SHA-256。快取的 HTML 檔案或下載的腳本若無持久的配方，則不滿足重新生成條件。
工作流程
1. 草擬前訪談
首先閱讀 understanding.json 與作用中的時間軸。計算符合條件的圖形時刻數量，並在訪談前建議目標卡片數量：
min(符合條件的時刻, max(1, round(節目分鐘數 / 0.75)))
這是一個目標，不是自動截斷規則。在提問之前，請使用當前作業系統的原生命令自行開啟真實的動畫範例。僅執行一個：
# Windows PowerShell
Start-Process (Resolve-Path 'skills/video-add-content-cards/examples/gallery-animated.html')
# macOS
open skills/video-add-content-cards/examples/gallery-animated.html
# Linux 桌面
xdg-open skills/video-add-content-cards/examples/gallery-animated.html
如果命令失敗，請診斷並重試。請勿用 URI 取代此動作，或要求使用者尋找並點擊檔案。圖庫會比較所有六個主題，並可使用其原生選擇器專注於一欄：
| 主題 | 起始字元 |
|---|---|
almanac | 暖奶油色、襯線、深思熟慮 |
teal | 深色廣播、青色強調 |
editorial | 紀錄片風格、墨水與琥珀色 |
dotgrid | 像素單色、技術感 |
apex | 高能量運動、紅色強調 |
air | 透明 Lexend 字體排版，無背板或遮罩 |
每次僅問一個問題，依此順序：
- 此次剪輯應使用哪個主題？
- 此次剪輯應使用什麼目標卡片數量？提供計算出的建議作為預設值。
- 必須包含哪些卡片類型？提供
intro、key-quote、stat、list和outro；預設為無。
提問後 + 停止。 在第三個答案之後，總結主題、目標數量、必要類型以及使用者提供的任何備註；要求確認。如果使用者取消，保留分析，將操作保留為 draft，且不建立或渲染卡片。
2. 從共用的理解草擬卡片
python skills/video-add-content-cards/scripts/build_cards_plan.py `
work/understand/understanding.json `
work/timeline.json `
work/content-cards/cards-plan.json `
--target-card-count 6 `
--theme editorial `
--must-include-type stat `
--notes "產品名稱請保留原樣"
腳本將保留的語義時刻對應到節目時間，並省略被剪輯移除的時刻。它會保留來源範圍與證據參考，將持續時間限制在所含剪輯片段內，並將文案/放置/視覺處理標記為 draft。stat 以 metric-spotlight 開始；list 以 side-by-side 開始；候選審查可以保留正常佈局或將列表切換為 parallel-columns。
已確認的訪談會作為 brief 儲存在 cards-plan.json 中。對多個值重複使用 --must-include-type；省略不適用的標誌。較舊的可選簡報欄位仍會為了相容性而接受，但並非正常訪談的一部分。
3. 做出編輯決策
在每個卡片時間點閱讀證據。修正 ASR 名稱與數字，剔除較弱的候選者，撰寫簡潔的文案，選擇能避開受保護臉部、可見頭部輪廓與字幕的放置位置，並批准視覺處理。切勿將分析器文字視為最終文案。
將所有螢幕文案儲存在 copy.display 下（例如 eyebrow、title 和 detail），而不僅僅是摘要或建議標題。只有在對照上述受保護的臉部與頭部定義審查過合成的靜止影像後，才將 placement.face_clearance 設為 verified，並在 placement.review_still 中儲存該靜止影像的協定相對路徑。將 HyperFrames 合成、Alpha 資產和確切的合理 FPS 儲存在 renderer 下。
使用以下對應作為起點：
| 語義種類 | 卡片類型 |
|---|---|
| hook | intro |
| key-point、quote、question | key-quote |
| stat | stat |
| list | list |
| cta | outro |
repetition、tangent 和 risk 是編輯證據，而非自動卡片。
保留五種標準卡片類型。在 visual_treatment.layout 下儲存以下可選佈局，而不是建立新的頂層卡片類型：
| 標準卡片類型 | 允許的佈局 |
|---|---|
stat | default、metric-spotlight、bar-chart、pie-chart、line-chart |
list | default、side-by-side、parallel-columns |
僅當一個有證據支持的數字、百分比、金額、倍數、年份或持續時間值得強調時，才使用 metric-spotlight。將數字放在簡潔的上下文之間，適合長值而不重疊，並使數字在這些標籤之間視覺上居中。
對兩到四個簡短的平行、對比、對立或相關概念使用 side-by-side 或 parallel-columns。偏好短語；使用審查來選擇適合可用素材並避開主體的朝向。
僅當保留的逐字稿提供完整、有證據支持的資料集時，才使用圖表。在建立圖表資料之前，請閱讀 reference/chart-data.md。在 data 下手動儲存維度、指標、單位、期間、有序的點以及每個點的逐字稿證據；切勿從分析器摘要推斷值，或合併不同影片的點。對 2-6 個可比較的類別使用 bar-chart，對 2-6 個已證明整體的互斥部分使用 pie-chart，對 3-8 個有意義排序的點使用 line-chart。當缺少所需的值、標籤、分母、時間順序或單位時，請使用 metric-spotlight、正常統計卡片或不使用卡片。
對於圖表佈局，將冗長的解釋壓縮為簡潔的支援文案，而不改變其含義。圖表應主要傳達關鍵值及其變化或關係。請勿列舉或重申圖表中已顯示的值、標籤、期間或單位。
在此階段保留所有有證據支持的候選者。目標是簡報的目標卡片數量，但當證據支持時，允許更強或更稀疏的集合。
4. 審查並套用候選選擇
在候選計畫存在後，為專案產生一個特定的瀏覽器審查頁面。將來源影片對齊到計畫的 source_range 和作用中的時間軸。腳本將每個證據中點限制在其包含的保留剪輯片段中，然後用每個候選者的一個對應來源幀填入已提交的模板：
python skills/video-add-content-cards/scripts/build_review_page.py `
work/content-cards/cards-plan.json `
review/03-content-cards/content-cards-review.html `
--video input/source.mp4 `
--timeline work/timeline.json `
--captions-plan work/captions/captions-plan.json
當專案沒有作用中的字幕操作時，省略 --captions-plan。有了作用中的字幕計畫，審查幀會顯示其實際佔用的上方、中間或下方區域。
立即使用當前作業系統的原生命令自行開啟已填入的審查頁面。僅執行一個：
# Windows PowerShell
Start-Process (Resolve-Path 'review/03-content-cards/content-cards-review.html')
# macOS
open review/03-content-cards/content-cards-review.html
# Linux 桌面
xdg-open review/03-content-cards/content-cards-review.html
如果命令失敗，請診斷並重試；請勿要求使用者定位檔案。該頁面會顯示每個來源幀、卡片 ID、節目時間、可編輯的文案、視覺處理和放置位置。圖表佈局也會顯示可編輯的結構化資料和點證據參考。在批准之前，請根據顯示的證據審查每個值。
每個候選者最初都是未選取狀態，放置位置設為 bottom。更改放置位置會將灰色卡片代理移動到真實幀上方，以便在批准前即可看到碰撞風險。使用者選擇卡片、編輯文案、選擇處理和放置位置、點擊 複製摘要，然後將可見的摘要貼回對話中。
提問後 + 停止。 等待貼上的選擇摘要。請勿根據未檢查的草稿候選者建立 HTML。將摘要轉換為 review/03-content-cards/content-cards-review.json：為每個計畫卡片寫入一個條目，將摘要 ID 標記為已選取，並附上其選擇的文案、視覺處理和放置位置，並將所有其他 ID 標記為未選取，附上其當前草稿文案和空的放置位置。將審查選擇儲存為名為 visual_treatment 的字串欄位。然後套用已驗證的審查：
python skills/video-add-content-cards/scripts/apply_cards_review.py `
work/content-cards/cards-plan.json `
review/03-content-cards/content-cards-review.json
套用步驟會拒絕未知、重複或遺失的卡片 ID、空白的已選取文案、無效的放置位置以及與標準卡片類型不相容的處理方式，而不會更改計畫。成功時，它會保留已選取的卡片，並將其文案、放置位置、視覺處理和頂層審查標記為 approved。在繼續之前，檢查產生的已選取數量是否符合簡報目標。
對於已選取的圖表佈局，套用步驟也會驗證完整的結構化資料，並將 data.status 標記為已批准。任何無效的已選取圖表都會在計畫被複製前拒絕整個審查。選擇非圖表佈局會移除未使用的草稿圖表資料。在套用之後，臉部和字幕的清除狀態會保持待處理，直到根據真實的合成幀檢查合成。
5. 建立一個 HyperFrames 合成
使用一個 index.html 和一個暫停的 GSAP 時間軸。每個已批准的卡片會成為一個由計畫的 program_start_s 和 duration_s 鍵入的 .clip。保持動作可搜尋，並從資料屬性而非時鐘計時器推導時間。
對於圖表提示，僅透過該暫停的時間軸在絕對合成時間進行動畫。長條圖從一個零基線揭示；圓餅圖扇形按點順序揭示，幾何形狀與值成比例；折線圖在點出現之前按 X 軸順序繪製。使用相對於來源的尺寸和固定的佈局框，以便搜尋、標籤和動態值永遠不會導致佈局跳動。建議的持續時間為條形圖和圓餅圖 5-6 秒，折線圖 6-8 秒，始終限制在保留的剪輯片段內。
從最接近的儲存庫範例開始：
examples/index-almanac.htmlexamples/index-apex.htmlexamples/index-dotgrid.htmlexamples/index-editorial.htmlexamples/index-teal.htmlexamples/index-air.html
在所有卡片中保持一種視覺語言，使用相對於來源的尺寸，並維持與所選色調足夠的對比度。五個不透明面板主題可以使用卡片或遮罩來確保可讀性。air 必須保持場景和文字容器透明...
（後續內容因翻譯要求截斷）