Communitygithub.com

分步機制動畫

把機制、原理或流程做成一頁網頁:一次只走一步,左邊一句說明,右邊零件按因果順序移動。

分步機制動畫 是什麼?

教學動畫:把系統剖開,觀眾每滾一下只看清一層因果。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/QichangZheng/mechanism-animation/tree/HEAD/mechanism-animation

在你喜歡的 AI 中提問

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

說明文件

原理動畫(mechanism-animation)

把「它是怎麼工作的」做成一頁分步動畫:讀者滾一下走一步,每一步只講一件事,圖裡的東西按因果順序一個個出現、移動、消失。

成品參考:assets/template.html,模板,自帶一個 4 步的小例子(沒有快取 → 加一層快取),用瀏覽器直接打開就能看。

0. 先判斷:該不該做動畫

從便宜的往貴的試,前一檔講得清就不往後走:

檔用什麼什麼時候夠
1直接寫字兩三句話能說清
2編號步驟(1. 2. 3.)是個過程,但每一步一句話,讀者不需要「看見」
3編號步驟 + 2–3 張定格的靜態圖(前 / 後對比)結構、關係;或過程拆成兩三張定格圖就能看懂
4本 skill:分步動畫講的是東西從哪到哪、先後順序、同一份數據被誰共用、哪一步省掉了什麼,三張定格圖還講不清

判據一句話:把圖定格在任意一幀,讀者還能看懂 ⇒ 靜態圖就夠;要看到「動」才明白 ⇒ 做動畫。

兩條邊界:

  • 成本。動畫是靜態圖的好幾倍(核對事實、排先後、調時間、自測、來回改)。別人沒點名要動畫時,先提議、說明為什麼前三檔不夠,對方同意再做;不要預設開工。
  • 動畫只管「第一次看懂」,不能當查閱材料:不能掃讀、不能搜、貼不進文件。所以頁面結尾要有一段「全過程一覽」(模板自動生成:每步一行字);原來的文件保留文字版,再加一個連結指到動畫頁,不要用動畫頁取代文件。

1. 流程

  1. 核對事實。動畫會把錯誤講得很生動。畫之前把要講的機制對著程式碼 / 設計文件 / 論文核一遍,分清「設計上這麼說」「程式碼現在這麼做」「別家(論文、預設值)這麼做」。拿不準的寫「推斷,待實測」。
  2. 寫分鏡(不寫程式碼)。照 references/storyboard.md 列一張表:每步一行,寫清這一步講哪一件事、畫面上依次出現什麼 / 動什麼、結束時留下什麼、左邊那句話。分鏡過了下面第 2 節的講法規則再動手。步數多(> 6 步)或講法沒把握時,先跟提需求的人對一下:只發那張表加一個要他定的問題,不要發成一份文件;對方習慣直接看成品的,就直接做。
  3. 從模板起:cp assets/template.html <產物目錄>/<名字>.html。只改三處:
    • HTML 裡的 <title>、開頭頁(#top)、圖的 aria-label、結尾頁(#where,含頁腳的「更新:年月 · 對著哪個版本核的」)——模板裡這幾處還是範例的內容,逐處換掉;
    • 腳本 A 段:PAGE、MODULES(模組、步驟、文字、每步時長);
    • 腳本 C 段:畫面(有哪些物件、每一步怎麼動)。 B1 / B2 兩段是引擎,一般不動。寫法、小工具、現成套路見 references/engine.md。
  4. 自測:node scripts/check.js <頁面.html> <截圖目錄>,10 項沒有 FAIL(contain 在頁面沒有歸屬標記時是 SKIP,正常),再把截圖逐張看一遍:step-NN(每步結束)、mid-NN(每步走到一半)、page-NN(整頁)。腳本只能查「停沒停住、壓沒壓字、出沒出框、字夠不夠大」,查不了「講沒講清」。4 步的頁面約 1 分鐘、12 步約 3 分鐘,裝依賴和用法見 engine.md 末尾。 4.5 (步數多或講給外行時)「第一次看的人」測試:起一個不知道這個機制、沒讀過任何資料的子代理,只給它頁面每一步的截圖,按順序看一遍,然後憑記憶複述每一步講了什麼、是圖告訴它的還是字告訴它的、哪裡沒看懂。它看不懂的地方是頁面的問題,不是它的問題——比自己再看十遍管用。
  5. 交付:把頁面(單個 HTML,不依賴別的檔案)交給提需求的人。之後每次改完都要重跑自測再交。
  6. (內容重要時)技術核查:頁面定稿後,起一輪唯讀核查,把頁面上每句話、每個數字對著程式碼和文件逐條核,出一份「錯的 / 有誤導的 / 不精確的」清單,由提需求的人定改哪些。核查只管事實;講法好不好,由提需求的人自己看。

2. 講法規則(最重要,都是被打回來之後才學會的)

順序

  • 先易後難,先「沒問題的情況」再「出問題的情況」。讀者先看到正常是什麼樣,才看得出問題在哪。例:先講一台虛機裡很多容器共用記憶體(沒問題),再講換成很多台虛機後每台各存一份(問題),再講解法。
  • 先底層、後上層,一層層出現。先只有宿主 → 資料從磁碟進宿主記憶體 → 虛機出現 → 資料進虛機 → 最後才出現裡面的程式。不要一開場就把所有框擺好,也不要讓程式先出現、資料後到。
  • 一步裡的幾件事有因果就排先後,不要同時發生。「容器退出」之後,「它的記憶體空出來」,然後才「還給宿主」。
  • 圖等滾動停了再出現,第一步的動畫從頭播;這些模板已處理,別改壞。

每一步講什麼

  • 一步只講一件事,標題就是這件事(「三個頁面各讀一次」),不是名詞(「讀取階段」)。
  • 主線只演實際的做法。預設值、別家的做法、歷史方案,放在這一步的要點裡用一句「為什麼要專門這麼做」帶過,不要單獨做成一步——否則讀者以為實際也要先走那一步。(反例:先演「按 2 MB 上報」再演「按 4 KB 上報」,讀者問「哪來的 2 MB?到底先哪個?」)
  • 看起來一樣的兩步,讀者會以為是同一件事。兩個場景有差別,就把差別畫出來(幾條箭頭匯到同一份資料上、用圈標出共用的那一份),不要只在文字裡說。
  • 圖上出現的每個數字、每個詞都要有來頭。沒在前面交代過的數字(「18」「2 MB」)讀者會卡住;要麼交代,要麼刪。
  • 問題只屬於某一種方案時,放在那種方案的模組裡,別放在總述裡讓讀者以為都有這個問題。
  • 用讀者認得的具體例子,不用抽象符號。幾條線、幾個點、幾根小短條在動,讀者不知道它們是什麼(讀者原話:「那 4 個進度條…我看不懂是什麼意思」)。把它換成一件說得出來的事:誰、對誰、說了一句什麼(「支付系統」的 Agent 問「資料平台」的 Agent「訂單介面怎麼呼叫?」,對方回「介面文件已傳送」);符號要用就用讀者在前面已經見過的那個東西(剛才列表裡的那幾行),不要臨時發明一個。一個例子演透,比三對抽象的往來強;例子好就再加一個不同的,不要把同一個例子重複三遍。
  • 這一步用不上的層和物件不畫。「一層層出現」不等於每一層都要出現:講「容器把記憶體還給虛擬機」時再畫宿主人,讀者要多認一層卻什麼也沒多懂(讀者原話:「不需要再體現宿主人了,有點複雜了」)。畫之前問:去掉它,這一步的那句話還成立嗎?成立就去掉。
  • 講完要回答「所以呢」。每個模組的最後一步或結尾頁寫清:這對讀者意味著什麼、現在做到哪了(已上線 / 只在測試環境 / 還沒做)。
  • 深淺按讀者定。動手前寫下「讀者是誰、他已經知道什麼、不關心什麼」:對內行講基礎會被嫌囉嗦,對外行堆實作細節會被嫌太具體。

文字

  • 每步:一句話(lead)+ 最多 2–3 條要點,加粗只給結論性的數字或詞。左邊字太多就刪細節,細節放結尾頁或圖右下角的小註。
  • 不引用後面才講的東西。「不再各存一份」「還是」「也一樣」「那一份」這類話,指的東西必須已經在前面出現過。調整過章節順序後,把挪到前面的那段文字按新順序從頭讀一遍。
  • 第一次出現的術語當場用半句話解釋,全頁同一個東西只用一個叫法。
  • 頁面上不出現內部名字:RFC 號、PR 號、檔名、函式名、指令名、內部機器名。讀者就是這段程式碼的開發者時例外。
  • 術語和「數字 + 單位」不拆行:文字裡包上 {{ }},如 {{4 KB}}、{{1,380 億 token}}。
  • 頁腳標「更新:年月 · 對著哪個版本的程式碼核的」。頁面是那一天的快照,程式碼會變。
  • 推斷的、沒實測的,寫明「推斷」「待實測」;別家的數字寫清是誰的(「論文」「POC」「main 上」)。

畫面

  • 同一個東西全程是同一個物件:資料塊從磁碟「飛」進記憶體、再「飛」進虛機,而不是這裡消失那裡出現。讀者靠它跟住過程。
  • 顏色有固定含義,全頁一致(如:青 = 資料,紫 = 程式,橙 = 正在發生的動作,藍 = 結論 / 還回去的)。圖例只放用到的。
  • 動作也有固定含義,全頁不換用法(如:橙線畫出來 = 發出請求,色塊飛過去 = 資料送到,橙圈 = 大家共用的那一份,整組變淡 = 用不上了)。同一類動作速度一致:路遠的飛得久,不要都壓成同一個時長。
  • 狀態用顏色說,而且只分兩三種:例如「藍 = 正在用,灰 = 已釋放」。讀者一眼能數出有多少藍、多少灰,後面「灰的被收走」才看得懂;同一種狀態不要又用顏色又用圖示又用文字各自說一遍。
  • 要讀的字不動:一句話要從 A 傳到 B,就讓這句話停在說話的一方旁邊,沿線送過去的是個小記號;讀的是停著的字,看的是記號走的路。字跟著飛,讀者兩樣都沒看清。
  • 先動、再停:一步裡的主要動作在前六成時間內做完,之後畫面安靜,留給讀者讀左邊那句話;兩個重要的動作不同時發生;大的移動不短於半秒,橫穿整張圖的不短於 0.7 秒,再快眼睛跟不上。
  • 怎麼來就怎麼走:線條畫出來的框,退場時由線條收回去;飛進來的飛出去。全頁的進出場只用兩三種手法,淡入淡出不要成為預設。
  • 幾條線匯到同一個目標時,從不同方向進(左端、頂部、右端各一條),不要並排落在同一條邊上:遲早會重合,或者從別的圖形後面穿過去(讀者原話:「手機的線和用戶端的線重合了,並且手機本身擋住了用戶端的線」)。
  • 意思對了但不好看,也算沒做完(讀者對一朵雲的原話:「意思對了,但是雲太醜太生硬」)。關鍵的圖形(全頁反覆出現的那個、最後一步落在上面的那個)先畫兩三種樣子並排看,挑一個;看的時候問:線條和頁面上別的東西是同一個手感嗎?比例舒展嗎?和背後的線分得開嗎?
  • 強調標記(圈、箭頭、橙色小字)講到時才出現,講完就退場,最晚在下一步開頭退掉,不帶進後面的步驟。每一步結束時的畫面單獨拿出來要說得通(step-NN.png 就是這個畫面)。
  • 強調共用 / 同一份:多條箭頭匯成一條落在同一個目標上,再加一個橙圈。
  • 「省掉了」「還回去了」要演出來:東西飛到佔用條上對應的那一段,落定以後那一段再縮短;不要邊飛邊縮。飛去的位置要和縮掉的那一段對得上。
  • 示意和真實尺寸對不上時,標「示意」,並且別讓示意的格子大小暗示一個不存在的單位。
  • 框的嵌套和名字照真實歸屬:動手前列一張「物件 → 它真實在哪個網路空間 / 容器 / 行程 / 服務裡」的表。獨立的容器或行程(sidecar、代理)畫成並列的框,不畫進業務容器裡;外框寫清它是什麼(「某個容器組的網路空間」),框名用讀者心裡的叫法(「業務容器」,不是「主容器」);同名的東西分清歸屬(兩個服務各有一個叫 sidecar 的元件時,各用固定的全名),圖上和左欄都別混用。
  • 連線拐角越少越好:端點落在兩個框相對的邊上,不要瞄著框中心;兩框高度有重疊就一條直線;要拐只經一個明確的拐點(繞開障礙的 U 形最多兩個),拐點避開文字;資料包、紅線等走同一條路的東西共用這組拐點。小折彎會被讀者當成「這裡有什麼特別的含義」。check.js 的 bends 項會攔。
  • 說明小字貼在框的邊上,不要壓在框裡的物件上。
  • 圖裡的字不小於 14 個畫布單位。圖在 13 吋筆電上會縮到約 0.8 倍,再小就看不清;check.js 的 fontsize 項按 1280 × 720 下不小於 11px 來攔。放不下就刪內容,不要縮字。模板另有「放大圖」(頂部按鈕 / F 鍵),那是給讀者的選項,不是字小的補救。

3. 常見返工(收到這種回饋,直接這樣改)

回饋多半的原因改法
「這一步動畫沒結束 / 結尾有問題」關鍵幀排到了這一步結束之後,或淡入剛好卡在結束時刻這一步的動作全部在 T(id, 0.88) 前開始、T(id, 1) 前停住;check.js 的 still 項會報
「字飛出框了 / 位置不對」父框和裡面的東西不是同一時刻開始動;多寫了一幀只改顏色的關鍵幀,把位置釘住了父子用同一組時刻;給它們標 data-box / data-in,用 contain 項逐幀查。別拿別的指標(字號、透明度)代替「在不在框裡」
「第 N 步和第 M 步看起來一樣」差別只寫在文字裡把差別畫出來(見上:匯聚箭頭 + 圈)
「哪來的 X?」圖上有個沒交代的數字 / 單位交代來源,或者從圖上拿掉,只在「為什麼」裡提一句
「順序不對,應該先 A 再 B」沒按因果 / 層次排按「先底層後上層」重排這一步的時刻;順便把其他步驟也按同一條過一遍
「XX 就很奇怪,之前也沒提過」文字引用了後面才講的東西grep「不再、各存、還是、也一樣、那一份、對比」,逐處確認指的東西已出現
「字太多 / 看不清 / 太小」細節堆在左欄;圖裡的字小於 14刪到一句話 + 要點;圖裡的字調到 14 以上、放不下就刪;check.js 的 fontsize、text 項會報
「從首頁滑下來第一步沒動畫 / 重新整理後沒動畫」改壞了引擎裡的進入邏輯別動 B2 段的 enteredFirst、pendingShow、起始那幾行;check.js 的 wheel 項會報
「為什麼會有這種拐角?」(附截圖)箭頭瞄著對方框的中心,或拐點各算各的,出現一小段來回折;同一條路的資料包和線各走各的端點放在相對的邊上,能直就直,最多一個拐點,資料包和線共用拐點;check.js 的 bends 項會報。把全圖所有連線按同一條過一遍
「X 是不是獨立的 Y?畫在 Z 裡面合適嗎?」「這塊應該叫……是不是更準確?」框的嵌套沒照真實歸屬(把 sidecar 畫進了業務容器),或框名用了內部叫法先列「物件 → 真實歸屬」表再改嵌套;外框寫清它是什麼,框名改成讀者的叫法;同類的框全圖一起核

收到一條回饋後,先想這條回饋在別的步驟是不是也成立,一起改掉,別等對方一處處指。

4. 檔案

檔案內容
assets/template.html模板(引擎 + 4 步範例)
scripts/check.js自測腳本(10 項 + 截圖)
references/storyboard.md分鏡怎麼寫、一個真實的 12 步分鏡
references/engine.md模板結構、小工具、畫面套路、坑、怎麼跑自測
references/lessons.md幾頁成品做下來的回饋記錄(規則的出處);遇到規則沒涵蓋的情況來這裡找最像的一條

相關技能