昨天把 Skill 資料夾分成 SKILL.md、templates、scripts 三塊，最後留了一句，說它們之間的接點是 deck.json。Day 3 我講過它為什麼一定要有，今天不重講那段，換個問題：這份檔案裡，哪些是 AI 寫的，哪些是程式在讀、甚至程式自己寫進去的。

AI 只負責填內容

先看 SKILL.md 定的 schema，長這樣：

{
  "project": "認識的英文怎麼說",
  "caption": "完整的 IG 文案，含換行",
  "hashtags": ["#小學英文", "#親子共讀", "#國小英文"],
  "slides": [
    {"type": "cover", "emoji": "🙋", "title": "封面大標題", "subtitle": "副標痛點提問"},
    {"type": "word", "level_emoji": "🌱", "level_label": "剛認識級",
     "word": "meet", "explain": "小朋友一秒懂的比喻",
     "example_en": "英文例句", "example_zh": "中文例句",
     "illustration_emoji": "🤝"},
    {"type": "spectrum", "title": "熟度光譜表", "items": [
      {"emoji": "🌱", "label": "meet", "pct": 20}
    ]},
    {"type": "quiz", "scenario": "情境題敘述",
     "options": [{"letter": "A", "text": "選項A"}]}
  ]
}

AI 要做的事，就是把教材變成這個形狀。哪個詞放第幾張、解釋用什麼比喻、例句放在哪個校園場景、熟度光譜給幾 %，都是它在想。

但它不用管字要多大、emoji 擺哪、顏色是什麼，因為 schema 裡根本沒有這些欄位。你在裡面找不到一個 font-size，也找不到 color。AI 想「亂排」都沒有地方可以亂。

程式只負責讀欄位

另一邊，render_cards.py 做的事很單調：看每張 slide 的 type，去 assets/templates/ 找同名的 HTML，把欄位一個一個塞進佔位符。type 不在 cover、word、spectrum、quiz 這四個裡面，直接報錯停掉，不會硬湊一張。

有幾個小地方是我特別留給程式處理的，因為 AI 不需要、也不該去操心：

• 文字進模板前會先做 HTML 轉義，換行變成 <br>。AI 寫了 < 或 & 不會把版面弄壞。
• 光譜表的 pct 會被夾在 0 到 100 之間，AI 手滑寫 120 也只會畫滿。
• 單字卡如果沒給 illustration_image，就退回用 illustration_emoji 當大圖，連 emoji 都沒給就放一個 ✨。這樣不用額外的繪圖工具，也不會出現一張空白的插圖框。
• 品牌色跟字型來自 config.yaml，跟 deck.json 無關，換配色不用請 AI 重寫任何一個字。

這樣分，兩邊出錯的方式就不一樣了。AI 頂多是內容寫得不好，那改 deck.json 重跑算圖就好。程式這邊如果樣式怪，去改模板，deck.json 一個字都不用動。

有一件事要更正

Day 3 我說 deck.json 可以先驗證格式、字數有沒有超。這次回頭讀程式，我發現實際上驗得沒那麼多。

現在擋的是：輪播張數要在 2 到 10 張之間（算圖跟發布各檢查一次）、type 要認得，預覽那一步還會檢查 caption 不是空的、caption 加 hashtag 不超過 2200 字元、hashtag 不超過 30 個，以及圖卡張數跟 slides 數對得上。

沒擋的是欄位有沒有漏。render_cards.py 讀欄位都用預設值，AI 漏掉 example_en，那一格就是空的，圖照樣算得出來，不會報錯。每個欄位的字數有沒有超過版位，目前也沒有程式檢查。這一關現在靠我在第 4 步看 preview.html 用眼睛抓。

所以 deck.json 現在做到的是「擋掉會讓整條流程壞掉的錯」，還沒做到「擋掉內容寫得不夠好的錯」。要補的話，我會加在算圖之前，寫一支小檢查，逐欄位看有沒有漏、字有沒有太長，這是後面可以改的地方。

程式也會回頭寫進 deck.json

最後一個我覺得有意思的點：deck.json 不只 AI 寫、程式讀，程式後面也會往裡面寫。

upload_images.py 把圖傳上圖床、驗證網址都能打開之後，會把網址清單寫成 uploaded 欄位存回去。publish_ig.py 讀的就是這個 uploaded，沒有的話直接停下來，叫我先跑上傳。發布成功之後，它再把 media_id、permalink 跟時間寫進 published。另外 publish_ig.py 發布時還會順手讀每張 slide 的 alt_text 當圖片替代文字，這個欄位 SKILL.md 的 schema 裡沒列，有寫才會帶上去。

所以到最後，一份 deck.json 裡有三種東西：AI 寫的內容、程式補的上傳結果、發布紀錄。每種各管各的欄位，互相不蓋。這也是為什麼 SKILL.md 會說它是後面所有步驟唯一的真相來源。隔了幾天想回頭看那篇貼文發了什麼、連結在哪，翻這一份就有。

小結

回到今天的問題：AI 負責「說什麼」，程式負責「長怎樣」跟「做到哪了」，deck.json 是兩邊交接的地方。交接的格式定得越窄，兩邊越不容易踩到彼此。

不過我也看到了，窄歸窄，現在驗證的那一層還有洞。這個我先記著。

明天開始進第三部分裡 AI 負責的那一塊：怎麼設定角色跟受眾，讓它把教材改成國小生看得懂的樣子。