Carvercat 動態圖形
找不到東西嗎？references/INDEX.md 會回答「X 在哪裡」的問題，涵蓋整個技能（工藝、應用、特效、繪圖、地圖、工作流程、已知問題）。
可與任何能呼叫 Carvercat MCP 工具的代理搭配使用：Claude、GPT/Codex、Gemini，或是跟著操作的人。這裡沒有任何東西依賴於特定廠商。工具名稱可能帶有客戶端前綴（例如 mcp__carvercat__carvercat_run）。
0. 單位與新的表面（請先閱讀此節）
您所寫的一切單位都是設計單位：以框架左上角為原點的 px，y 軸向下，順時針度數，CSS 顏色與緩動函數，fontSize px，時間以幀為單位、"1.5s" 或 "500ms" 表示。在一個經過驗證的單一呼叫（scene.apply，先進行乾執行）中建構整個場景，使用類似 CSS 的選擇器選取物件，使用輔助工具（layout.*、text.fit、motion.apply、measure.*），並在任何傳送前執行 carve.preflight {host}。指南請參閱：references/app/design-units.md。舊的名稱仍會相容一個版本，並會在那裡列出一次；請不要使用它們。
0b. 開始操作任何東西之前
- 找到這台機器上已安裝的 Carvercat 應用程式，並將此技能所在資料夾視為已安裝的資料夾；對於創意工作來說，這個技能就足夠了。請勿使用固定的歷史路徑。
carvercat_session（附加）然後carvercat_state：在您進行任何修改之前，先確認建置版本、開啟的專案與合成。carvercat_list可取得 ID。- 請對方在您建構期間不要點擊應用程式：他們切換合成會導致您後續的指令被重新導向。
- 絕不要清除使用者的文件來重新建構。將可編輯的
.carverproj檔案儲存在工作目的地。
1. 像動態設計師一樣規劃（工藝）
只閱讀工作所需的內容：
| 需求 | 閱讀內容 |
|---|---|
| 持續時間、緩動函數、12 個原則、編舞、配合音樂的節奏、反模式 | references/craft/motion-principles.md；每個原則有一頁在 references/craft/principles/ |
| 字級大小、閱讀時間、入場樣式、強調效果；測量字距、行距與 lint 閾值 | references/craft/typography.md |
| 哪種轉場、持續多久、在剪輯點的交接 | references/craft/transitions.md |
| 音效與音樂：每個事件一個音軌、音量、pop/whoosh 規格 | references/craft/sound-design.md |
| 9:16 / 社群媒體安全區域、轉換 16:9 作品 | references/craft/vertical-and-safe-areas.md |
| 色板角色、對比、漸層、色彩數值 | references/craft/colour.md |
| 品牌的動態系統：緩動家族、持續時間、招牌動作、品牌包 | references/craft/brand-systems.md |
| 焦點、閱讀順序、網格、層級、安全區域 | references/craft/composition-and-layout.md |
| 閱讀簡報：事實、幀數預算、風格、配方 | references/craft/reading-a-brief.md |
| 為簡報選擇哪個風格包 | references/craft/style-families.md |
| 每種風格的測量幀數；該風格的審查清單 | references/craft/timing-by-style.md，references/craft/review-by-style.md |
| 某個動作為何有效：12 個原則與進階知識、設計基礎、技巧、類型、時機、工作流程、可及性、歷史（每頁結尾都會說明如何在 Carvercat 中實作） | ../wiki/README.md，機器索引 ../wiki/index.json |
普遍適用的規則：
- 每個場景只有一個主角。
- 輔助元素以 expo-out 或減速方式進入。
- 以加速方式退場，時間約為入場時間的 70%。
- 相鄰元素錯開 3–6 幀。
- 每個場景都有入場、中間的動態以及退場（絕不能凍結不動）。
- 文字至少停留 max(25 幀，每字 10 幀) + 10 幀。Carvercat 的 lint 要求每秒 17 個字元（不計空格），至少 25 個完全不透明幀。
2. 先從模式庫建構
patterns/README.md 包含 25 個預設與 5 個範本，均已於 0.0.72 版驗證，附有測量過的 overshoot 與 settle 幀數，以及推拉、縮放穿越、卡片堆疊與高光掃描的配方。該包位於 ../library/templates/motion-patterns/。使用 library.list {query:"expo"} 檢查是否已安裝；若未安裝，則將其安裝到使用者的 Library 資料夾（Help > Library Folder 或 library.folder，複製到 templates/，然後 library.reload；需要 Carvercat 0.1.8+；請參閱 patterns/README.md）。在 0.1.8 版之前，已安裝的應用程式無法載入它。放置的範本會變成巢狀合成 — 請參閱 patterns README。
- 單一物件：
preset.apply {name, id}，例如Rise - expo、Pop - spring、Stamp、Exit up - accelerate。 - 文字：
Words rise - expo、Letters cascade - spring、Lines reveal - decelerate等。 - 多個物件：
library.place {name, frame}然後template.apply {id}。例如Two-tone wipe、Colour iris、Lower third - accent bar、Logo - stamp reveal、Bar chart - grow。 - 在一個合成中完成的完整多節拍作品：patterns/promo-assembly.md。
- 風格包（安裝方式與 Motion Patterns 相同）：SaaS UI、Kinetic Typography、Data Viz、Corporate Brand、Minimal Luxury、Social Short-form 9:16、Cartoon Bounce、Funky、Futuristic HUD、Retro、Glitch、Sports、Explainer；使用 references/craft/style-families.md 來挑選。它們需要安裝 Rethink Sans 字體（文字無法使用應用程式內建字型，KI-136）。每個風格在
../categories/下都有一個實驗室 (lab) 和一個展示 (showcase) 專案。 - 常見簡報的食譜（SaaS 發表、體育比分更新、9:16 提示短片、年報開場、季度財報、奢華預告、解說課程、動態報價短片、兒童解說、促銷廣告、科技預告、復古之夜、音樂預告）：包含幀數分鏡表與僅使用 Library 範本建立的驗證範例專案，位於 recipes/README.md。
- 精確曲線：在離幀關鍵點上使用
ease: "cubic-bezier(a, b, c, d)"（patterns/custom-curves.md）。 - 彈簧與彈跳：
scripts/motion/curves.py會將其烘焙成關鍵幀。
3. 驅動應用程式
常規規則（2026 年 10 月 23 日）： 直接編輯 .carverproj JSON 檔案來建構和修改場景，然後執行 edit.open {force:true}。整個場景也可以透過 MCP 以一個經過驗證的原子性 scene.apply 呼叫發送；專案檔案現在是 carvercat/2（px，y 向下，幀；每次儲存都會寫入，v1 檔案仍可開啟），而下面的 JSON 路徑描述了 json_author/cc.py 所寫且應用程式仍可載入的較舊 v1 格式（分數，y 向上）；若要為新的生成器編寫，請使用 carvercat/2（cc_project.py，如同食譜建構器所做的那樣）。對於檔案無法處理的步驟（測量文字、檢視、儲存、Resolve 傳輸、即時調整），請使用 MCP。程序與備用方案：references/app/json-authoring.md。
references/app/design-units.md 是工作指南：單位、scene.apply、選擇器、anim.set（補間、緩動、錯開）、以 CSS 用語表示的特效、輔助工具、無頭模式說明。references/app/mcp-essentials.md 涵蓋了建構 -> 檢視 -> 檢查的循環、值得知道的指令以及耗費數小時的陷阱（clip.move 會覆蓋、ID 會在每個合成中重新開始）。機器可讀的目錄是 carvercat://schema/design、carvercat://schema/commands 和 carvercat://schema/scene（應用程式儲存庫的 schema/agent/json-schema/）：在使用不熟悉的鍵之前先閱讀其條目；絕不要猜測參數或生成的條目 ID。
對於腳本化工作，請使用受維護的 Python 腳本：ai/scripts/cc_client.py + cc_scene.py（references/app/creative-toolkit.md）；應用程式也有自己的 Python 輔助工具（carvercat_py）。特效、填色/描邊、漸層、顏色、變形、錯開與路徑修剪，請參閱 references/app/creative-controls.md。可以透過 scene.apply {dry_run: true} 和 measure.* 檢查待處理的計畫；除了文件本身之外，不會儲存任何東西。測量實際成形後文字。有意識地選擇字型，包括在混合 RTL 文字中為獨立的 LTR 數字序列選擇字型。指南中的每個範例都由 ai/scripts/verify_examples.py 針對無頭模式的 Carvercat 執行過。
3b. 特效、繪圖、地圖與完整工作
| 需求 | 閱讀內容 |
|---|---|
| 模糊、發光（含燃燒限制）、陰影、動態模糊、漸層、描邊/修剪繪製、柔邊與遮罩羽化、文字外框、錯開、遮罩 | references/effects/README.md |
| 隱藏的底層參數、提升它們、參數之間的連結 | references/effects/basement-promote-ropes.md |
| 所有形狀（矩形、橢圓、星形、多邊形、路徑）、排列與分組 | references/drawing/shapes.md |
用零件組成的角色/物件：作為關節的錨點、父級關聯、作為樞軸或控制柄的空物件（object.new {kind: "null"}） | references/drawing/rigging.md |
| 地圖：邊界、道路、圖釘、路線、環、地標彈出視窗、箭頭、縮放 | references/maps/maps.md |
| 字幕 + 旁白、RTL/阿拉伯文、Resolve 交接、匯出、工作循環 | references/workflows/ |
| 某個行為異常 | references/known-issues.md |
普遍適用的特效規則：glow 強度 ≤ 0.8（0.9 會裁切，1.0 會燒成白色），半徑決定光暈範圍；模糊與陰影僅用於主角的深度；線條使用修剪繪製；UI 形狀的 softEdge 為 2 到 6 px，環境光的 softEdge 為 160 到 320 px（references/effects/soft-edge.md，包含羽化遮罩揭示）。
4. 在說「完成」之前先檢查
- 檢視 入場、停留與退場（
carvercat_look）。測量 使用carvercat_inspect（timing、curves用於 overshoot 與 settle、lint、expect、qc用於閃爍）以及無需渲染的輔助工具（measure.boxes、measure.overlaps {within: "safe"}、measure.contrast）。在傳送前使用carve.preflight {host}進行預檢。 - 走一遍 references/craft/review-checklist.md：故事、時機、文字、UI、轉場、外觀、聲音、衛生。
- 先建構一個代表性的合成，審查它，然後再擴展。食譜是起點：根據簡報和素材調整層級結構、圖像和時機。安全範圍不能取代視覺判斷。
- 延遲或音訊不足：references/app/performance.md。
5. 應用程式外部的工具（scripts/motion/，Python 3，標準函式庫 + ffmpeg）
vo_align.py：旁白轉換為單字與行幀。sfx_kit.py/sfx_render.py：合成音效（pop、whoosh-hit、tick、衝擊...）-> 每個提示一個 WAV 檔案。music_bed.py：符合剪輯的音樂背景；mix_check.py：音軌 LUFS 與參考混音。reformat.py：將 16:9 專案轉換為 9:16 合成。carverproj.py：專案 JSON 輔助工具（ID、鍵）。build_pattern_pack.py/comp_to_template.py：重新產生模式包。effects_param_tables.py：重新產生特效參數表。../maps/geo_paths.py/../maps/map_overlay.py：真實地理資料轉換為路徑；解說覆蓋層（圖釘、環、路線、卡片、箭頭）。
6. 安全性與交付
使用場景 ID（以及 Scene.component 命名空間），以便修訂時更新相同的物件：再次套用相同的文件時，只有差異部分會變更。在被拒絕之後，停止依賴於該拒絕的工作。在未知的結果之後，在進行任何進一步的變更之前，先檢查身份與狀態；絕不要重複執行你不知其結果的寫入或匯出操作。Resolve 操作需要使用者目前的授權；若無授權，僅在本機創作與測試。在獲得授權後，驗證實際的專案、時間軸與格式，保留原始編輯，並檢查合成樣本。Carvercat 工作的單位是合成；Resolve 時間軸是分開的。有關傳輸檢查、合併、重新定位與重新連結，請閱讀 references/app/media-recovery.md；在清理參考覆蓋範圍不完整的地方，保留檔案。
工藝參考背後的想法來源與許可證：SOURCES.md。