專案定位與架構
XiaoyeCodes/code-animation-prompts 是面向 Claude Code 與 OpenAI Codex 的可安裝程式碼動畫技能與素材庫（查核 commit 2e6396abb45c2d183e91bc5a6583597411860217）。專案將嗶哩嗶哩創作者「俯仰觀照」整理的免費程式碼動畫素材包，結合社群補充的參考圖卡，封裝為標準 Agent Skill 目錄（skills/code-animation-prompts/），內含 341 份 Markdown 風格提示詞、196 張對位參考靜幀（原包 193 張加上 PR #1 補充之 K1 至 K3 共 3 張說明卡）與 145 份純文字參考。
系統在原始素材之上提供零第三方依賴的 Python 檢索腳本（scripts/styles.py）、安裝器（scripts/install_skill.py）、確定性時間介面範例（assets/starter/index.html）與 Playwright + FFmpeg 影片匯出器（scripts/render_video.py）。編碼代理只需查詢輕量索引 references/catalog.json 即可定位目標編號，不必將全部 341 份提示詞載入上下文視窗。
Stage 1 · 風格挑選與輕量索引檢索：catalog.json 與 styles.py
- 離線瀏覽器開啟 assets/library/ 下的風格挑選器 HTML 勾選並匯出編號清單
- 或由 Agent 執行 scripts/styles.py search / show / list 查詢 references/catalog.json
- 按需讀取單篇 Markdown 提示詞與對應 JPG 靜幀，不載入全部 341 份檔案
Stage 2 · 參數注入與確定性時間介面實作：window.renderAt
- 提取使用者主題、時長、畫幅（預設 1920x1080、30 fps、12 s）與字幕設定
- 以 HTML + Canvas / SVG / CSS / Three.js 實作視覺動態並固定亂數種子
- 暴露 window.renderAt 時間函數並在網址帶入 ?export=1 時停用即時計時迴圈
Stage 3 · 本地無頭逐幀擷取與 MP4 封裝：render_video.py
- scripts/render_video.py 啟動 127.0.0.1 隨機埠號靜態伺服器載入目標頁面
- Playwright Chromium 按 t = frame / fps 逐幀推進畫面並擷取 PNG 串流
- FFmpeg 以 libx264（CRF 18、yuv420p）與選用 AAC 音軌封裝輸出 MP4 成片
將風格選型、程式碼生成與無頭瀏覽器渲染解耦，僅在匯出 MP4 階段需要安裝 Playwright 與 FFmpeg。
10 大系列與 341 種風格分佈總覽
素材庫依用途與來源劃分為 10 個系列（定義於 docs/STYLES.md 與 references/catalog.json），另在 assets/library/ 保留獨立範例 B6（光速穿梭、爆炸、重聚，附 2 個 MP4）與 X7（英雄漫畫，附 1 個 MP4）：
| 系列代號 | 系列名稱 | 風格數量 | 核心視覺與敘事側重點 | 代表編號與風格範例 |
|---|---|---|---|---|
AG | A–G 程式碼樣片 | 26 | 字體、粒子、線與墨、光與天氣、圖形與紙、講解、質感 | A1 字雨、B2 螢火光塵、B3 粒子聚形、C1 水墨暈開、F1 圖表生長、G2 訊號故障 |
M | 動態風格 | 40 | 整段影片的運動節奏、轉場剪輯與敘事結構 | M1 白板手繪講解、M8 口播加逐字字幕、M18 數學科學講解、M23 通用講解模板 |
K | 卡通畫風 | 38 | 角色造型與平面插畫視覺語言 | K1 扁平向量、K2 Q 版、K3 卡哇伊、K13 美漫網點、K15 橡皮管 1930、K25 皮克斯式 3D |
Z | 中國風 | 15 | 傳統水墨、工筆、剪紙、皮影與敦煌壁畫美學 | Z1 水墨、Z2 工筆、Z5 剪紙、Z7 皮影、Z8 敦煌、Z9 青花、Z12 書法 |
H | 現成版式 | 12 | 雜誌級配色色票與字體排印成套搭配 | H1 Biennale Yellow、H2 BlockFrame、H8 Cobalt Grid、H12 Editorial Forest |
L | Lemo-Opuscar | 59 | 附帶完整實作做法的多類型資訊與藝術風格（MIT） | L1 字幕新聞、L10 工程方案比較牆、L14 爆炸圖拆解、L28 Risograph 絲網印刷 |
V | mg-styles-15 | 15 | 衍生自 Vincentwei1021/mg-styles-15 的動態圖形風格（MIT） | 涵蓋扁平向量、等軸測、包浩斯構成與賽博龐克 HUD 等 15 項動態設計提示詞 |
X | code-video | 31 | 衍生自 Bae-ChangHyun/code-video 的程式碼影片風格（MIT） | X7 英雄漫畫等高衝擊力分鏡與程式碼驅動視覺模板 |
R | 照參考學來的 | 7 | 以程式碼還原的賽博龐克城市與漫畫視覺參考 | R1 霓虹雨夜、R3 美式漫畫、R5 像素賽博、R6 東方賽博 |
O | 奧斯卡 98 部 | 98 | 按原素材整理的經典電影畫風、光影與構圖參考 | 涵蓋 98 部電影視覺色調與鏡頭語言文字參考 |
環境需求與安裝步驟
安裝技能與執行風格檢索僅需 Git 與 Python 3.10（或更新版本，僅使用標準函式庫，無須第三方套件）。完整儲存庫包含原始示範影片與靜幀，下載體積約 75 MiB。
Step 1：複製儲存庫並執行技能安裝腳本
scripts/install_skill.py 支援安裝至 Codex（~/.agents/skills/code-animation-prompts）、Claude Code（~/.claude/skills/code-animation-prompts）或同時安裝至 2 個環境（--target both），亦可加 --scope project --project-dir <path> 安裝至專案目錄：
git clone https://github.com/XiaoyeCodes/code-animation-prompts.git
cd code-animation-prompts
# Preview target paths without writing files
python scripts/install_skill.py --target both --dry-run
# Install to Claude Code or Codex user skill directory
python scripts/install_skill.py --target claude
python scripts/install_skill.py --target codexStep 2：驗證輕量索引與提示詞讀取
安裝完成後，執行技能目錄下的 scripts/styles.py 驗證索引查詢與單篇提示詞讀取：
python ~/.claude/skills/code-animation-prompts/scripts/styles.py list --series Z --limit 5
python ~/.claude/skills/code-animation-prompts/scripts/styles.py show B3Step 3：安裝選用的 HTML 轉 MP4 渲染依賴
僅在使用 scripts/render_video.py 將確定性 HTML 匯出為 MP4 影片時，才需安裝 Playwright、Chromium 與 FFmpeg：
python -m pip install playwright
python -m playwright install chromium
ffmpeg -version核心技能與工具鏈
專案包含離線視覺挑選、命令列檢索、Agent 技能指令與無頭瀏覽器渲染共 6 項核心模組。
Phase 01 · One-Click Import
prompts/one-click-import.md
交由 Claude Code 或 Codex 自動完成下載、安裝與驗證的導入提示詞
複製整段導入指令貼給具備本地終端機權限的編碼助手，即可自動檢查目錄、執行 install_skill.py、驗證 styles.py 檢索並回報調用方式。
Phase 02 · Offline Style Picker
skills/code-animation-prompts/assets/library/
支援關鍵字搜尋、系列篩選、靜幀放大與清單匯出的離線挑選器
於 Chrome 或 Edge 直接開啟 assets/library/ 下的風格挑選器 HTML 即可離線瀏覽 196 張靜幀與 341 個條目，勾選多個候選風格後複製編號清單交給 AI 助手。
Phase 03 · Catalog Search CLI
python scripts/styles.py search|show|list
免載入全庫提示詞的輕量級 JSON 索引檢索工具
讀取 references/catalog.json 進行編號、名稱、分類、標籤與適用場景比對，支援 --series（AG/M/K/Z/H/L/V/X/R/O）、--limit 20 與 --json 結構化輸出。
Phase 04 · Agent Skill Workflow
/code-animation-prompts · $code-animation-prompts
引導 AI 拆解主畫風、運動方式與版式職責的製作規範
定義於 SKILL.md，規範代理先查索引再讀單篇提示詞、替換模板佔位符、集中配置常改參數，並檢查首幀、中段、尾幀與轉場的字體及溢位狀態。
Phase 05 · Deterministic HTML Renderer
python scripts/render_video.py <html_path> --output <mp4_path>
基於 window.renderAt 時間函數與 Playwright Chromium 的逐幀 MP4 匯出器
自動掛載本地 HTTP 伺服器並附加 ?export=1 停用即時動畫迴圈，依 t = frame / fps 逐幀截圖並透過 FFmpeg 封裝 H.264 MP4 與選用 --audio 音軌。
Phase 06 · Baseline Integrity Validator
python scripts/ build_catalog.py & validate_repo.py
重建目錄索引與校驗 555 個原始檔案 SHA-256 雜湊的維護工具
從離線挑選器提取資料重新生成 references/catalog.json 與 docs/STYLES.md，並核對 docs/source-manifest.json 與 references/library-changes.json 確保素材庫完整性。
scripts/styles.py 與 scripts/render_video.py 參數對照
| 腳本與指令 | 支援參數 | 預設值與約束說明 |
|---|---|---|
styles.py search <query> | --series、--limit、--json | 依空白分隔多關鍵字比對 id、name、category、description、fit 與 tags；預設顯示前 20 筆 |
styles.py show <id> | --json | 精確比對風格編號（不分大小寫，如 B3、Z5、H1）並輸出原始 Markdown 全文 |
styles.py list | --series、--limit、--json | 列出指定系列（AG、M、K、Z、H、L、V、X、R、O）之風格清單 |
render_video.py <html> | --output（必填，須為 .mp4） | 輸出檔案若已存在會直接報錯停止，防止覆寫既有成片 |
render_video.py 視訊規格 | --duration、--fps、--width、--height | 預設 12 秒、30 fps、1920x1080；寬高必須為正偶數，總影格數為 ceil(duration * fps) |
render_video.py 音訊合成 | --audio <path> | 選用外部音檔（如旁白或配樂 WAV），由 FFmpeg 以 aac 與 apad 補齊或裁切至影片長度 |
社群與進階技巧
以下做法整理自 skills/code-animation-prompts/SKILL.md、references/rendering.md 與 docs/INSTALL.md。
組合多種編號時應明確切分主畫風、運動與版式職責
素材庫中 A–G 為程式碼樣片、M 為運動與敘事結構、K/Z/R 為視覺畫風、H 為配色字體版式、O 為電影光影參考。向 AI 提出需求時，切勿將多個編號的所有約束機械疊加，建議指定 1 個主畫風（如 Z5 剪紙）、1 個敘事運動（如 M5 連續長鏡頭）與 1 個版式（如 H1 Biennale Yellow）。
點名 B6 光速穿梭時直接讀取示例目錄而非檢索 catalog.json
B6（光速穿梭、爆炸、重聚）屬於獨立保留的原始範例，不計入 341 個標準風格條目中（styles.py 查詢 B6 會回傳提示訊息）。需要使用 B6 時，請直接讓代理讀取 assets/library/ 範例目錄下的 B6 提示詞與 2 支 MP4 參考成片。
匯出 MP4 前務必實作 ?export=1 停用即時迴圈與固定亂數種子
render_video.py 會對頁面附加 ?export=1 並逐幀呼叫 window.renderAt 時間函數。開發自訂 HTML 動效時，收到 ?export=1 必須停用 requestAnimationFrame、計時器與 CSS 自動播放動畫，並將粒子系統改為固定亂數種子或時間 t 的純函數，否則逐幀截圖會出現畫面靜止或跳幀。
更新技能時勿將舊版備份留在 .agents/skills/ 或 .claude/skills/ 下
install_skill.py 遇到既有目錄會自動停止以保護本地修改。升級版本前，請先將舊版目錄移出技能掃描路徑之外再重新執行安裝；若將帶有 SKILL.md 的備份資料夾留在 skills/ 目錄內，Claude Code 或 Codex 仍會重複掃描並造成同名技能衝突。
完整實戰範例
以下示範從檢索 H 系列與 B3 粒子聚形提示詞、使用 assets/starter/index.html 確定性時間介面匯出 1920x1080 MP4 影片，到驗證儲存庫完整性的流程。
Step 1：檢索風格索引並查看 B3 完整提示詞
執行 scripts/styles.py 搜尋 Biennale 版式或列出 AG 系列，再讀取 B3（粒子聚形）的提示詞內容：
python skills/code-animation-prompts/scripts/styles.py search Biennale
python skills/code-animation-prompts/scripts/styles.py list --series AG --limit 10
python skills/code-animation-prompts/scripts/styles.py show B3Step 2：使用隨附時間介面範例渲染 12 秒 1080p MP4
確認本機已安裝 Playwright Chromium 與 FFmpeg 後，執行 render_video.py 將 assets/starter/index.html 逐幀渲染為 output/demo.mp4（共 360 影格）：
python skills/code-animation-prompts/scripts/render_video.py \
skills/code-animation-prompts/assets/starter/index.html \
--output output/demo.mp4 \
--duration 12 \
--fps 30 \
--width 1920 \
--height 1080Step 3：重建輕量索引並執行 555 檔 SHA-256 基準驗證
若在本地維護或擴充了社群參考圖卡，可依序執行 build_catalog.py 與 validate_repo.py 驗證統計數量、內部連結與 SHA-256 基準：
python scripts/build_catalog.py
python scripts/validate_repo.py注意事項與授權邊界
下一步
掌握 code-animation-prompts 的 341 種風格檢索與時間介面渲染後，可搭配以下手冊深化動態設計、音軌合成與視覺生產管線：
15 種 MG 動態設計風格與程式碼渲染管線（
skills-atlas-mg-styles-15）：即本專案V系列的完整上游來源，提供 15 支 10 秒成片原始碼、mgaudio103 採樣配樂合成器與rubric.md2 輪 AI 評審工作流。華叔 AI 藝術與動態設計技能庫（
skills-atlas-huashu-art-motion）：涵蓋 53 套藝術風格配方卡、9 種解說動畫語法與 17 套搭配 Playwright 渲染的 Canvas/SVG 視覺函式庫，可與本專案的風格提示詞互補。AI 姿勢畫廊提示詞庫（
skills-atlas-ai-pose-gallery-zh）：提供結構化人物姿態與鏡頭構圖提示詞，適合用於K系列卡通畫風與R3/X7漫畫短片的分鏡設計。