codex-ppt

Codex PPT

概述

此技能可從原始素材建立以圖片為基礎的 PowerPoint 簡報。每張投影片都是一張完整的 16:9 生成圖片。最終圖片會透過 scripts/assemble_ppt.py 組合成 .pptx 檔案。

當使用者想要一份視覺統一的簡報，且能接受全投影片圖片頁面時使用。請勿在每個文字框、圖表或形狀都必須保持可獨立編輯的情況下使用。

優先使用內建的圖片生成/編輯工具。僅在內建後端不可用、缺乏所需功能，或使用者明確要求 API/CLI 模式時，才使用 scripts/image_gen.py。

嚴格限制

• 在每個階段開始前，請先閱讀相關的 Reference Map 檔案。此檔案是編排合約；詳細規則位於 docs/ 中，工作提示則位於 prompts/ 中。
• 尊重核准關卡。在 docs/workflow-gates-and-progress.md 中規定的核准完成之前，請勿建立最終的 deck_spec.json、speech.md、提示作業、投影片圖片或 .pptx。
• 在使用者核准樣本投影片並授權完整簡報生成後，只要子代理可用，每個剩餘的投影片圖片作業都必須分派給投影片子代理。
• 主代理負責編排、提示作業、狀態記錄、品質檢查、講者備註和組裝。請勿在子代理可用時，默默地以順序生產取代它們。
• 每張最終的 origin_image/slide_XX.png 必須由選定的圖片後端（內建圖片生成/編輯工具或 scripts/image_gen.py）生成。
• 本機繪圖、Pillow、SVG、HTML/CSS/Canvas 截圖、python-pptx/PptxGenJS 版面配置以及手動疊加都屬於失敗模式，而非備用方案。
• 選定的圖片後端在後端確認後必須保持固定。請勿讓子代理為了方便而切換後端。
• 樣本核准後，記錄核准樣本的生成方式，並將該確切方法傳遞給每個投影片子代理。
• 投影片分派和結果狀態必須透過隨附的腳本記錄。僅靠聊天訊息無法構成投影片已分派或完成。
• 如果所需的子代理、圖片後端或必要圖片路徑不可用，請停止並回報阻礙因素，附上投影片 ID 和證據。請勿建立品質較低的替代品。

可見進度

對於非簡單的簡報，請保持一個使用者可見的檢查清單，並包含一個進行中的步驟。標準的完成證據位於 docs/workflow-gates-and-progress.md。

預設的可見步驟：

1. 準備原始素材、大綱、風格和後端決策。
2. 生成並核准一張樣本投影片。
3. 準備投影片作業和投影片狀態。
4. 分派投影片子代理。
5. 記錄生成的投影片結果。
6. 品質檢查、修復、備註和 PPT 組裝。

請勿僅憑聊天內容就將步驟標記為完成；請使用實際檔案或腳本記錄的狀態。

預設工作流程

1. 理解原始內容。

   • 識別主題、受眾、目標、頁數、風格/品牌限制，以及要包含或排除的章節。
   • 如果未指定頁數，請選擇一個實用的數字。典型的簡報為 8-12 張投影片。

2. 規劃簡報大綱。

   • 在撰寫或更新 outline.md 之前，請先閱讀 docs/workflow-gates-and-progress.md 和 docs/outline-style-and-sample.md。
   • 草擬投影片角色和所需的原始圖片。要求確認，然後在風格、後端、樣本或下游產物獲得核准前停止。

3. 確認統一的視覺風格。

   • 在提供風格選項或使用 references/ 中的檔案之前，請先閱讀 docs/outline-style-and-sample.md。
   • 提供 2-3 個具體的風格方向，推薦其中一個，等待確認，然後保持一個視覺識別，同時根據頁面角色變化版面配置。

4. 確認圖片後端。

   • 在生成任何投影片圖片之前，請先閱讀 docs/backend-selection.md。
   • 檢查內建圖片工具是否可呼叫，說明檢查了什麼，命名後端，解釋備用狀態，並等待確認。
   • 如果選擇了 CLI/API 備用模式，請閱讀 docs/cli-api-fallback.md。僅在設定錯誤或明確要求 API 設定時，才閱讀 docs/image-model-configuration.md。

5. 生成一張樣本投影片以供核准。

   • 在生成或核准樣本投影片之前，請先閱讀 docs/outline-style-and-sample.md。
   • 在大綱、風格和後端確認後，僅生成一張具代表性的樣本。在獲得核准前，請勿生成完整簡報。
   • 核准後，將 sample_generation_method 記錄在 deck_spec.json 中，以便作業和子代理繼承相同的路徑。

6. 建立專案目錄。

   • 在初始化資料夾或組裝檔案之前，請先閱讀 docs/project-assembly-and-reporting.md。
   • 如果未指定目的地，請使用目前工作目錄或原始檔案目錄。

7. 準備使用者提供的素材。

   • 在使用論文圖表、圖表、螢幕截圖、標誌或其他必要素材之前，請先閱讀 docs/user-supplied-assets.md。
   • 將必要素材視為嚴格輸入，並在生成前確認投影片與素材的對應關係。

8. 生成所有投影片圖片。

   • 在完整簡報圖片生成之前，請先閱讀 docs/slide-generation-and-subagents.md。
   • 使用 scripts/prepare_slide_prompts.py 或儲存的 prompts/slide_XX.json 檔案為每張投影片建立作業。
   • 每張最終圖片必須來自選定的後端，並透過隨附的狀態腳本記錄。

9. 分派投影片子代理。

   • 在分派或取代投影片工作者之前，請先閱讀 docs/slide-generation-and-subagents.md 和 prompts/slide-worker.md。
   • 盡可能為每個剩餘的投影片作業使用一個子代理。如果無法產生所需的子代理，請停止並回報阻礙因素，除非使用者變更工作流程。

10. 品質檢查與修復。

    • 在品質檢查或組裝之前，請先閱讀 docs/project-assembly-and-reporting.md。
    • 在組裝前檢查每張投影片：文字、大綱匹配、截斷、風格、不必要的頁碼、重疊和必要素材。
    • 對於嚴重失敗，使用更嚴格的提示重新生成。對於局部問題，在後端支援編輯時使用後端編輯功能。
    • 對於 CLI/API 備用模式的編輯指令，請閱讀 docs/cli-api-fallback.md。僅在驗證編輯輸出後才取代最終投影片。

11. 撰寫講者備註並組裝 PPT。

    • 在撰寫 speech.md 或執行組裝之前，請先閱讀 docs/project-assembly-and-reporting.md。
    • 確保 outline.md 反映最終確認的簡報大綱。使用對應到 Slide N 的 speech.md 標題。
    • 在組裝前，確保 slide_jobs.json 顯示生成的投影片為 recorded，核准的樣本為 accepted。如果任何投影片為 pending、dispatched 或 blocked，請停止。

12. 報告結果。

    • 使用 docs/project-assembly-and-reporting.md 中的最終報告檢查清單。
    • 包含路徑、投影片數量、使用的後端、記錄結果狀態，以及任何限制或阻礙因素。

13. 儲存可重複使用的風格。

    • 如果要求儲存目前的簡報風格或提供的圖片/PDF/PPT/PPTX 風格，請閱讀 docs/style-library.md。
    • 如果最終簡報使用了自訂或改編的風格，請主動在最終報告中提議儲存，依據 docs/project-assembly-and-reporting.md。使用者自訂風格儲存在 ${CODEX_PPT_HOME:-~/.codex-ppt-skill}/references/ 中，位於技能安裝目錄之外。

子代理分派

在樣本核准後，只要執行環境能夠產生子代理，投影片子代理就是強制性的。主代理準備作業並記錄狀態；每個工作者處理恰好一個 prompts/slide_XX.json 作業，並僅回傳選定的圖片路徑、後端和品質檢查備註。

使用 docs/slide-generation-and-subagents.md 進行分派、指令、結果記錄、阻礙因素和後端來源追溯。使用 prompts/slide-worker.md 作為交接範本。

子代理不得編輯 outline.md、deck_spec.json、其他投影片作業、origin_image/、speech.md 或最終的 .pptx。父代理記錄輸出並進行組裝。

驗收標準

• 輸出為有效的 .pptx。
• 每張預期的最終投影片圖片存在於 origin_image/slide_XX.png 下。
• 每張最終投影片圖片均由確認的後端生成，並透過 record_slide_result.py 記錄，但核准的樣本標記為執行狀態 accepted 者除外。
• outline.md 反映核准的簡報大綱。
• 當預期有講者備註時，speech.md 存在，且組裝會將這些備註寫入 PPT。
• slide_jobs.json 和 slide_run_state.json 反映最終狀態。
• 必要的原始圖片已明顯呈現，否則回報阻礙因素。
• 如果受阻，最終回應需指出階段、投影片 ID、證據路徑和未完成原因；請勿將簡報標記為完成。

Reference Map

• docs/workflow-gates-and-progress.md：核准關卡、進度、完成證據。
• docs/backend-selection.md：後端決策規則和確認文字。
• docs/outline-style-and-sample.md：大綱、風格、樣本規則、提示範例。
• docs/user-supplied-assets.md：必要原始素材的嚴格處理方式。
• docs/slide-generation-and-subagents.md：作業、分派、結果記錄、阻礙因素、來源追溯。
• docs/cli-api-fallback.md：備用執行環境、生成/編輯指令、圖片限制、疑難排解。
• docs/image-model-configuration.md：API 金鑰、基礎 URL、模型、.env；僅在需要設定時閱讀。
• docs/project-assembly-and-reporting.md：專案目錄、備註、組裝、最終報告、提示原則。
• prompts/slide-worker.md：投影片子代理交接範本。
• references/*.md：內建視覺風格參考。使用者自訂風格位於 ${CODEX_PPT_HOME:-~/.codex-ppt-skill}/references/，且優先於同名的內建風格。

文件與更新

有關原始碼、文件、安裝、設定和範例，請參閱 ningzimu/codex-ppt-skill。