Communitygithub.com

作者動畫 (author-anim)

建立一個「動畫模組」(anim),也就是單一 YAML 檔案,可根據簡短的需求描述,在瀏覽器中(使用 canvas2d、SVG、DOM 或 three.js)將歌曲的歌詞與節拍製作成動畫。當被要求製作、移植、重新設計樣式或修正動畫/歌詞視覺化/歌詞動畫模組時使用。僅需此技能即可運作,不需要範例庫或目錄。

作者動畫 (author-anim) 是什麼?

這個 AI 技能(「作者動畫」)定義了一個高度結構化的架構,用來建立所謂的「動畫模組 (anim)」:一個獨立的 YAML 檔案,封裝了在瀏覽器中播放歌詞動畫所需的 JavaScript、CSS 和 HTML。它強制執行一套嚴格的設計規則,以確保動畫在快轉、暫停、調整大小和切換主題時都能正確運作。純粹的動畫邏輯(透過 `frameAt` 等函數將時間映射到狀態)與瀏覽器特定的程式碼(處理 `G` API)嚴格分離,並將可測試性與可維護性放在首位。此技能支援 Canvas 2D、SVG、DOM 操作和 Three.js 四種後端,並提供一個全面的指南、陷阱和規格文件路由表,以協助開發者。工作流程包含一個使用 npm 腳本的強大驗證與測試工具鏈,用於冒煙測試和視覺回歸測試,但 AI 模型在無法使用 shell 時,也可以在「無工具模式」下運作,只輸出最終的 YAML 檔案。可訪問性(清晰度、閃爍頻率)和主題支援(淺色/深色模式)是其核心要求。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/prjctg/animr-skill/tree/HEAD/skill

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

作者動畫 (Author an anim)

動畫模組 (anim) 是一個檔案 <kebab-name>@<major>.<minor>.yaml,包含四個鍵:t(字面值 c)、j(ES 模組)、s(CSS)、h(HTML/SVG)。宿主播放器會搭配一個全域 G API 來執行它,該 API 提供歌曲的音節、單詞、行、段落和節拍。你的工作是將一個簡短需求轉換為這樣的檔案,使其在搜尋/暫停/調整大小/切換主題時保持正確、清晰可讀且美觀。以下路徑相對於此 skill/ 目錄。

最重要的規則

  1. 影格是播放時間的純函數。 render(t) 必須在播放到達 t 或用戶拖曳到 t 時繪製相同的畫面。不能使用 Math.random、Date.now、累積積分或「上一影格發生了什麼」等會被搜尋跳過的狀態。所有內容都必須源自歌曲資料、種子和 t。
  2. 兩個部分。 在一個橫幅註解上方,是一個導出的、不依賴 DOM 的純粹部分(buildPlan、frameAt、輔助函數;可進行單元測試),然後是一個精簡的瀏覽器部分(export default function (G, shadowRoot, config)),僅負責連接和繪製。請參閱 guides/architecture.md。
  3. 在 default 中註冊,在 INIT 中讀取歌曲資料。 G.on / G.off / G.onFrame 只能在 default 內部使用。G.map / forEach / lookup / iterator / relayout 只能在 INIT 觸發後使用(在 INIT 處理常式中,或在後續的 render 等回呼中),絕不能在 default 本身中使用。訂閱 G.on(G.TYPE.TICK, render) 以處理播放;G.onFrame({ render, reset }) 涵蓋 SEEK/PLAY/PAUSE/RESIZE 和 UNINIT。
  4. 使用 G.dispose / G.listen 進行清理。 從 default 返回的函數將被忽略。釋放 WebGL(使用 forceContextLoss)、監聽器、計時器、攝影機。
  5. 顏色存在於 CSS 中,而非 c.v 中。 在 :host 上設定淺色值,在 [data-bs-theme=dark] { } 中設定深色覆寫;Canvas 使用 g-lib 的 cssColors 讀取它們。兩個主題都必須看起來經過設計。
  6. 不要手動實作 g-lib 已有的功能(clamp、lerp、緩動函數、基於種子的亂數產生器、Canvas 適配、彈簧、文字佈局、物件池等)。從精確標籤的固定版本導入;在編寫任何輔助函數之前,請先查看 pitfalls/dont-hand-roll.md 和 spec/g-lib.md。
  7. 可讀性優先於特效。 活躍的音節在淺色和深色主題下,在手機和筆記型電腦上,都必須清晰可讀,並支援長行、中日韓 (CJK) 字元、從右到左 (RTL) 的語言和緬甸文。大範圍閃爍的頻率必須保持在 3 Hz 以下(guides/accessibility.md)。
  8. 少量的型別化選項。 c 和 cSchema 是純文字字面值;每個選項都應有可見的效果。

工作流程(搭配 repo 工具)

  1. 需求簡述。 根據 guides/design-brief.md 撰寫設計需求簡述:一個強而有力的物理畫面;機制;哪些事件驅動什麼(同步圖);結構(主歌/副歌/節拍);可讀性方案;選項;陷阱。使用其選擇表選擇後端。拒絕那些無法保持可讀性的想法。
  2. 架構建立。 執行 npm run new -- <name> --backend canvas2d|svg|dom|three(或手動複製 templates/<backend>.yaml 並取代 __NAME__)。
  3. 閱讀一次: spec/module-format.md、pitfalls/general.md、你選擇的後端在 pitfalls/backends.md 中的章節、pitfalls/dont-hand-roll.md。僅透過下方的路由表打開其他文件。
  4. 實作:先實作純粹的部分(時間到狀態的轉換),然後是精簡的瀏覽器部分。
  5. 驗證。 執行 npm run validate -- anims/<file>.yaml。修正所有錯誤;在文件區塊中證明每個警告的合理性,或修正它。
  6. 檢查。 執行 npm run check -- anims/<file>.yaml 會以無頭模式掛載 13 首邊界案例歌曲,評分符合性表格,並將 PNG 寫入 out/<name>/ 目錄。打開這些 PNG(手機/筆電,淺色/深色主題)。一個綠色表格搭配一個難看或無法閱讀的影格就是失敗。如果「搜尋純粹性」行出現 WARN,表示畫面依賴於歷史狀態:請修正它,或在文件區塊中證明其合理性(例如刻意模擬)。
  7. 預覽(可選)。執行 npm run preview -- anims/<file>.yaml 來播放、拖曳進度條、切換主題和調整選項。
  8. 審查:根據 guides/quality-rubric.md(20 個問題)進行審查,然後交付一個 YAML 檔案和一份簡短報告(檔案名稱、最終檢查表、需求簡述中未決的決策、你刻意沒有實作的事項)。不要提交 out/ 目錄或測試工具。

無工具模式(聊天模型,無 shell)

跳過步驟 2、5-7。從匹配的範本文字開始,在你的推理中撰寫設計需求簡述,然後在回答之前,逐行將你的程式碼與 pitfalls/general.md、後端章節以及 20 個問題的評分量表進行比對。只輸出一個圍籬程式碼區塊中的 YAML 檔案,並提及哪些評分量表項目你因無法執行而無法驗證(搜尋純粹性、主題切換、調整大小)。

路由表:僅在觸發條件適用時打開文件

當你即將...閱讀文件...
決定要建構什麼;選擇一個後端guides/design-brief.md
佈局檔案;命名階段;撰寫文件區塊guides/architecture.md
使用任何 G.* 呼叫、事件選項或 ID 範圍spec/events.md, spec/event-shapes.md, spec/g.d.ts
新增選項、顏色、主題spec/config.md
使用時間工具、文字測量、Canvas 輔助函數、生命週期spec/utilities.md
將行分割為顯示行、文字換行spec/relayout.md, guides/patterns-text.md
根據音節/行/節拍觸發事件;預先生成;暫停;彈簧guides/patterns-timing.md
調整、高亮或設定文字樣式;非拉丁文字guides/patterns-text.md
編寫渲染程式碼(DOM, SVG, Canvas, Three, Simulation, Layers)guides/patterns-render.md, pitfalls/backends.md
攝影機、地形、群體、包裝、程序化 3Dguides/techniques.md, pitfalls/techniques.md
使用照片或攝影機spec/image-input.md
建立遊戲(autoPlay false, score, states)guides/games.md
使用任何 g-lib 輔助函數spec/g-lib.md
對閃爍、動態、對比度感到不確定guides/accessibility.md
完成guides/quality-rubric.md

最小範例(不要交付此範例;從範本開始)

"t": |-
  c
"j": |
  import { hash01 } from 'https://cdn.jsdelivr.net/gh/prjctg/[email protected]/index.js';
  /* [email protected]: <一行>
   * 1. <編號的設計主張:機制及其拒絕的誘人錯誤答案> */
  export function frameAt(plan, t) { /* 純粹 */ }
  /* 瀏覽器部分。此線以上的所有內容刻意不依賴 DOM。 */
  export default function (G, shadowRoot, config) {
    const cfg = G.cfg(config, { channel: G.cfg.int(0) });
    let ready = false;
    const render = (t) => { if (!ready) return; /* 繪製 frameAt(plan, t) */ };
    G.on(G.TYPE.INIT, () => { ready = true; /* 此處可使用 G.map(...) */ });
    G.on(G.TYPE.TICK, render);
    G.onFrame({ render, reset() { ready = false; } });
  }
  export const c = { v: { fadeMs: 150 }, m: [{ s: 'fadeMs', t: 'fadeMs' }] };
  export const cSchema = [{ i: 'fadeMs', n: '淡化 (毫秒)', t: 'int', mn: 0, mx: 2000 }];
"s": |
  :host { display: block; --ink: var(--inkColor, #111); }
  [data-bs-theme=dark] { --ink: var(--inkColor, #eee); }
"h": |
  <canvas id="c"></canvas>

j、s、h 包含原始文字(永遠不要用反引號或引號包裹)。t 使用 |-。檔案名稱包含版本號;切勿原地編輯已發佈的版本。

相關技能