syklayou-glitch/video-shotcraft

video-shotcraft：電影感產品影片製作

一個自包含的製作能力庫：152 張鏡頭配方卡（附 demo 實作原始碼與動態樣片 畫廊）、一支已验收的完整宣傳片模板、可複用元件與音訊資產、六階段工作流。 當前 focus 是 web/桌面產品宣傳片，但鏡頭卡本身是通用動效詞彙—— 也可以單獨抽卡做任意影片裡的單個鏡頭。

呼叫時先判斷模式

完整宣傳片有三種互不合併的模式。在開始素材採集、分鏡或實作前，先判斷使用者 是否已經明確選擇；已經選擇時直接執行，不重複詢問，也不要改成另一種模式。

1. 直接使用模板：保持 Ink Press 原有替换流程。讀 template/TEMPLATE.md， 按既有鏡頭結構替换目標產品的截圖、文案和品牌資訊。
2. 自主自由創作：讀 references/pipeline.md。Agent 根據使用者已有要求和專案 內容，自主決定視覺方向、鏡頭映射、分鏡、素材和音訊，連續推進到成片；不在 產品簡報、styleframe、鏡頭映射或分鏡階段暫停等待使用者確認。
3. 共同創作：讀 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 原始碼。單鏡頭可在目標素材明確後執行；完整宣傳片若尚未說明採用 自主自由創作還是共同創作，只詢問這兩種模式，指定鏡頭作為後續製作約束，不自動 等同於共同創作。

四種用法

1. 完整宣傳片（模板路線）：想要和模板片高度相似的效果 → 讀 template/TEMPLATE.md，按「换產品復現指南」替换素材逐鏡頭適配。
2. 完整宣傳片（自主自由創作）：要新風格並授權 Agent 自主決定 → 讀 references/pipeline.md，從產品理解連續推進到終檢，中途不逐階段等待確認。
3. 完整宣傳片（共同創作）：要參與關鍵决策 → 讀 references/guided-free-creation.md，確認產品簡報、需求决策、視覺方向、 鏡頭映射和最終分鏡；放行後從流水線的最終素材採集繼續。
4. 單鏡頭/單動效：從 references/shots/ 選卡（或讓使用者在 gallery/ 畫廊裡挑），讀卡全文並按「參考實作」定位準確 demo 原始碼， 適配到目標素材。

自主自由創作與共同創作的邊界

自主自由創作把創意和工程决策交給 Agent。Agent 從專案內容動態推導產品重點、 視覺方向、鏡頭映射、分鏡、素材處理與音訊方案，記錄關鍵判斷後直接執行；除非缺少 無法安全推斷的必要輸入，否則不提問、不逐階段暫停，也不要求使用者確認中間產物。 使用者已有的明確要求始終是約束，不能被 Agent 的預設選擇覆蓋。

共同創作才使用逐階段確認。預設讀 references/guided-free-creation.md，每輪只問 1–3 個最能减少返工的問題，並在產品簡報、需求决策、視覺方向、鏡頭映射和最終分鏡 處暫停等待使用者確認。使用者確認業務與創意方向；Agent 自主完成採集方式、實作參數、 SFX 釘幀、Remotion 工程、渲染和技術 QA。

共同創作中，使用者明確說「你全權决定」或「跳過確認直接做」時，切換為自主自由創作 並記錄這一選擇；不要一邊聲稱自主推進，一邊繼續要求逐階段確認。

功能到鏡頭的映射只是「選用哪些運動語法」，不是完整分鏡。共同創作確認映射後， Agent 必須繼續給出鏡頭順序、時長、具體畫面、頁面狀態、素材來源、字幕、轉場和 SFX；只有完整分鏡確認後才進入最終素材採集。使用者從 Gallery 複製鏡頭名時，只需 提供卡名或「卡名 · 樣式名」，Agent 負責讀取本地配方卡和 demo 原始碼。

核心理念

1. 復刻既有頁面必須用真實截圖；手搓 UI 限非復刻場景，且品質與表達 明確性是硬門檻。 表現產品真實頁面時第一步就起本地 dev server， 用無頭瀏覽器截全頁 2x 紋理 + 元素級摳圖 + layout.json 座標表。 非復刻場景（抽象開場/品牌段/獨立展示元件）允許手搓 UI，但達不到 出版級質感或觀眾看不懂它表達什麼，就回截圖路線。頁面資料按風險處理： 公開演示資料只有在產品簡報明確確認後才可保留；客戶、個人、內部、密鑰、 即時或其他敏感資料必須用虛構或脫敏內容，且在採集前凍結。

2. 整支影片的視覺語言必須從產品自身生長，不能另造一套不相干的 「宣傳片皮膚」。 做 styleframe 前，先從產品/網站的設計系統、原始碼或 computed styles 中提取並寫入設計 spec：字體家族與字重、字號層級、 行高/字距，網格、間距、對齊、資訊密度與圓角，以及背景/表面/正文/ 強調/狀態色、漸層和材質。片中所有標題、字幕、數字、字卡、版式、 轉場、粒子、光效和其他動效配色都必須複用或克制擴展這套 tokens， 同時匹配產品的調性、品味和質感。走模板或鏡頭卡路線時，只繼承其 鏡頭結構、運動語法、節奏和已調參數；字體、排版、配色與材質必須按 目標產品重新蒙皮。若因敘事需要偏離產品視覺，共同創作先說明理由並讓使用者 確認；自主自由創作把理由與取捨寫入設計 spec 後繼續。

3. 電影感來自運鏡、光影、節奏與聲音的配合，不來自炫技動畫。 反覆被認可的是：單主角完整動作弧（聚光→推近→懸浮→歸位）、 物理隱喻驅動的加速度（發牌）、側斜機位 orbit 環繞特寫、 riser→impact→sparkle 的聲音句式。批量元素入場靠運動本身， 不靠逐個發光——裝飾性 glint/泛光群發即廉價，單點高品質光效可做。

4. 每個鏡頭只講一個動效；關鍵資訊落定後必須呼吸。 一種動畫手法（飛入/堆疊/翻頁）全片只當一次主角，重複鏡頭、重複 tagline 一律刪。節奏偏好是單向的：歷史回饋全部指向「放慢/停留」， 從未有過一次「太慢了」——品牌字標落定 hold ≥1s、批量動效收尾留 0.5s 靜止、開場主體動作給足 3s。排時間線時预先給 hold/rest 留幀預算。

5. 強節奏 BGM 的片子，所有轉場和動效必須卡在拍上。 使用者已選好音樂 → 開工前先做節奏分析（librosa 網格擬合求真實 BPM/相位 + kick/snare/hihat 三分類鼓點定位），網格按瞬態覆蓋率 驗收通過後才分鏡；時間線用拍號 beatF(n) 寫，稀疏重音釘真實 瞬態而非網格插值點，渲後從成片抽音軌回測切點誤差 ≤3f。 卡拍管的是時機不是幅度——作用於整畫面/相機層的節拍衝擊視同 大 slam，全片 ≤3 處（aesthetic-rules R4），其餘拍點動效只動元素層。 方法論見 references/music-beat-sync.md。 配了 BGM 的片子終渲固定交付兩版：帶 BGM 版 + 無 BGM 版（保留 SFX）， 靠 bgm inputProp 從同一時間線渲出，方便使用者後期自配音樂。

6. 用鏡頭卡動效必須先解析 Gallery 索引並讀準確的 demo 實作程式碼。 先用 gallery/api/library.json 校验卡名與 style-key，再按卡片文件的 「參考實作」定位具體 TSX。配方卡給的是語義和參數表，準確的 demo 原始碼 才是調校過的參數真相（緩動、時值 配比、摘罩時機、已知坑的規避寫法）。允許適配性改動，但卡上 「已知坑/命門」標註的參數不得降檔——品質標準只升不降。憑卡名和 理解新寫＝放棄全部調校積累。

7. 共同創作把廉價確認物前置，自主自由創作把同樣的判斷留作執行記錄。 產品簡報→需求到執行决策表→文字方向→styleframe→鏡頭映射→分鏡的順序不變； 共同創作逐級交給使用者確認，自主自由創作由 Agent 自主選定並連續推進。兩種模式 都不應在方向未定時進入逐鏡頭實作。

8. 驗收貫穿全程 + 交付前獨立審查。 階段 5 起每個鏡頭用 npx remotion still 出靜幀自檢、每輪修改後整片渲染 + ffmpeg 抽幀回看；交付前必須派一個乾淨上下文的 subagent 做獨立終檢。審查輸入 包含成片、關鍵幀、產品簡報、需求到執行决策表、當前模式確認或記錄的視覺方向/styleframe、功能到鏡頭映射、 Gallery 卡名/變體、準確 demo TSX、Gallery 參考樣片/抽幀、最終分鏡、選中的鏡頭卡和 審美準則；按 references/final-review.md 同時檢查方案一致性、功能完整性、鏡頭還原度、視覺/音訊技術品質和資料安全， 逐條出帶幀號證據的報告。製作者對自己的產出有確認偏差，首檢永遠不能交給使用者。

9. 確定性渲染：禁 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 頁面相機——一切「真實頁面」鏡頭的地基）、ClipCard（把外部 影片素材 mp4 包成可被鏡頭卡運鏡骨架驅動的「卡片主角」，含 OffthreadVideo 交叉淡化循環——素材短於鏡頭時無縫續播）、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（部分 import demos/_fixtures/Fixtures.tsx 的假 UI 場景件，個別 import demos/_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 條動態樣片 可瀏覽/搜尋/多選複製卡名——適合讓使用者看著樣片挑鏡頭。