codepawl/machine-anatomy

機器解剖圖

一套共享工具包：新的機器只需撰寫其模型、佈局與繪圖、動態鉤子（live hooks）以及事實資料。 工具包負責頁面、主題與風格、縮放框、爆炸視圖、事實校驗（truth lint）、 錄製、音效與檢查。參考範例為 examples/edison-light-bulb/；請複製其結構。

1. 一次提問，然後建構

在開始任何程式碼之前，請使用主機的提問工具（Claude Code 中的 AskUserQuestion）一次回合向使用者提出入門問題，每個問題附上建議的預設值，跳過他們已經說過的內容。然後直接進行，不再需要額外關卡。問題、預設值以及每個答案如何對應到設定，請參閱：references/intake.md。

2. 研究，然後建立事實

閱讀真實來源（專利、製造商論文、博物館頁面、百科全書）。撰寫 reference/notes.md，包含網址和引用句，然後建立 facts.json：每個事實一條記錄，包含 text、source、quote 或 note，以及 status（verified 或 inferred）。規則及校驗（lint）的強制內容請參閱：references/truth-control.md。 從來源列出機器的每一項功能及其設定，放入 functions。

接著收集至少 3 張真實照片或圖紙，以及機器的設定，放入 reference/images/ 並附上 sources.json，繪圖前應先打開每一張；每個組件必須宣告其繪製所參考的圖片。 校驗（lint）會強制執行此規則，而 record 會寫入 shots/reference-compare.png 以供比對：請參閱 references/reference-images.md。

3. 建立機器資料夾

node cli.mjs new <folder> --title "..." 會從愛迪生燈泡範例建立範本。請依序取代以下檔案：

1. model.mjs — 純模型，無 DOM；所有行為與顯示的數字均在此定義。test-model.mjs 根據真實數值或不變量進行測試。測試是強制的。
2. layout.mjs — 世界單位的大小以及計算出的曲線（路徑必須遵循真實零件，不能使用弦線近似）。
3. figure.mjs — drawFigure(draw)：使用工具包的輔助函數繪製真實零件，作為編號組件的項目；回傳標籤、defs、CSS、徽章錨點、步驟點以及縮放目標。
4. live.js — createMachineHooks(kit)：狀態、移動零件的繪製、控制項、讀數、動作。使用 kit.Motion 處理彈簧、慣性與關節：請參閱 references/motion.md。
5. machine.mjs — 組件，包含移除軸線與來源，每個可見文字為 { text, facts }，讀數範本、控制項、影片故事、音效語音。

在撰寫每個檔案之前，請先閱讀範例中對應的檔案；不要閱讀已建構的 *.html 檔案。

4. 外觀

主題與渲染風格是兩個獨立的層次：請參閱 references/themes-and-styles.md。在 machine.mjs 中設定預設值（theme、style）；頁面可使用 ?theme= 和 ?style= 切換。

5. 影片與音效

預設影片為經核准的 30 秒結構（先運轉、一次縮放入場、一次慢速標註運轉、正常運轉並包含一個對比時刻、逐漸拆解、組回、最後繼續運轉）：請參閱 references/film.md。 音效為安靜的近距離敲擊聲，無嗶聲，無限制器：請參閱 references/sound.md。發佈影片時的字幕規則：請參閱 references/caption.md。

6. 命令與檢查（所有步驟在移交前均為必要）

node cli.mjs lint   <folder>     # 文字綁定至事實、來源、最高級用語、來源追溯
node cli.mjs test   <folder>     # 模型測試
node cli.mjs build  <folder> [--format 16:9,9:16,square]
node cli.mjs audit  <folder>     # 爆炸視圖的繪製順序與穿透檢查
node cli.mjs verify <folder>     # 在無頭 Chrome 中檢視真實頁面，每種主題與風格
node scripts/lines.mjs <folder>/<slug>-anatomy.html   # 紋理線條必須有終點
node cli.mjs record <folder> [--format 9:16] [--style dither] [--no-sound]
node cli.mjs remux  <folder>     # 僅變更音效，保留已錄製的幀
npm test                         # 工具包單元測試

Playwright 未內建：請執行 npm install --no-save playwright，或將 MACHINE_ANATOMY_PLAYWRIGHT 設為現有的 Playwright index.mjs。錄製作業會以低於正常的優先順序執行，且不使用 GPU。

接著請自行開啟 shots/<variant>/video-sheet.png、三張靜態截圖、驗證截圖以及 shots/reference-compare.png；修正裁剪、重疊、無法閱讀的文字、浮動圖案，以及與參考圖片之間任何未經宣告為簡化的差異。

所有者設定的規則（若存在檢查則強制執行）

• 任何東西都不應遮蓋其他東西：record 與 verify 中有一項碰撞檢查（references/film.md）；僅可宣告物理上真實存在的重疊，並說明原因，置於 film.overlapAllowed 中。
• 必須在機器完整的真實設定中展示（入門問題第 10 題），並附上來源與出處。
• 主體在每個階段至少佔據畫面高度的 25%，關鍵事件必須發生在畫面內（minimum.subject、film.onScreen）；移動中的機器應使用 hooks.camera() 追蹤鏡頭。
• 圖案必須鎖定在表面上，不可浮動；使用 scripts/swim.mjs 量測（references/themes-and-styles.md）。
• 火焰、蒸汽、煙霧與發光效果必須使用 kit/effects.mjs，由模型驅動（references/motion.md）。
• 每個運轉中的零件都必須顯示其運轉狀態，或明確說明原因；不得有無繪製原因或主動原因的運動；壓縮的時間必須在畫面上顯示（references/completeness-and-causality.md、lint 與 record）。

報告

頁面路徑、發佈片段與影片檔案；lint、test、audit、verify 與 lines 計數；音量、真實峰值與影片頻譜（說明無人收聽）；影片時間軸；每個字幕事實及其來源；簡化、推斷或未經驗證的內容。

致謝：基於 Ryan 的 Anatomy 專案（github.com/wheresryan22/anatomy，MIT 授權）。詳見 THIRD_PARTY_NOTICES.md。