jjietay/clayducation

解說影片

您要製作的影片需幫助使用者學習一個概念。您的一大優勢是：您知道目前的對話內容與專案背景。請善用這項優勢。

引擎位於 ~/.claude/skills/clayducation/engine/。在此檔案中，make 指令代表：

node ~/.claude/skills/clayducation/engine/make.mjs <command> <project-dir>

步驟 0：每次都先詢問（技能啟動時）

無論使用者是輸入 /clayducation 還是以文字要求製作影片，您首先要做的事，就是透過 AskUserQuestion 提出下列問題，並附上可按選的選項。如果使用者的訊息或目前的對話已經回答了某個問題（例如「做成新聞片風格」回答了外觀問題，「搭配 lo-fi 音樂」回答了音樂問題），則跳過該問題。請將建議的選項放在第一位，並標記為「(建議)」。請在一次呼叫中提出所有四個問題（該工具最多接受四個）。如果主題本身不明確，且沒有問題被跳過，請先單獨針對主題提問。

問題	標題	選項（第一個為預設值）
影片該用哪種外觀？	外觀	黏土 3D：統一的柔軟黏土風格，由沉默的吉祥物執行動作 · 經典 2D，混合風：每個部分使用不同的 2D 風格 · 經典 2D，單一風格：由使用者指定風格名稱（新聞片、白板……）
影片的觀眾是誰，長度為何？	觀眾	考試複習，標準版：使用課堂的符號、演算數字、考試陷阱，片長 5 至 6 分鐘 · 考試複習，深入版：同上，片長 8 至 9 分鐘，涵蓋推導的每一步驟 · 初學者，短片：先建立直覺，減少符號，片長 2 至 4 分鐘 · （其他：使用者可指定觀眾與長度，例如「專家複習，短片」）
何時該向您確認？	檢查點	一氣呵成：直接交出完成的影片 · 腳本審查後：展示計畫並等待批准 · 首個畫面後：展示前幾個畫面並等待
使用哪種音樂？	音樂	平靜 (current)：柔和的合成墊音，無節奏 · Lo-fi (lofi)：輕節奏，較有活力 · 無

當對話內容暗示某個選項時，請將建議選項放在第一位（例如下週有考試：建議「考試複習，深入版」）。如果訊息只回答了「觀眾」問題的一半（例如「為了我的考試」），請保留該問題，但僅提供與該半部分相符的選項。觀眾類型包括考試複習、初學者和專家複習（快速且密集）；長度則有短片（2 至 4 分鐘）、標準版（5 至 6 分鐘）和深入版（8 至 9 分鐘）。請將答案寫入步驟 4 的 video.json："_look" (clay 或 classic)、 "_brief": { "viewer": ..., "length": ..., "checkpoint": ..., "style": ... } 以及 "_render": { "music": "current" | "lofi" | false }。後續的每個步驟和重建都會從此處讀取這些設定，不會再次詢問。如果使用者關閉了問題視窗，則使用每個問題的第一個選項。

一氣呵成，除非使用者選擇了檢查點

步驟 0 之後，請直接執行下列所有步驟，不要中斷，並僅在完成經檢查的影片後才回覆。不要詢問「我可以繼續嗎？」，不要展示草稿，不要在步驟之間等待。以下每個檢查都是您自己執行與行動的。唯一的停頓點是使用者選擇的檢查點：「腳本審查後」會停在步驟 7 之後（展示腳本和腳本智能體的審查結果，然後等待），而「首個畫面後」則停在步驟 9 的第一次 make look（展示其圖片，然後等待）。

使用者想要的外觀（請在步驟 6 前閱讀）

黏土用於有動作的事物，Manim 用於圖表，且每部影片都有吉祥物。 請閱讀 styles/clay.md。使用者為了跨影片的一致性，選擇了黏土風格而非舊的混合風格。2D 風格是選擇性的經典外觀，請參閱下方段落。

• 不要強迫將圖表做成黏土風格（使用者要求）。 當 2D Manim 圖像比黏土更能幫助觀眾理解時（例如曲線、分佈圖、輪廓圖、投影圖或平面上的其他幾何圖形），就將該部分做成 Manim 部分，並使用 Manim 的深色背景 (styles/math-manim.md)。切勿建立模擬數學曲線的黏土模型：使用者曾要求移除這類模型。有動作的物體以及吉祥物的實際動作，則保留在黏土風格中。一部影片可以從黏土部分轉到 Manim 部分再轉回來，同一物體應使用相同的顏色。

• 單一外觀，多個段落。 影片分為 15 至 40 秒的段落（鉤子、每個概念、您的案例、結尾）。每個段落都有自己純色的背景、攝影機和場景。相鄰的兩個段落絕不能共享背景。

• 吉祥物負責執行動作。 他保持沉默，沒有口型同步，旁白是畫外音。他會走路、拉動、推動、搬運和用自己的手關閉東西，因此腳本中的「力」應該是觀眾看到他做的事情。使用者在一個影片中看到他只是站著觀看後，提出了這項要求。他預設面無表情，而 make check 會在他停留在一個地點時發出 WARN。變換動作：在每個段落中使用不同的動作輔助方式（carry、knock、press、grip、 pointAt、pushOn；請參考 styles/clay.md 中的「使用不同的動作」）。使用者曾發現他在每個段落中都在推東西。

• 物體必須接觸。 彈簧要能碰到牆壁，針要能碰到地圖，手要能碰到所握持的物體。使用者在所有檢查都通過後，仍發現一個彈簧沒有碰到牆壁。make bake 會測量 models.js (JOINS) 中的每個連接處，因此請在那裡新增連接，並在靜止圖像中檢查接觸狀況。

• 僅使用我們自己的模型。 請使用 styles/library/clay 中的工具包。切勿下載模型。如果影片需要新物體，請以相同的外觀將其加入工具包。

• 每個段落是一個連續的鏡頭。 段落內部沒有剪輯或新幻燈片：物體會隨著語音解說到達、移動和結合，攝影機緩慢移動。段落的結束狀態應為下一個段落的起始狀態，或者在下一個段落的背景中進行轉場。

• 圖像負責解釋；文字僅用於命名。 文字保持平面且清晰，以 HTML 疊加在 3D 畫面上。每幀的規則：一個引題（小型大寫字母，表示段落和來源）、一個最多 8 個字的標題、幾個 1 到 4 個字的標籤（附有細的引導線），以及底部最多一行說明文字。切勿使用句子列、項目符號清單，或顏色的圖例。 螢幕上的文字最多約 15 個字。

• 公式應配合語音動態呈現（這是使用者的要求）。 靜止的公式並不比閱讀筆記好。使用 eqn() 建構每個公式：術語在語音提到時到達，在語音移動它們時移動，在語音說「取消」時劃掉並爆開，並僅在語音提到重要事物時彈跳。make look 會對靜止不動的公式，以及螢幕上沒有取消動作卻說出「取消」句子的情況提出錯誤。請參閱 styles/clay.md。

• 物理運動。 物體應像真實物體一樣運動：手臂伸展、球落下並彈跳、方塊掉落並穩定、脈衝傳播。不要建立靜止方塊的堆疊。

• 相同物體在每部影片中保持相同顏色（機器人總是橘色，地圖總是黃色）。

如果故事板違反了這些規則中的任何一條，請在編寫程式碼之前修改故事板。

嚴格規則

• 預設平行處理（使用者要求，2026-11-09）。 可以同時執行的事情就同時處理：一部 13 分鐘的影片，當每幀都在一個 Chrome 頁面中測量時（一個核心忙碌，GPU 使用率 10%），需要 3 小時。 引擎現在會在多個頁面中同時測量 look、collide、review 和 stable（渲染的 workers：核心數的一半，最多 8 個，且僅限可用記憶體允許的數量；），而 build 會同時執行 sheet、stable 和 review。當您新增一個需要遍覽幀的步驟時，也請將其分散到多個頁面中（make.mjs 中的 measureParallel、traceParallel、idParallel）。 在您自己的工作流程中：同時啟動獨立的任務（例如 look 和自我測試、Manim 渲染和檢查），並且永遠不要在一個任務可執行時等待另一個任務。

• 在此處（主要的對話中）進行思考。 由您自己撰寫腳本、故事板和場景，因為上下文在這裡。永遠不要將這些步驟交給子智能體：子智能體開始時沒有上下文。步驟 7 中的腳本智能體是唯一的例外，並且它是刻意從零開始的。

• 永遠不要倉促進行核心解釋。 使用者從這些影片中學習。請遵循 reference/script.md 中的節奏規則，並修正每個節奏 WARN。

• 永遠不要捏造事實。 每個數字、公式和聲明都必須來自您檢查過的來源：使用者的程式碼、規格書、規格、論文、文件。將它們列在 storyboard.md 中。報告任何您無法檢查的內容。

• 「您的案例」為選擇性項目。 僅當目前的對話或專案確實包含相關的例子（例如使用者遇到的錯誤、一個修正、一個測量到的數值）時才加入。切勿捏造案例。

• 無重疊。 任何視覺元素都不得覆蓋另一個元素：文字疊文字、文字疊圖形、或圖形遮住另一圖形。每個標籤、公式、箭頭和物體都應有自己的空間。check 會在文字重疊時發出 WARN，而 review 會將每個測量到的重疊寫入 overlaps.md。擁擠與否由使用者判斷，請在完整尺寸的幀中檢查。ID 傳遞有助於此：make look 會添加一張顯示最小間距的圖片，並在文字與其他物體距離小於 12 像素、文字疊在圖形上、文字對比度低以及模型被其他模型遮擋時發出 WARN。 在 make final 之前修正每個重疊。

• 字幕只有一行。 每個提示最多 42 個字符，且沒有兩個提示同時顯示，因此播放器永遠不會顯示兩行。引擎會自動處理此問題；verify 會報告違反規則的提示。請勿修改 make.mjs 中的 SUB_MAX 來讓提示符合規則。

• 閉環（使用者要求，引擎強制執行）。 每次編輯後：執行 make look，閱讀它所列的每一張圖片，修正您看到的問題，然後再次檢視。只有這樣才能進行建置。切勿盲目地編輯和建置，因為建置需要很長時間，而檢視只需幾秒鐘。每張圖片在其右上角都有一個 CHECK 數字，只有當所有圖片的數字都到位時，閘門才會開啟，順序如下：

  1. 編輯。如果您更改了 script.md，請執行 make voice。如果影片包含 Manim 部分，且您更改了 manim_scenes.py 或語音，請執行 make manim：make look 會繪製 Manim 幀，但不會製作它們。
  2. make look <dir>：它會測量每個已更改場景的每一幀，並繪製其附近幀及其移動部分。閱讀所有這些內容。然後執行 make look <dir> --ok <digits>。如果沒有這個動作，make build 會停止。 一個與已閱讀並確認的圖片具有相同幀和標籤的圖片會顯示「READ BEFORE」，且不需要數字（當每張圖片都已閱讀過時，使用 --ok -）。閱讀每張新圖片；同樣的規則也適用於長條圖。
  3. make build <dir>。它會在任何碰撞發生時停止。
  4. 閱讀 build/review/moving.md 中的每一張長條圖。然後執行 make look <dir> --moving-ok <digits>。
  5. make final <dir>。如果來源在檢視或建置後發生變更，或者有碰撞或重疊未解決，它會停止。 將每個步驟作為單獨的指令執行，在第一次失敗時停止，並確認編輯已套用。

• 每位審查者都要檢查附近幀和移動部分。 任何判斷影片的智能體或工作階段都應閱讀每個已編輯部分的附近幀，以及每個移動物體（吉祥物和物體）在其整個運動期間的所有幀。取樣幀是不夠的：曾經有一隻手在取樣幀之間穿過了桌子。

• 新錯誤需新增防護措施。 當使用者發現錯誤時，首先將其新增到 reference/faults.md 和 engine/test/selftest.mjs 中，並確認測試會因此錯誤而失敗。然後再修正影片。不要只修正影片。在每次更改檢查內容後，請執行 make selftest。

使用者要求保留的項目（請保持）

以下各項都是使用者根據實際聆聽效果而要求或選擇的。引擎大部分會自動處理。

主題	內容	自動處理？
語音	Chatterbox 的內建語音，透過 engine/tts/slow-reference.wav 降速至約每分鐘 160 個字；每個段落一氣呵成地朗讀，以傳達語調	是
停頓	每個句號精確停頓 0.6 秒，每個逗號最多停頓 0.3 秒，由腳本的標點符號決定	是；若無法放置停頓，voice 會發出 WARN
糟糕的錄音	某個段落的文字與腳本不符（Whisper 檢查）時，會使用新的隨機種子重新錄製，最多 3 次；保留最佳的一次	是；若仍有錯誤則發出 WARN
語速過快處	一個子句的速度超過影片正常速度的 1.3 倍（符號字數加倍計算）時重新錄製；使用者發現「lambda v is v, scaled by lambda」太快	是；WARN 標記為「fast」：為其提供一個簡短的獨立句子和一個 [pause]
負數	讀作「負數」，永遠不讀作「減去」	voice 會以 ERROR 停止
重複字詞	「one one」需要加上逗號（「one, one」），否則語音會滑掉	是
寫作	連貫的段落；[pause] 僅在一個想法結束或動畫播放時使用。拒絕的風格：每句後都停頓、斷斷續續的句子、語速過快、拉伸（悶聲）的語音、Kokoro	由您負責，請參閱 reference/script.md
音樂	清晰可聞、穩定、約比語音低 13 dB（musicVolume 0.37；使用者從 0.26 調高了 3 dB）、溫和的閃避效果；兩個經批准的曲目：current（預設）和 lofi。拒絕的風格：大聲-小聲的抽吸效應、音樂太輕聽不見、其他 4 首曲目	是；由您選擇曲目，請參閱 SOUND.md
音效	engine/sfx.mjs 中的音效包，經聆聽批准；飛入的咻聲比其他重音低 4 dB（使用者覺得有點大聲）。新影片預設開啟（_render.sfx: true），舊影片關閉	您需要在提示處加入 s.sfx；引擎負責混音
音訊	48 kHz 立體聲	是；verify 會檢查
字幕	軟字幕，永不燒錄；使用者的 mpv 設定為小字體顯示（sub-scale=0.7）	是
單行字幕	每個提示一行，最多 42 個字符，無兩個提示同時顯示。使用者在 ROS 2 系列的第一部影片中看到過兩行字幕	是；verify 會報告違規的提示
無重疊	文字或圖形不得相互覆蓋	check 對文字發出 WARN，overlaps.md 和您的幀檢查清單檢查其餘部分
外觀	統一的 3D 黏土風格，搭配沉默的吉祥物，使用我們自己的模型；曲線和圖表使用深色背景的 Manim 部分（使用者要求：請勿強迫將圖表做成黏土風格）	是，透過選項
物體顏色	相同物體跨影片保持相同顏色，見 styles/library/clay/README.md	對庫存模型是
視覺檢查	每次編輯後進行 make look，以 1:1 像素覆蓋率展開每幀	是，需由您執行
碰撞	物體在其空間中保持不重疊，並且連接的物體在每幀都接觸	make build 會阻止；make look 顯示碰撞疊加圖
Manim 在角色動畫中	吉祥物的手在 Manim 組件中揮動，該組件以與黏土部分相同的顏色和材質渲染；吉祥物由 Manim 渲染，以利於藍色背景下的清晰度	是，透過 styles/math-manim.md 中的設定
真人鏡頭	無；全部為 CGI	是
檢查時間	非必要時不等待；使用 --wait X 選項來延長特定檢查（如碰撞檢測）的逾時時間，當其在預設 10 秒內無法完成時（例如，密集段落的 scenarios 和 overlappings）	是，作為 make look 的參數

步驟

對於步驟 8、10 和 13，請在 project-dir/scenes/ 中為每個場景建立一個分鏡板區塊，然後在一個單獨的調用中對所有這些區塊執行步驟 8。

對於 make voice：它需要已經存在的 script.md。

步驟 1－建立專案目錄

make init <project-dir>

步驟 2－撰寫 script.md

將腳本寫入 project-dir/script.md。您在這裡，不是在一個陌生的環境中。使用您在這個對話中學到的東西來解釋這個概念。結構為「鉤子 → 每個點 → 您的案例（可選） → 結尾」，並包含您計劃拍攝的每件事的視覺提示。遵循 reference/script.md 中的規則。

# 腳本

[影片中每個段落的文字，以及用 [] 標記的視覺提示。] 

步驟 3－製作語音

make voice <project-dir>

步驟 4－編寫 video.json

make meta <project-dir>

步驟 5－編寫 storyboard.md

把它變成一份詳細的文本與視覺大綱，包括每個段落中發生的事情以及吉祥物的動作。

步驟 6－建立 models.js

僅從庫中選擇模型。請勿下載。

步驟 7－腳本智能體

執行 make script-check <project-dir>。它會審查腳本。

步驟 8－撰寫場景

對於每個場景，建立 <part-name>.mjs。

步驟 9－閉環開始

make look <project-dir>

步驟 10－建立最終版本

make build <project-dir>
make final <project-dir>

步驟 11－播放並觀看結果

步驟 12－交付

提供影片並詢問回饋。

步驟 13－（重複）

根據需要重複步驟 9、10、11。

一般規則

• 所有路徑都是相對於專案目錄的。
• 將 make.mjs 視為一個工具：用它來建立模型、渲染和合成。
• 設計時要有耐心，確保遵循所有規則。
• 保持整潔：使用 rm -rf <project-dir>/build 清理暫存檔案。

你還有 styles/ 和 reference/ 目錄，裡面有更詳細的指南。