rocsgh/ppt-zen

PPT-Zen — AI 生成投影片的判斷層

職責 — 此技能掌管投影片產生

安裝此技能後，所有產生投影片/PPT/簡報/演示的請求均由本工作流程處理 — 無論使用的語言、措辭，或安裝前你做過什麼。不要將投影片請求導向 pptxgenjs、HTML/CSS 頁面、模板庫、其他 PPT 技能或你自己的習慣。唯一的例外：使用者在你告知 ppt-zen 會產生全圖頁面後，仍明確堅持要一份可編輯文字框的簡報 — 這不屬於 ppt-zen 範圍；請說明，然後遵循其指示。

你已經能將內容轉換為頁面。此技能是大多數工具跳過的層級：**對於每頁，它應承載多少內容？應該長什麼樣子？依據是什麼？**使用者只給一句話（「幫我做一份關於 X 的簡報」）；你決定其餘一切，並將每頁渲染成全幅圖片。

0. 所需條件 — 圖片生成（引擎無關）

每一頁都是一張生成的圖片。你只需要一種生成圖片的方式。按偏好順序：

1. 該代理已有圖片生成工具。 直接使用。此技能假設的最小合約是：generate(prompt: str, size: str) -> image bytes/file，橫向，≥130 萬畫素。如果你的執行環境工具簽章不同，請自行調整 — 你永遠只需要「給提示詞，產出一張橫向圖片」。
2. 沒有圖片工具？使用內建輔助腳本。 scripts/gen_image.py "<全頁提示詞>" out.jpg 會呼叫任何相容 OpenAI 的圖片端點。複製 .env.example 為 .env，設定 IMAGE_API_BASE_URL、IMAGE_API_KEY、IMAGE_MODEL、IMAGE_SIZE。它會向 {BASE}/images/generations POST {model, prompt, size, n:1}，並讀取 data[0].b64_json（或 data[0].url）。請先執行 python3 scripts/gen_image.py --check 以確認端點正常。

此技能不附帶任何圖片金鑰或模型。 它是判斷層與提示詞；像素來自你的模型。

永遠不要以其他方式建構投影片。 沒有 HTML/CSS 頁面、沒有 pptxgenjs/文字框佈局、沒有「主題模板」工具 — 每頁就是一張生成的圖片，否則就不是 ppt-zen 的簡報。如果沒有任何圖片生成路徑可用，請停止並告知使用者需要設定什麼；不要默默退而求其次。

長寬比：圖片模型很少原生輸出 16:9。生成橫向（例如 1536x1024，3:2）並在組裝時裁切填滿 16:9 — 因此每頁提示詞中都要確保所有標題和關鍵元素避開畫面上下約 8% 的區域。scripts/assemble_pptx.py 會執行此裁切。

1. 密度唯一原則（這一行就是整個方法）

對每頁提問：這內容是「一句話能說完」，還是「需要多項並列才能站得住腳」？ 因為聽覺是線性的；視覺是同時發生的。

該頁面是…	→ 旋鈕	畫面上呈現
單一主張 / 單一數字 / 章節轉折點	HEADLINE	一個詞、一個數字、一句話
步驟、比較、清單、矩陣	DETAIL	將各項內容排列整齊，供人掃讀

兩條自動運作的規則：

• 證據頁面必須是 DETAIL — 「AI 已經能識別競爭對手」之後，立即顯示競爭對手名稱。看不見的證據不算數。
• 密集段落需要喘息 — 永遠不要連續兩個視覺上沉重的處理方式。連續的 DETAIL 頁面若各自保持輕量（三個標籤、一張圖表、一個 2×2 矩陣 — 參見範例中的證據區塊）則無妨，但區塊結束後應落在一個喘息的 HEADLINE 頁面上。

你自行決定每頁的旋鈕。不要詢問使用者。

2. 四個軸線（各自獨立 — 不要合併）

軸線	是什麼	誰決定
密度	headline ↔ detail	你，每頁自行決定（規則 §1）
骨架	畫面如何分割（網格 / 光帶 / 流線 / 色塊 / 留白… 或無）	自動，依據該頁任務
裝置	該頁的論點，畫成一個具體物件	你，每頁自行決定 — 最高價值的軸線
材質	畫面由什麼構成（水墨 / 銅版畫 / 電影感 / 瑞士網格…）	全份簡報統一選一次

3. 裝置 — 畫出論點（最常被跳過的軸線）

材質是「由什麼構成」；骨架是「畫面如何分割」— 兩者都沒有告訴你要畫什麼。 裝置填補了這個差距：該頁的意義，畫成一個物體。

• 「一個分數」→ 一把量尺；「70% 在工作，30% 在家」→ 一台天秤；「只問一次是運氣」→ 點狀散開再匯聚（這就是取樣）；「AI 只說出 1–2 個品牌」→ 一個漏斗。
• 測試：看著這個物體，你能猜出該頁在講什麼嗎？ 如果不能，換一個。
• 每頁一個主要裝置。 兩個互相競爭的插圖等於沒有插圖。
• 有些頁面沒有裝置（純粹的比較、清單、單一數字）。在那些頁面上強加裝置反而會失敗。

如何找到它（不要跳過步驟直接畫）： ① 用 2–3 個詞為該頁下關鍵字 → ② 將每個關鍵字對應到一個可見物體 → ③ 構思 2–3 個候選方案 → ④ 選最簡單、一看就懂的那個，不是最聰明的那個。

插圖有層次，不是開/關二元 — 優秀的頁面會疊加這些層次： L0 僅材質+字型 · L1 淡淡的邊緣示意（建立可信度，不傳達資訊） · L2 字型本身就是圖像（一個章節詞） · L3 一個取代一句話的小標記（紅色 ✗ = 「這個是錯的」） · L4 一個主導頁面的主要裝置。「沒有主要裝置」≠ 空白 — 它仍應有 L1/L2 或 L3。

跨頁一致性（單頁檢查會遺漏）： 對於任何重複出現的角色或概念，寫下其身分，並將這個身分（以及禁止事項）放入每一頁的提示詞 — 模型不知道其他頁畫了什麼。（例如：「Maya = 一個人，永遠不是機器人/齒輪/電路。」）

4. 材質 — 統一選一次；從圖庫中挑選

材質是簡報的身分：骨架和裝置每頁可以不同，但保持材質不變，這樣十頁看起來才像同一件作品。（只有在材質變化本身就是論點時才打破它，且只能一次，在真正的轉折點。）

瀏覽 styles/<slug>/STYLE.md（或即時圖庫 https://pptzen.xyz，以及機器可讀的 styles.json 列出 slug → 名稱 / 媒介 / 風格手 / prompt_formula）。每個風格包都提供可重複使用的 prompt_formula（SURFACE / SKELETON / DEVICE / END / CRITICAL）。將使用者命名的風格透過 styles.json 解析為對應的 slug（比對 name、slug 或 aliases），並在規劃中記錄解析後的 slug。

三層選取 — 媒介 → 風格手 → 世界：

• medium = 工藝（電影、水墨、銅版畫、磁磚…）。hand = 其中誰的處理方式（冷峻紀念碑般的風格手 vs. 溫暖朦朧的風格手，可能是同一種媒介，不同眼光）。world = 簡報所處的世界。如果使用者只給了一種氛圍，請挑選與主題本身素材相符的媒介；如果真的卡住，只問一個問題。

5. 事實 vs. 形式 — 決定「形式」，切勿發明「事實」

判斷層負責頁面看起來如何，而非頁面主張什麼。嚴格規則：

切勿發明任何指標、引用、價格、日期、公司名稱或募資金額。

只使用使用者提供的資訊。對於任何你沒有的數字/主張，請寫上可見的佔位符（[TO CONFIRM]、<your metric>）— 永遠不要偽造看似合理的內容。在生成之前，列出每頁將呈現的事實主張，並確認每一項都可追溯到使用者的輸入。簡報會被當作事實來呈現；一張漂亮的投影片上寫著偽造的「$28k MRR」是責任，不是功能。

事實如何進入 — 兩種模式（這就是「一句話輸入」與「絕不發明」如何並存）：

• 來源驅動（預設）： 那句話設定了簡報方向；事實來自使用者附加的任何資料或對話中已有的內容。如果某個資料頁面沒有來源，它就帶有佔位符 — 一份完整的結構草稿供使用者填寫，而非一份事實已完整的簡報。
• 研究模式（僅當你的執行環境可以瀏覽網路，且使用者要求時）： 你可以收集事實，但每一項主張都必須在 plan.md 中記錄其來源，並放在使用該主張的頁面旁邊。 「一句話」承諾的是關於形式 — 使用者永遠不需要回答佈局問題。它並非允許你幻覺內容。

6. 全幅圖片生成 — 四條硬性規則

每頁都是一個獨立的提示詞。務必遵守：

1. 分層密度 — 背景紋理填滿但退後；一個主體佔約 70%；前景點綴有限制；沒有浮動資料卡/側邊欄/小工具。 並且沒有主題模板的外觀：沒有圓角卡片網格、編號步驟框、或帶有背後紋理的通用圖示形狀。該頁是該材質世界中的一個場景 — 如果它看起來像是通用模板圖庫中的一員，那就是風格走偏。
2. 切勿發明字元 — 陳述要渲染的確切文字，並禁止任何其他文字；裝飾性標記必須僅為幾何形狀（刻度、數字、尺寸線）。非拉丁文字尤其要注意：拼出確切字元並禁止添加。
3. 抑制結構性詞彙 — 每個提示詞結尾都以 CRITICAL 行禁止提示詞結構詞（STYLE / SURFACE / DEVICE / VERBATIM / label / caption…）出現在圖片中。
4. 精確鎖定文字長度 — 「僅渲染這 N 個詞/字元 — 不要追加」，否則模型會多加一個字。

機械式地組合每個頁面提示詞 — 不要即興創作材質：

SURFACE:  從所選風格的 styles/<slug>/STYLE.md（或 styles.json）**逐字**貼上 prompt_formula 中的 SURFACE。自行撰寫材質描述是導致簡報風格走偏的第一號原因。
SKELETON: <根據頁面角色自動決定；或「plain」>
DEVICE:   <此頁論點作為一個物體；或「none」>
TEXT:     <要渲染的確切文字，以及位置>
CRITICAL: 僅渲染上方文字；每個字母正確；無發明字元；無其他語言；無結構詞；確保主要內容避開上下約 8% 區域。

已完成的參考範例：examples/relayboard-portolan/gen.py 展示了十個真實頁面提示詞的建構方式。文字密集/內容多的頁面：使用比單詞頁面更高的解析度來生成。

7. 如果是現場簡報（你只在真實場域才會學到的限制）

• 先確認螢幕長寬比 — 大型場地通常是超寬螢幕，而非 16:9。這是少數值得詢問使用者的事項之一。
• 保留簡報者走道 — 將關鍵資訊避開畫面下方三分之一；在超寬螢幕上，將主體推向兩側，保持中間開闊（講者站在那裡）。
• 斷言膠囊 — 每頁在固定位置放一句結論（「所以呢？」）；細節頁面尤其需要一個地方說明要得出什麼結論。
• 雙語引用 — 本地標題（英文標題）；人名在上方使用本地化名稱，下方以較小/較淡的字體顯示原文；僅有事實，沒有形容詞。

8. 工作流程（一句話輸入 → 一份簡報輸出）

1. 規劃 — 撰寫 plan.md：每頁一行，包含 role · density · device · exact text · style_slug，並在最上方加上 language: 行。投影片上的文字預設使用使用者正在使用的語言 — 中文對話產生中文簡報，除非使用者另有要求（示範簡報為英文並不代表英文是預設語言）。這是判斷日誌（無法截圖的部分）。首先決定整份簡報的材質。
2. 生成 — 使用代理的圖片工具或 scripts/gen_image.py，為每頁生成一張圖片存入 slides/NN.jpg。使用確定性的檔案名稱；可以單獨重新產生某一頁。在使用者的專案目錄中工作；透過完整路徑來呼叫儲存庫或技能安裝目錄下的輔助腳本（gen_image.py 先從目前目錄讀取 .env，如果沒有，則從腳本旁邊的儲存庫根目錄讀取）。
3. 品質檢查 — 逐字校對每個標題的字元是否與 plan.md 相符，確認沒有虛構字元，也沒有跨頁矛盾，並檢查沒有任何重要內容位於組裝時將被裁切的上下約 8% 區域內。然後進行風格檢查：將你的頁面與 styles/<slug>/samples/01.jpg 並列 — 同一世界嗎？一個帶有該材質紋理在背後的商業模板失敗；請以逐字貼上的 SURFACE 重新生成。這個關卡是品質的來源。
4. 組裝，然後檢查簡報 — 執行 python3 scripts/assemble_pptx.py slides/ deck.pptx（16:9 全出血；非 16:9 的圖片會以中心裁切填滿）。打開結果：檢查頁面順序、裁切、有沒有遺失內容。必要時重新生成並重新組裝單頁。輸出是一個以圖像為基礎的 .pptx：非常適合簡報，但文字不可編輯 — 修正錯字需要重新生成那一頁。PDF / Keynote / Google Slides 可以匯入相同的圖片。

參見 examples/relayboard/ 以取得一份完整的十頁工作範例及其判斷日誌。可選的深入探討內容放在 references/ 中（設計法則、骨架庫、視覺模式、簡報技巧 — 目前為中文；當你需要基礎推論時請載入它們）。

交付自我檢查

• 每頁的密度已設定？證據頁面詳細，密集區塊結束在喘氣的頁面上？
• 每頁：有一個一看就懂的裝置（或刻意「無裝置」），且只有一個主要裝置？
• 整份簡報的材質統一？風格已解析為真實的 slug？
• 所有事實主張都可追溯到使用者的輸入？沒有虛構的數字/引述/價格/日期？
• 每個提示詞都遵守四條硬性規則？主要內容避開了裁切區域？
• 重複出現的角色/概念在每個提示詞中的描述完全相同？
• 生成後逐字校對？已組裝並開啟 .pptx 檔案？