video-shotcraft：電影感產品影片製作
一個自包含的製作能力庫：152 張鏡頭配方卡（附 demo 實作原始碼與動態樣片 畫廊）、一支已驗收的完整宣傳片模板、可重複使用元件與音訊資產、六階段工作流程。 當前 focus 是 web/桌面產品宣傳片，但鏡頭卡本身是通用動效詞彙—— 也可以單獨抽卡做任意影片裡的單個鏡頭。
呼叫時先判斷模式
完整宣傳片有三種互不合併的模式。在開始素材採集、分鏡或實現前，先判斷使用者 是否已經明確選擇；已經選擇時直接執行，不重複詢問，也不要改成另一種模式。
- 直接使用模板：保持 Ink Press 原有替換流程。讀
template/TEMPLATE.md， 按既有鏡頭結構替換目標產品的截圖、文案和品牌資訊。 - 自主自由創作：讀
references/pipeline.md。Agent 根據使用者已有要求和專案 內容，自主決定視覺方向、鏡頭映射、分鏡、素材和音訊，連續推進到成片；不在 產品簡報、styleframe、鏡頭映射或分鏡階段暫停等待使用者確認。 - 共同創作：讀
references/guided-free-creation.md。Agent 先提出有依據的 判斷和方案，由使用者依次確認產品簡報、需求決策、視覺方向、鏡頭映射和最終 分鏡；分鏡放行後再進入references/pipeline.md的最終素材採集與製作階段。
使用者提供了專案路徑、網址、錄影或頁面截圖但尚未選模式時，先做一次最小、 唯讀的產品檢查：了解產品定位、主要功能、頁面視覺、可展示狀態和素材風險； 不修改業務專案、不採集敏感資料、不寫影片程式碼。檢查後給出三種模式，並說明：
- Ink Press 是否適合該產品、適合與不適合的具體依據；
- 自主自由創作與共同創作各自是否適合、預計會保留哪些產品視覺線索；
- Agent 推薦哪一種模式及其依據和取捨。
然後明確詢問：「根據上面的產品檢查，我推薦使用 ×× 模式。要按這個模式繼續嗎？」 同時告知使用者：可前往 https://vincentwei1021.github.io/video-shotcraft/ 瀏覽動態樣片，並挑選希望在影片中使用的動效鏡頭。
使用者尚未提供可檢查的專案或頁面時，簡要介紹三種模式再詢問；不要僅因 Ink Press 是現成模板就預設推薦它。
- 使用者選擇模板：完整閱讀
template/TEMPLATE.md，按原模板流程執行。 - 使用者選擇自主自由創作：完整閱讀
references/pipeline.md，Agent 自主推進，不逐階段等待確認。 - 使用者選擇共同創作：完整閱讀
references/guided-free-creation.md，按其中的確認節點協作。 - 使用者尚未決定：停在此處等待選擇；不要預設替使用者選擇，也不要開始製作。
例外一：使用者已點名 Ink Press 模板時，視為模板模式已選定。
例如「用 Ink Press 模板給我的產品做宣傳片」。此時不要再詢問，直接完整閱讀
template/TEMPLATE.md 按模板路線執行。
例外二：使用者已明確指定要使用或參考某些鏡頭卡時，鏡頭約束已經選定。
例如「用 deck-deal-flyin 和 row-embed 做這支影片」或「參考
spotlight-hero-card 的效果」。此時不要介紹模板、也不要詢問是否使用模板；
按 Gallery 名稱解析規則確認指定鏡頭，完整閱讀每張卡，並按卡片的「參考實現」
定位準確 demo 原始碼。單鏡頭可在目標素材明確後執行；完整宣傳片若尚未說明採用
自主自由創作還是共同創作，只詢問這兩種模式，指定鏡頭作為後續製作約束，不自動
等同於共同創作。
四種用法
- 完整宣傳片（模板路線）：想要和模板片高度相似的效果 →
讀
template/TEMPLATE.md，按「換產品重現指南」替換素材逐鏡頭適配。 - 完整宣傳片（自主自由創作）：要新風格並授權 Agent 自主決定 → 讀
references/pipeline.md，從產品理解連續推進到終檢，中途不逐階段等待確認。 - 完整宣傳片（共同創作）：要參與關鍵決策 → 讀
references/guided-free-creation.md，確認產品簡報、需求決策、視覺方向、 鏡頭映射和最終分鏡；放行後從管線的最終素材採集繼續。 - 單鏡頭/單動效：從
references/shots/選卡（或讓使用者在gallery/畫廊裡挑），讀卡全文並按「參考實現」定位準確 demo 原始碼， 適配到目標素材。
自主自由創作與共同創作的邊界
自主自由創作把創意和工程決策交給 Agent。Agent 從專案內容動態推導產品重點、 視覺方向、鏡頭映射、分鏡、素材處理與音訊方案，記錄關鍵判斷後直接執行；除非缺少 無法安全推斷的必要輸入，否則不提問、不逐階段暫停，也不要求使用者確認中間產物。 使用者已有的明確要求始終是約束，不能被 Agent 的預設選擇覆蓋。
共同創作才使用逐階段確認。預設讀 references/guided-free-creation.md，每輪只問
1–3 個最能減少返工的問題，並在產品簡報、需求決策、視覺方向、鏡頭映射和最終分鏡
處暫停等待使用者確認。使用者確認業務與創意方向；Agent 自主完成採集方式、實現參數、
SFX 釘幀、Remotion 工程、渲染和技術 QA。
共同創作中，使用者明確說「你全權決定」或「跳過確認直接做」時，切換為自主自由創作 並記錄這一選擇；不要一邊聲稱自主推進，一邊繼續要求逐階段確認。
功能到鏡頭的映射只是「選用哪些運動語法」，不是完整分鏡。共同創作確認映射後， Agent 必須繼續給出鏡頭順序、時長、具體畫面、頁面狀態、素材來源、字幕、轉場和 SFX；只有完整分鏡確認後才進入最終素材採集。使用者從 Gallery 複製鏡頭名時，只需 提供卡名或「卡名 · 樣式名」，Agent 負責讀取本地配方卡和 demo 原始碼。
核心理念
-
復刻既有頁面必須用真實截圖；手搓 UI 限非復刻場景，且品質與表達 明確性是硬門檻。 表現產品真實頁面時第一步就起本地 dev server， 用無頭瀏覽器截全頁 2x 紋理 + 元素級摳圖 + layout.json 座標表。 非復刻場景（抽象開場/品牌段/獨立展示元件）允許手搓 UI，但達不到 出版級質感或觀眾看不懂它表達什麼，就回截圖路線。頁面資料按風險處理： 公開展示資料只有在產品簡報明確確認後才可保留；客戶、個人、內部、金鑰、 即時或其他敏感資料必須用虛構或脫敏內容，且在採集前凍結。
-
整支影片的視覺語言必須從產品自身生長，不能另造一套不相干的 「宣傳片皮膚」。 做 styleframe 前，先從產品/網站的設計系統、原始碼或 computed styles 中提取並寫入設計 spec：字體家族與字重、字號層級、 行高/字距，網格、間距、對齊、資訊密度與圓角，以及背景/表面/正文/ 強調/狀態色、漸層和材質。片中所有標題、字幕、數字、字卡、版式、 轉場、粒子、光效和其他動效配色都必須重複使用或克制擴展這套 tokens， 同時匹配產品的調性、品味和質感。走模板或鏡頭卡路線時，只繼承其 鏡頭結構、運動語法、節奏和已調參數；字體、排版、配色與材質必須按 目標產品重新蒙皮。若因敘事需要偏離產品視覺，共同創作先說明理由並讓使用者 確認；自主自由創作把理由與取捨寫入設計 spec 後繼續。
-
電影感來自運鏡、光影、節奏與聲音的配合，不來自炫技動畫。 被反覆認可的是：單主角完整動作弧（聚光→推近→懸浮→歸位）、 物理隱喻驅動的加速度（發牌）、側斜機位 orbit 環繞特寫、 riser→impact→sparkle 的聲音句式。批量元素入場靠運動本身， 不靠逐個發光——裝飾性 glint/泛光群發即廉價，單點高品質光效可做。
-
每個鏡頭只講一個動效；關鍵資訊落定後必須呼吸。 一種動畫手法（飛入/堆疊/翻頁）全片只當一次主角，重複鏡頭、重複 tagline 一律刪。節奏偏好是單向的：歷史回饋全部指向「放慢/停留」， 從未有過一次「太慢了」——品牌字標落定 hold ≥1s、批量動效收尾留 0.5s 靜止、開場主體動作給足 3s。排時間線時預先給 hold/rest 留幀預算。
-
強節奏 BGM 的片子，所有轉場和動效必須卡在拍上。 使用者已選好音樂 → 開工前先做節奏分析（librosa 網格擬合求真實 BPM/相位 + kick/snare/hihat 三分類鼓點定位），網格按瞬態覆蓋率 驗收通過後才分鏡；時間線用拍號
beatF(n)寫，稀疏重音釘真實 瞬態而非網格插值點，渲染後從成片抽音軌回測切點誤差 ≤3f。 方法論見references/music-beat-sync.md。 配了 BGM 的片子終渲染固定交付兩版：帶 BGM 版 + 無 BGM 版（保留 SFX）， 靠bgminputProp 從同一時間線渲染出，方便使用者後期自配音樂。 -
用鏡頭卡動效必須先解析 Gallery 索引並讀準確的 demo 實作程式碼。 先用
gallery/api/library.json校驗卡名與style-key，再按卡片文件中的 「參考實現」定位具體 TSX。配方卡給的是語意和參數表，準確的 demo 原始碼 才是調校過的參數真相（緩動、時值 配比、摘罩時機、已知坑的規避寫法）。允許適配性改動，但卡上 「已知坑/命門」標註的參數不得降檔——品質標準只升不降。憑卡名和 理解新寫＝放棄全部調校積累。 -
共同創作把廉價確認物前置，自主自由創作把同樣的判斷留作執行記錄。 產品簡報→需求到執行決策表→文字方向→styleframe→鏡頭映射→分鏡的順序不變； 共同創作逐級交給使用者確認，自主自由創作由 Agent 自主選定並連續推進。兩種模式 都不應在方向未定時進入逐鏡頭實現。
-
驗收貫穿全程 + 交付前獨立審查。 階段 5 起每個鏡頭用
npx remotion still出靜幀自檢、每輪修改後整片渲染 + ffmpeg 抽幀回看；交付前必須派一個乾淨上下文的 subagent 做獨立終檢。審查輸入 包含成片、關鍵幀、產品簡報、需求到執行決策表、當前模式確認或記錄的視覺方向/styleframe、功能到鏡頭映射、 Gallery 卡名/變體、準確 demo TSX、Gallery 參考樣片/抽幀、最終分鏡、選中的鏡頭卡和 審美準則；按references/final-review.md同時檢查方案一致性、功能完整性、鏡頭還原度、視覺/音訊技術品質和資料安全， 逐條出帶幀號證據的報告。製作者對自己的產出有確認偏差，首檢永遠不能交給使用者。 -
確定性渲染：禁
Date.now()/Math.random()，一切偽隨機固定 種子（mulberry32/雜湊，seed 從 index 派生），逐幀可重現。
工作流程
自主自由創作按 references/pipeline.md 從階段 0 連續執行，不逐階段等待使用者確認。
共同創作先按 references/guided-free-creation.md 完成階段 0–3 的產品理解、視覺方向、
鏡頭映射和分鏡確認，再從管線階段 4 的最終素材採集繼續，不得重複提問或重新設計。
階段 2–3 掃 references/shots/ 各卡 frontmatter 按能量曲線選鏡頭；階段 5–7 持續
對照 references/aesthetic-rules.md 自檢；階段 6 讀
references/sound-design.md；卡點片全程貼 references/music-beat-sync.md。
所有模式成片交付後，預設詢問使用者一次是否需要同時匯出剪映工程文件
（可在剪映裡改字幕內容/字號/顏色、分鏡頭變速/重排、調整或替換音訊）；
使用者需要或直接點名匯出時，讀 references/jianying-export.md 執行。
何時讀哪個文件
| 時機 | 讀 |
|---|---|
| 專案啟動且模式未定 | 最小唯讀檢查，然後提供三種完整宣傳片模式並推薦 |
| 自主自由創作 | pipeline.md（Agent 自主完成階段 0–7，不逐階段等待確認） |
| 共同創作 | guided-free-creation.md（確認階段 0–3），再從 pipeline.md 階段 4 繼續 |
| 使用者已選 BGM | music-beat-sync.md（先分析再分鏡） |
| 走模板路線 | template/TEMPLATE.md 全文 |
| 分鏡設計 | sequences/ 橋段模板（全片骨架先填空）；shots/ 全部 frontmatter；選中的卡讀全文 |
| 逐鏡頭實現 | 該鏡頭卡全文 + 按「參考實現」定位的準確 demo 原始碼全文 + assets/lib/ 對應元件 |
| 聲音設計 | sound-design.md + assets/audio/ |
| 驗收 | final-review.md + aesthetic-rules.md 全文過 checklist（獨立 subagent 執行） |
| 成片交付後（剪映工程匯出） | jianying-export.md + jianying-export/ 平台模組 |
資產使用方式
assets/lib/元件 copy 進新專案後自由修改（不 import 本庫）。 清單：PageCam（2.5D 頁面相機——一切「真實頁面」鏡頭的基礎）、DigitRoll、 FlashCut、Caption、FlatPanel、VerticalTicker（3D 無限滾動牆）、 helpers(rand/shake/camera/motion)。FlatPanel 與 helpers/camera 需要three+@react-three/fiber+@remotion/three依賴，其餘僅需 remotion。assets/scripts/capture-template.mjs複製後改頂部 CONFIG（BASE/路由/選擇器）。assets/audio/音效直接複製使用（免費商用授權，見 audio/ATTRIBUTION.md）：audio/bgm/是節奏感強的 BGM 備選；audio/sfx/<類別>/149 個音效按場景分 16 類 （transition impact riser camera ui text paper film light data scifi mech glass fluid crowd counter），找音先進類別目錄，清單見 sound-design.md。 詞彙表 sparkle 的目錄名是light/（無sparkle/）；S1 禁音色不禁動作—— 畫面真有點擊/開關就該配擬音，但ui/裡一半是合成回饋音（tone/bleep/ notification）需逐個試聽、不可整目錄放行（名單見 sound-design 3.3）； 長樣本與輕音素材各有名單需特殊處理（sound-design 4.1）。demos/各卡實作原始碼：多數為自包含灰階 demo（部分 importdemos/_fixtures/Fixtures.tsx的假 UI 場景件，個別 importdemos/_textures/的真實頁面紋理），copy 進 Remotion 專案即可跑； 個別 demo 用到@remotion/motion-blur（CameraMotionBlur），需npm i @remotion/motion-blur，名單見demos/README.md。template/完整可渲染工程：npm install && npx remotion render src/index.ts AiflPromo out/promo.mp4。jianying-export/剪映工程匯出模組：mac_draft.py（Mac 剪映 11.2 實測通過）、windows_draft.py（按上游支援路徑實現，未真機驗證）、smoke_test.py（新環境先跑的最小冒煙測試）。流程、時間線提取與建軌 方法見references/jianying-export.md；需 venv +pip install pyJianYingDraft。gallery/靜態畫廊：優先直接給使用者線上版 https://vincentwei1021.github.io/video-shotcraft/library.html ； 本地跑則先gallery/fetch-media.sh拉樣片（mp4 不在 git 裡），再cd gallery && python3 -m http.server 4178。152 卡 209 條動態樣片 可瀏覽/搜尋/多選複製卡名——適合讓使用者看著樣片挑鏡頭。