Pixerate 動畫編輯器
一個場景包含藝術品（一個被解析為向量路徑和群組的 SVG，每個元素都有 ID）加上一個有序的鏡頭列表。一個鏡頭可以選擇性地移動攝影機，播放其 run 中的指令，然後保持靜止（預設 600 毫秒）。指令會一個接一個地播放，除非指定了 "with": "previous"；每個指令都有基於內容的預設長度（進入 600 毫秒，退出 450，移動 700，繪製跟隨路徑長度），除非您想改變節奏，否則請省略 duration。每一幀都是時間的純函數。
ID：元素 ID 來自 get_animation（elements）或 find_animation_elements；鏡頭 ID 由您選擇（例如 "intro"）；指令透過鏡頭 ID 及其在指令序列中的索引來定址。時間單位為毫秒，位置則為藝術品的文件單位。任何較晚進入的元素在進入前都是隱藏的；任何從未進入的元素從一開始就可見。
關於錯誤、命名空間的工具名稱和通用指令工具，請參閱 pixerate-agent-tools。完整的指令詞彙（每種類型、選項和預設值）位於 references/commands.md。
工作流程技能
對於這些任務，請同時載入工作流程技能：它包含了方法、步驟間的檢查以及常見陷阱，並使用了下列工具。
pixerate-animation-motion-graphics：鏡頭、錯開的入場、緩動、保持、符合長度。pixerate-animation-logo-reveal：一個簡短的揭曉，使用標誌的各個部分，配合節拍，最終保持靜止。
工作方法
- 讀取。 使用
get_animation取得元素、帶有時間設定的鏡頭、片段、驅動器和問題。如果沒有藝術品，請先使用set_animation_artwork_svg（為您將要動畫化的每個元素指定一個 ID），或從import_flair_effect/import_pptx_animation開始。對於輪廓文字，get_text_layout會顯示字母、單詞和行單位。 - 規劃鏡頭，每個鏡頭一個想法。 寫下每個鏡頭中觀眾應注意的內容及其順序，然後將每個拍子對應到一個指令。隱藏的結束狀態（變形/比對目標、跟隨路徑）必須先存在於藝術品中，然後才能引用它們。
- 批次寫入。 使用
insert_shots寫入整個鏡頭；使用edit_animation將多個相關編輯作為一個復原步驟（不確定時先用dry_run: true；"$0.indexes[0]"和"$last.shot"引用先前的操作）。使用add_commands、update_command、move_command、delete_commands進行細部調整。僅在需要替換所有鏡頭時才使用write_animation。對於您尚未寫過的指令類型，請先使用describe_animation_command取得其確切欄位。 對於應感覺像是表演而非關鍵影格設定的運動（手繪弧線、抖動拖曳、移動過程中改變顏色），可以使用record_animation_take配合計時樣本，將其錄製為一個鏡頭，如同一個人在舞台上現場錄製一樣。 - 調整時間與提示。 使用
fit_animation來符合特定長度（保留節奏重要的鏡頭）。對於音樂或旁白，使用set_animation_settings設定beat或narration，使用get_timing_grid讀取提示，並為鏡頭設定"at": { "beat": n }或{ "word": i }。 - 檢查。 使用
check_animation；修復每個錯誤和警告（代碼如too-fast、overlap、out-of-frame、enter-visible、cue-missed）。使用get_motion_path以數字形式取得間距和弧線。 - 預覽。 使用
render_animation_frame搭配shot+at: "end"，或使用times製作聯絡表，並可啟用onion_skin/motion_paths在一張圖片中看到運動。在批次處理後而非每次編輯後才進行渲染。seek_animation可以向使用者顯示某個時間點。 - 導出（當被要求時）：使用
export_flair_motion、export_flair_effect（需先呼叫set_animation_controls）或export_lottie；閱讀返回的關於取樣或遺失內容的備註。
最佳實務
- 每個鏡頭一個想法，每次一個焦點運動。 分階段安排動作，讓視線知道該看哪裡；次要元素的移動應較少、較晚或完全不移動。使用攝影機（用
frame框住一個節點）來引導注意力，而不是移動所有東西。 - 為每個變化添加緩動。 到達時使用緩出（減速到位；
enter的預設值），退出時使用緩入（exit搭配ease: "ease-in"），移動時使用緩入-緩出（預設值）。僅在機械運動（恆定旋轉、進度條）或循環中使用linear。 - 根據大小和距離調整時間。 小型 UI 變化 150-300 毫秒，元素入場 300-600 毫秒，大型移動和攝影機移動 600-1200 毫秒。不要低於 120 毫秒（
too-fast）。大物體移動得比小物體慢。 - 預備動作和跟進動作。 使用
ease-in-back來為快速退出前的蓄力；使用pop、rise、ease-out-back或彈簧預設值（spring-gentle、spring-quick）來實現到達時的過衝和穩定。謹慎使用spring-bouncy；它會給人俏皮、活潑的感覺。 - 重疊動作。 將相關項目錯開 40-120 毫秒（使用
stagger，或對文字使用帶cascade的split），而不是讓它們同步移動；使用"with": "previous"加上一個小的delay來啟動次要運動，使其跟隨主要運動。 - 弧線。 自然運動曲線：使用帶
via路徑點的move（一條平滑路徑），而不是使用會在各點停止的鏈式移動，或使用follow跟隨路徑節點。 - 錄製片段。 以每秒 30-60 次的頻率取樣表演；錄製器只保留重要的點（提高
tolerance以獲得較少、較乾淨的指令）。每個移動元素開始時，應在其當前姿勢處取樣（使用get_motion_path的最後一個點，或靜止時其邊界中心），否則它會跳到第一個取樣點。一個片段是位於其他鏡頭之後（或在at處）的一個新鏡頭；它不能疊加在現有鏡頭之上。像對待任何鏡頭一樣對其進行細化：它由普通的move（含via和times）、scale、rotate、fade和style指令組成。 - 保持足夠長的時間以便閱讀。 將每個結果保留在螢幕上（鏡頭
hold，預設 600 毫秒）；對於需要閱讀的文字，每個單詞大約 250 毫秒，對於最終幀或標誌則更長。 - 剋制地誇張。 強調效果（
pulse、shake、teeter、color-pulse）僅用於需要引起注意的單一事物，且僅使用一次；它會自行恢復到靜止狀態。 - 動態模糊僅用於真正快速的運動（
motionBlur: { shutter: 180 }）；它會影響舞台和渲染的影格，但不影響 Flair 或 Lottie 導出。 - 無障礙性。 避免閃爍：每秒閃爍次數不得超過三次（WCAG 2.3.1），因此
color-pulse和大型區域的淡入淡出應緩慢且少量。避免為必要的 UI 運動使用大規模視差、縮放和旋轉；提供一個減少動畫的替代方案（主機應在prefers-reduced-motion下切換為淡入淡出或結束狀態；此編輯器不會自動生成一個）。運行時間超過 5 秒的循環需要一種暫停方式（WCAG 2.2.2）。 - 互動元件。 對於按鈕或切換開關，設定
trigger（click、hover、press、scroll）；對於點擊切換，使最後一個鏡頭恢復到起始狀態。
工具參考
讀取工具
| 工具 | 用途 |
|---|---|
get_animation | 從這裡開始。返回名稱、藝術品大小、長度（毫秒）、循環、元素（id、類型、名稱、父元素、邊界、實色填色、含數值參數的即時效果）、每個鏡頭及其每個指令的索引、開始、結束和 flairPrimitive、片段、驅動器、控制項和問題摘要，以及當編輯被拒絕時的 readOnly。includeElements: false（預設為 true）可在藝術品較大時跳過元素列表。 |
get_shot | 讀取一個儲存的鏡頭（shot id），包含其開始/結束和每個指令的開始/結束（毫秒）；在細化單個鏡頭時比 get_animation 更節省資源。 |
describe_animation_command | 在使用尚未用過的指令類型之前，或當寫入操作拒絕某個欄位時使用：返回每個 types（例如 ["enter", "move"]）的完整 JSON Schema，包含每個欄位的類型、範圍、預設值、含義以及哪些是必需的。寫入工具會以簡短形式列出每個指令欄位一次，並帶有接受該欄位的類型前綴。 |
find_animation_elements | 當藝術品很大時，尋找其 id 或名稱包含 query 的元素（不區分大小寫；limit 預設 20，最多 200）。返回 id、類型、名稱、父元素、邊界、填色、效果。 |
get_text_layout | 在使用 split 製作輪廓文字的動畫之前使用：返回 group 的線條、單詞和字母 id（按閱讀順序）。如果元素不是路徑組，則會出錯（將文字轉換為輪廓，每個字母一個路徑，並將其分組）。 |
get_motion_path | 以數字形式檢查間距、弧線和著陸點：從 from 到 to 毫秒，每隔 step 毫秒（預設 33，最多 400 個樣本）對一個 node 的中心（文件單位）進行取樣，並顯示每個移動變化的開始和結束位置。 |
get_timing_grid | 列出 from 和 to 之間的拍子（編號、毫秒、小節、小節內的拍子）和旁白單詞（索引、文字、開始、結束）（limit 預設 200），以及每個時間點播放哪個鏡頭，以便選擇 at 提示。當未設定節拍網格或旁白時，返回空值並附帶提示。 |
check_animation | 在每次批次寫入後使用。列出帶有代碼、嚴重性、鏡頭、指令索引、節點 ID、測量值與所需值以及如何修復的問題。修復錯誤和警告；備註僅供參考。 |
render_animation_frame | 查看結果：time（毫秒）或 shot + at（start、middle、end；預設為 end）。times（2-16 個時間點）可製作帶有標籤的聯絡表（columns 1-8）。onion_skin 添加鬼影幀（before 預設 2，after 0，spacing 毫秒或 "commands"）；motion_paths（true 或 id 列表）繪製運動路徑。預設為 SVG；format: "png" 僅在主機可以光柵化時使用。 |
export_flair_motion | 將場景作為一個 Flair SvgMotion { svg, animate } 導出，包含保持、取樣步驟計數和備註。參數：fps（預設場景 fps，否則 30）、curves 和 behaviors（預設 true）、flair 目標版本（預設 0.39；舊版本會將彈簧、步驟、行為和曲線取樣）。 |
export_flair_effect | 導出為 Flair 目錄向量效果（id 使用 kebab-case，name，description，category 預設 icon，tags，加上上述的 curves / behaviors / flair）。先呼叫 set_animation_controls，以便顏色變成 {{name: color}} 控制項。 |
export_lottie | 導出為 Lottie（Bodymovin v5）JSON，適用於 lottie-web 和行動裝置播放器，每個鏡頭帶有一個標記，參數：fps（預設場景 fps，否則 30），取樣的關鍵影格計數，以及關於未保留內容的備註（漸層、虛線、揭示遮罩、改變點數的變形）。 |
寫入工具
| 工具 | 用途 |
|---|---|
seek_animation | 向使用者顯示某個時間點：time（毫秒）或一個 shot 的開始，帶有 play true 或 false。不會改變場景。 |
set_animation_artwork_svg | 用一個獨立的 svg（帶有 viewBox）取代藝術品，作為一個復原步驟。為您將要動畫化的每個元素設定一個 id；如果現有鏡頭引用了新藝術品缺少的 id，則會被拒絕。返回元素。 |
import_pptx_animation | 用 PowerPoint 投影片的形狀和動畫窗格取代整個場景（data base64 .pptx，slide 預設 1）：每次點擊一個鏡頭，保留延遲、重複和加速度；圖片和圖表會被省略並附帶說明。不確定時先用 dry_run: true。 |
set_animation_drivers | 取代所有驅動器（空列表即清除）：目標的 x、y、rotation、scaleX、scaleY 或 opacity 跟隨源節點的屬性變化，乘以 factor + offset，可選地進行 clamp。用於視差、滾動時轉動的輪子、隨著某物上升而逐漸淡出的陰影。 |
set_animation_clip | 定義、取代或（使用 clip: null）刪除一個可重複使用的命名片段，其 run 針對 "$"；使用 play 指令在任何節點上播放它。優先使用片段而不是重複相同的指令。 |
copy_animation | 將所有動畫化 from 的指令賦予 to 中的節點（所有鏡頭或 shots），每個副本從其原始版本開始，可選地進行 stagger（毫秒）。適用於快速一次性複製；對於將重複使用的運動，請使用片段。 |
record_animation_take | 將表演的動作錄製為一個新鏡頭（一個復原步驟）：samples（{ node, t（進入片段的毫秒數）, x, y（中心）, scaleX, scaleY, rotation, opacity, fill, stroke, strokeWidth }）會變成一個透過記錄的 times 處路徑點移動的 move 指令，以及一些在發生時開始的帶緩動的 scale / rotate / fade / style 指令。可選參數：length、id、label、at、tolerance；dry_run: true 會先返回指令序列。返回鏡頭 id、其開始時間以及每個指令的索引、類型、開始和結束時間；之後再使用 check_animation 和 render_animation_frame。 |
fit_animation | 透過設定鏡頭的 speed 使場景持續 seconds 秒，並保持比例；keep 中的鏡頭將按原樣播放。dry_run: true 會先報告新的長度和速度。 |
import_flair_effect | 用一個 Flair 向量 effect 或 SvgMotion motion 取代整個場景（只給出一個；可選 name）。佔位符會變成顏色控制項；每個 Flair 步驟變成一個鏡頭。不確定時先用 dry_run: true。 |
insert_shots | 在位置 at（預設為結尾）添加一個或多個完整的鏡頭（id, run, 可選 label, camera, hold, speed, at）。返回每個鏡頭的時間設定和問題。 |
update_shot | 透過 set 更改一個鏡頭的 label、camera、run、hold、speed、at 或 id，並透過 remove 清除 label、camera、hold、speed 或 at。 |
delete_shots | 按 id 刪除鏡頭（一個復原步驟）。 |
move_shot | 將一個鏡頭重新排序到索引 to（0 = 第一個）。 |
add_commands | 在鏡頭指令序列的索引 at 處（預設為結尾）添加指令。返回它們獲得的索引及其時間設定；使用這些索引進行後續更新。 |
update_command | 更改一個指令（透過 shot 和 command 索引）：set 中的欄位會取代，remove 中的名稱會清除（例如 "delay"）。返回該指令及其時間設定。 |
delete_commands | 從一個鏡頭中按索引刪除指令；後續指令會向前移動，因此之後需重新讀取索引。 |
move_command | 將一個指令移動到其序列中的索引 to；然後一個帶有 "with": "previous" 的指令會與其新鄰居同時開始。 |
set_animation_settings | 設定 name、description、loop（none, loop, ping-pong）、trigger（click, hover, press, scroll, 或 null）、導出 fps（預設 30）、場景 steps（12 = 二格拍攝；null 為平滑）、解析度 width 與 height、背景 background（顏色或 "transparent"）、beat 與 narration 時間設定、以及 controls（svg 或 json，或空列表以清除所有控制項）。必須先有藝術品。 |
set_animation_controls | 為兩個向量效果導出工具設定暴露的控制項：一個控制項物件列表，每個帶有 name（kebab-case）、type（color、number、select）、default（數字或色碼）、以及用於 select 類型的 options。針對 color 類型可選用 placeholder: "{{name}}"。這僅影響 export_flair_effect 和從 import_flair_effect 匯入的 Flair 效果的後續輸出。 |
指令參考
一個鏡頭的 run 是一個指令物件陣列，順序執行。每個指令必須有 type；其他欄位取決於類型。欄位名稱與 describe_animation_command 返回的名稱一致。
關鍵欄位
type（字串，必要）：指令類別，例如"enter"、"exit"、"move"、"draw"、"rotate"、"scale"、"fade"、"morph"、"style"、"smart-animate-match"、"follow"、"pulse"、"shake"等。nodes（id 字串或 id 字串陣列）：針對哪個或哪些元素。對於split，也支援type: "text"的子條件。duration（數字，毫秒，可選）：指令的持續時間。省略則使用基於類型與內容的預設值。delay（數字，毫秒，可選）：指令開始前的延遲。ease（字串或物件，可選）：緩動曲線。字串："ease"、"ease-in"、"ease-out"、"ease-in-out"、"linear"、"ease-in-back"、"ease-out-back"、"ease-in-out-back"、"pop"、"rise"、"spring-gentle"、"spring-quick"、"spring-bouncy"。物件：{ type: "cubic-bezier", values: [x1, y1, x2, y2] }或{ type: "spring", stiffness: 數字, damping: 數字, mass: 數字 }。with（字串，可選）：設定為"previous"以使此指令與上一個指令同時開始。at（字串或物件，可選）：鏡頭開始的提示。字串"start"用於鏡頭開頭；物件{ beat: 數字 }或{ word: 數字 }（配合set_animation_settings設定的拍子或旁白）。
常見指令類型（主要類型）
enter：元素從隱藏變為可見，使用指定的緩動（預設緩出）。exit：元素從可見變為隱藏，使用指定的緩動（預設緩入）。move：將元素從其目前位置移動到to: { x, y }，可選透過via路徑點（陣列{ x, y }或節點 ID）。也支援split用於文字。draw：模擬繪製路徑（僅適用於path類型的節點）。使用startOffset和endOffset（0-1）。rotate：旋轉degrees，圍繞著anchor（{ x, y }或節點 ID）或origin（"center"、"top-left" 等）。scale：縮放scaleX、scaleY（預設 1），圍繞anchor或origin。fade：改變opacity（0-1）。如果需要同時更改權重、顏色、字重等，使用style搭配opacity。morph：將形狀變形為另一個形狀（透過節點 IDto）。需要起點和終點具有相同數量的點。style：更改元素的視覺屬性（fill、stroke、strokeWidth、opacity等）。smart-animate-match：根據名稱或 ID 比對元素，並在其間製作動畫。follow：使元素沿著path節點定義的曲線移動。pulse：一個簡短的縮放/淡出效果，用於吸引注意力。shake：一個簡短的抖動效果，用於強調。play：從clip（片段名稱）播放一個可重複使用的動畫序列。
鏡頭層級屬性（在 insert_shots 中）
id（字串，必要）：鏡頭的唯一識別碼。run（陣列，必要）：此鏡頭中的指令陣列。camera（物件，可選）：{ frame: "節點ID", zoom: 數字, pan: { x, y } }用於攝影機移動。hold（數字，毫秒，可選）：在所有指令完成後保持在此幀的時間。預設 600 毫秒。speed（數字，可選）：鏡頭的播放速度倍數。at：此鏡頭開始的提示（{ beat: n }、{ word: i }或字串"start"）。label（字串，可選）：用於組織目的的人類可讀標籤。