JuneYaooo/gpt-image2-ppt 技能

gpt-image2-ppt -- 用 gpt-image-2 生成 PPT

把一份 markdown 大綱（或 slides_plan.json）+ 一種視覺風格，直接餵給 OpenAI 官方 Images API（gpt-image-2），逐頁出圖，最後打包成 16:9 .pptx。

可用風格

風格 ID	一句話定位	適用場景
gradient-glass	Apple Vision OS / Spatial Glass	AI 產品發布、技術分享、創意提案
clean-tech-blue	Stripe / Linear 級藍白	融資路演、商業計畫書、企業策略
vector-illustration	復古向量插畫 + 黑描邊	教育訓練、品牌故事、社群分享
editorial-mono	Kinfolk / Monocle 編輯設計	品牌發布、文化訪談、讀書分享
dark-aurora	Linear / Vercel 深色霓虹	AI 產品、開發者工具、技術分享
risograph	Riso 雙套色印刷 + 網點紋理	創意工作室、文創品牌、獨立 zine
japanese-wabi	無印 / 原研哉式侘寂	茶道、生活方式、奢侈品、文化講座
swiss-grid	Bauhaus / Vignelli 國際主義網格	學術報告、博物館展陳、嚴肅匯報
hand-sketch	Sketchnote / 白板手繪	工作坊、產品 brainstorming、訓練
y2k-chrome	Y2K 千禧液態金屬 + 蝴蝶貼紙	潮牌、文娛、品牌聯名、Z 世代行銷
abstract-art-showcase	黑白極簡、藝術展覽感、超大字體和抽象畫面並置	藝術策展、作品集、品牌調性展示
coal-industry-business-company-profile	工業棕黑、粗重標題、結構線和硬朗圖示	能源、製造業、重資產公司介紹
college-candy-aesthetics-infographics	糖果色、校園感、圓潤資訊圖和輕快裝飾	教育、校園活動、輕量數據科普
creative-agency	創意機構氣質、強視覺拼貼、鮮明版式節奏	Agency 提案、品牌方案、創意匯報
culinary-innovation	餐飲創新感、食材攝影、暖色塊和雜誌式排版	餐飲品牌、食品創新、菜單/新品發布
data-science-consulting	數據諮詢藍灰、模組化佈局、圖表和技術感資訊層級	數據分析、AI 諮詢、企業數位化
mindfulness-in-the-classroom-breathing-techniques	柔和心理健康配色、留白、圓角塊和安靜插畫感	心理健康、課堂活動、呼吸訓練課程
mind-maps-workshop-professional	專業工作坊風、心智圖節點、清晰流程結構	訓練工作坊、方法論、團隊共創
meeting-agenda	會議議程感、乾淨網格、強資訊分組和商務標題	例會、專案同步、管理層匯報
investment-company-business-plan	投資機構質感、深淺對比、穩重商務版式	投資計劃、基金介紹、商業計畫書
indigenous-cultures	文化紋樣、自然色、手工質感和敘事型構圖	文化課程、歷史主題、公益教育
health-disparities-and-social-determinants-of-health-doctor-of-philosophy-phd-in-health-behavior-and-health-education	公共健康學術風、理性網格、柔和醫療色和論文感層級	醫學論文答辯、公共健康報告、教育研究
geometric-duotone-thesis	雙色幾何、論文答辯感、斜切圖形和強標題	學術答辯、研究報告、章節型內容
geometric-clinical-case	幾何醫療風、冷靜配色、病例卡片和清晰分欄	臨床病例、醫療訓練、診療匯報
geometric-business	商務幾何塊、穩健藍綠調、簡潔圖表語言	商業計劃、團隊匯報、產品策略
formal-lavender-portfolio	淡紫正式感、作品集留白、優雅細線和柔和版式	個人作品集、設計簡歷、專業展示
flowery	花卉裝飾、柔和色塊、浪漫但有秩序的排版	生活方式、女性品牌、活動介紹
first-impressions	第一印象主題、強封面視覺、人物/標題的戲劇化關係	面試訓練、個人品牌、溝通課程
final-year-project-thesis-defense	畢業設計答辯、學院派網格、清晰章節與數據頁	畢業答辯、專案結題、研究展示
fashion-business-consulting-toolkit-aesthetic	時尚諮詢感、高級拼貼、雜誌排版和中性色	時尚商業、品牌諮詢、趨勢報告
economic-impact-of-coronavirus	經濟影響報告風、嚴肅資訊圖、冷靜色彩和數據敘事	宏觀經濟、政策分析、風險報告
eco-green-business-plan	鼠尾草綠、自然材質攝影、環保商務與極簡分屏	可持續商業、環保品牌、健康生活方式

所有可用風格都統一放在 styles/ 下並按來源分組，使用方式完全相同：initial/ 收錄初始 10 套，featured/ 收錄精選 22 套，xiamulingzi/ 收錄設計師 @夏目玲子 提供的 233 套。目錄索引見 styles/README.md；精選風格封面展示見 docs/distilled-styles.md。

風格選擇原則：先根據內容場景在 styles/ 裡選擇最貼近的一套。技術類可優先看 dark-aurora / gradient-glass / data-science-consulting，商務類可優先看 clean-tech-blue / editorial-mono / eco-green-business-plan / investment-company-business-plan，文化生活類可優先看 japanese-wabi / vector-illustration / culinary-innovation / flowery，學術類可優先看 swiss-grid / geometric-duotone-thesis / final-year-project-thesis-defense，工作坊與訓練類可優先看 hand-sketch / mind-maps-workshop-professional / mindfulness-in-the-classroom-breathing-techniques。

場景 recipes（可選起步模板）

examples/ 不是新的 skill，也不是運行時必須輸入；它是當前 skill 的場景起步模板庫，用來在使用者只給出模糊需求時，幫助 agent 更快寫出第一版 slides_plan.md。

觸發規則：

• 使用者已經提供完整大綱 / 完整 slides_plan.md / 完整 slides_plan.json 時，不要套 recipe，直接按使用者內容走生成流程。
• 使用者只說「做一份產品發布 PPT / 融資路演 / 週報 / 課程課件 / 論文答辯 / 讀書分享」等常見場景，且沒有給清晰頁結構時，先查看 examples/ 是否有匹配 recipe。
• recipe 只作為結構參考：讀取 examples/<id>/recipe.md 了解場景、推薦風格和注意事項，再參考 examples/<id>/slides_plan.md 的頁序結構，改寫成使用者自己的主題與內容。
• 不要把範例裡的虛構產品、公司、專案、數據直接當成使用者成品；必須替換為使用者提供的資訊，或明確標註為佔位內容並等待使用者確認。
• 如果使用者給了真實圖片、logo、截圖、論文圖表或產品 UI，仍按「外部真實圖片貼入」規則處理；recipe 只負責內容結構，不替代素材保真流程。

當前內建 recipes：

使用者場景	recipe 目錄	推薦風格
產品發布、新功能發布、AI 產品介紹	examples/product-launch/	gradient-glass
融資路演、商業計畫書、投資人匯報	examples/investor-pitch/	clean-tech-blue
項目週報、月報、例會同步	examples/weekly-report/	meeting-agenda
課程課件、訓練、知識科普	examples/courseware/	vector-illustration
論文答辯、畢設答辯、結題展示	examples/thesis-defense/	final-year-project-thesis-defense
讀書分享、文化訪談、觀點分享	examples/book-sharing/	editorial-mono

使用方式：

1. 判斷使用者需求是否命中某個 recipe。
2. 讀取對應 recipe.md 和 slides_plan.md。
3. 基於使用者主題改寫一份新的 slides_plan.md，不要直接改 recipe 源檔案。
4. 與使用者確認頁數、每頁標題和關鍵內容。
5. 使用者確認後再執行 md_to_plan.py 轉 json，並繼續下面的指定風格或模板克隆流程。

內置風格的 layout bank sidecar（唯一運行格式）

內置風格採用「MD 給人看，JSON 給機器用」的雙檔案結構：

styles/<collection>/<style-id>.md            # 風格說明、設計令牌、基礎提示詞
styles/<collection>/<style-id>.layouts.json  # 必需；每頁 layout bank，供自動分配頁面形態

generate_ppt.py 會把同名 .layouts.json 作為無 reference image 的 RuntimeProfile 使用：透過 assign_layouts() 分配不同 layout，把 visual_signature / content_capacity / best_for / avoid_for / variation_tags 寫入 prompt，並把命中的 layout 精簡資訊寫入 metadata.json。

當前所有 styles/**/*.md 都必須配套同目錄、同名的 .layouts.json。只有 Markdown、缺少 sidecar 的舊風格會在出圖前直接報錯，不再靜默走舊 Prompt；先把它遷移為配對格式。以後蒸餾公開模板或新增內置風格時，必須同時產出 JSON sidecar；不要把多頁 layout 只壓縮進單個 MD 的「佈局系統」文字段落。

統一 RuntimeProfile 運行內核

嚴格模板克隆和結構化 style sidecar 都先編譯成同一種 RuntimeProfile，再統一經過 assign_layouts()、頁面 Profile 附著、prompt 編譯和 metadata 記錄。入口配接器只保留必要差異：

• template-clone：來自 --template-profile 或模板 vision 分析；layout 可攜帶 reference_image，只有 --template-strict 才實際傳入生圖。
• distilled-style：來自 <style>.md + <style>.layouts.json；使用內容路由和多佈局，不依賴原模板圖片。

RuntimeProfile 統一記錄 source_kind、固定的 prompt_strategy=layout-fields、layouts 和 capabilities（routing / evidence / reference / portability）。優先級固定為：有效模板 Profile > style RuntimeProfile；模板分析沒有 layouts 時必須真正回退到結構化 style，而不是只列印提示。運行時不再包含 legacy-freeform 或 synthetic layout 分支。

模板克隆模式

直接給 skill 一個 .pptx 模板，後續所有頁都仿這個模板。

# 一行：自動渲染 + 模板分析 + 出圖。需本機有可用 PPTX 渲染後端
python3 scripts/generate_ppt.py \
  --plan slides_plan.json \
  --template-pptx ./company-template.pptx \
  --template-strict

--template-strict 表示每頁都把模板對應頁作為 image reference 餵給 gpt-image-2，仿真度最高。

模板渲染：本機不需要操作 PowerPoint

skill 自帶 render_template.py，把 .pptx 自動渲染成每頁 PNG，存到 <cwd>/template_renders/<stem>/page-NN.png。

Agent 前置檢查（模板克隆時必須做）

在跑任何 --template-pptx 命令之前，你必須先檢查本機是否有可用 PPTX 渲染後端。

檢查方式：

• 首選：在 skill 目錄運行 python3 scripts/render_template.py --check。它會驗證後端是否真的可執行，而不是只看路徑是否存在。
• macOS：優先檢查 /Applications/Keynote.app 且 AppleScript 可執行；否則檢查 libreoffice --version || soffice --version
• Windows：優先檢查本機 PowerPoint COM 可啟動；否則檢查 libreoffice --version / soffice --version
• Linux / 相容層：檢查 libreoffice --version || soffice --version，不要只用 which

注意：鴻蒙 / Termux / 容器 / 特殊架構環境可能看起來像 Linux，但不能假設 Linux aarch64 的 LibreOffice 二進位檔可運行；必須以 render_template.py --check 或 soffice --version 的實際執行結果為準。不要把 aspose-slides 當預設兜底，它在很多行動/特殊 Python 環境沒有可安裝 wheel。

如果都沒有可用後端，先告知使用者模板渲染需要安裝可執行的 LibreOffice，或讓使用者在桌面端手動把模板每頁匯出為 page-01.png、page-02.png 後透過 --template-images 傳入。可選安裝命令：

平台	安裝命令
Windows	winget install LibreOffice.LibreOffice
macOS	brew install --cask libreoffice
Linux (Debian/Ubuntu)	sudo apt-get install -y libreoffice
Linux (Fedora/RHEL)	sudo dnf install -y libreoffice
Linux (Arch)	sudo pacman -S --noconfirm libreoffice-fresh

裝完再次檢查，確認存在可用渲染後端再繼續後續流程。

注意：Windows 上 winget 是 Win10/11 自帶，會彈 UAC 確認框，需要使用者點確認；macOS 上 brew 需要先安裝 Homebrew。

render_template.py 的渲染後端按優先級自動挑：

1. Windows：PowerPoint COM（本機有 Office 時優先，直出 PNG，跳過 PDF 步驟）> LibreOffice
2. macOS：Keynote AppleScript（本機有 Keynote 時優先，直出 PNG）> LibreOffice
3. Linux / 相容層：透過 --version 探測確認可運行的 LibreOffice / soffice 命令
4. PDF -> PNG 走 pymupdf（已在 requirements）；沒裝就用 pdf2image + poppler

跑 generate_ppt.py --template-pptx ... 時如果省略 --template-images 會自動調一次渲染；也可以手動先跑一次：

python3 scripts/render_template.py company-template.pptx
# -> <cwd>/template_renders/company_template/page-01.png ... page-NN.png

仿模板的兩層快取

資料	路徑	用途
模板每頁 PNG	<cwd>/template_renders/<stem>/page-NN.png	本機渲染後端一次渲染長期複用
模板風格分析	<cwd>/template_cache/<sha256>.json 或手寫 template_profile.json	多模態 agent 自己看圖生成；純文字 agent 才需要外掛 vision
生成產物	<cwd>/outputs/<timestamp>/	每次新跑都新目錄

三者都在呼叫者 cwd 下，與專案自然同進退；建議把 template_renders/、template_cache/、outputs/ 加進專案的 .gitignore。

模板看圖分析（讓 agent 自己判斷要不要配 VISION_*）：

• 當前 code agent 本身是多模態模型（例如 Claude Code 的多模態 Claude、Codex 的多模態 GPT）：不需要額外配置 VISION_*。agent 直接讀取 template_renders/<stem>/page-*.png，按 template_analyzer.py 的 TemplateProfile 結構生成 template_profile.json，再用 --template-profile template_profile.json 傳給 generate_ppt.py。如果要配合 --template-strict，每個 layout 裡要寫 reference_image（模板 PNG 的絕對路徑或可存取路徑）。
• 當前 code agent 是純文字模型（例如只接入 DeepSeek 文字模型）：它看不了模板截圖，需要額外配置 VISION_BASE_URL / VISION_API_KEY / VISION_MODEL_NAME，讓 template_analyzer.py 調一個獨立的 OpenAI 相容多模態端點做模板分析。

vision 分析與圖片生成的 gpt-image-2 永遠解耦——換 vision provider 不影響出圖路徑。

安裝

git clone [email protected]:JuneYaooo/gpt-image2-ppt-skills.git
cd gpt-image2-ppt-skills
bash install_as_skill.sh --target claude   # Claude Code
# 或
bash install_as_skill.sh --target codex    # Codex
# API 直連所需金鑰優先透過 agent 配置 / 系統環境變數注入

環境變數注入（API 直連時）

不要把本 skill 的金鑰寫進呼叫者業務專案根目錄的 .env，也不要為了出圖去讀取使用者專案裡的通用 .env。環境變數建議按 agent 框架的標準方式注入：

• 通用 / CI / 伺服器：用系統環境變數、Docker Compose environment / env_file、Kubernetes Secret、CI Secret 等注入。
• Claude Code：用使用者級 ~/.claude/settings.json 或專案級 .claude/settings.local.json 注入環境變數；命令列環境變數優先權最高。
• OpenClaw / 自訂 Agent：用框架配置裡的 apiKey / env reference 引用系統環境變數，避免把 key 明文寫進專案配置。
• 本地 standalone CLI fallback：可以設定 GPT_IMAGE2_PPT_ENV=/path/to/private.env，或使用 skill 安裝目錄下的 .env；這只是備用方式，不是業務專案 .env。

API 直連需要這些變數：

OPENAI_BASE_URL=https://api.openai.com    # 或任意 OpenAI 相容中繼站
OPENAI_API_KEY=sk-...
GPT_IMAGE_MODEL_NAME=gpt-image-2
GPT_IMAGE_QUALITY=high                     # low / medium / high / auto

# 可選：模板克隆模式的 vision 分析 backend。
# 多模態 agent / 原生 Codex 可自己看圖生成 --template-profile，不需要下面這組。
# 只有純文字 agent（如 DeepSeek 文字模型）才需要外掛下面這組。
# 不內建預設 endpoint，請填你自己信任的服務，否則就別填。
# VISION_BASE_URL=https://your-openai-compatible-relay.example.com/v1
# VISION_API_KEY=sk-...
# VISION_MODEL_NAME=gemini-3.1-pro-preview   # 或 gpt-4o / claude-3.5-sonnet 等任意多模態 SKU

配置優先級固定為：當前執行緒環境變數 > 平台注入的 gpt-image2-ppt_* 變數 > GPT_IMAGE2_PPT_ENV / skill 目錄下的 .env；JULING_GPT_IMAGE2_* 只作為沒有對應 OPENAI_* 配置時的相容 fallback，不會覆蓋顯式配置。

安全提示：腳本只讀取當前執行緒環境、平台注入的 gpt-image2-ppt_* 變數、顯式 GPT_IMAGE2_PPT_ENV，以及 skill 安裝目錄下的 .env fallback。腳本不會向上遞迴讀取呼叫者專案目錄裡的 .env，避免誤吃業務專案金鑰。python3 scripts/render_template.py --check 會執行一個最小真實轉換來驗證回渲染後端。

如果你就是 Codex agent（原生 image_generation 出圖 — 推薦）

如果你自己就是 Codex（正在運行本 skill 的 agent 就是 Codex CLI / Codex TUI），並且當前環境提供 image_generation tool 和 ChatGPT 登入態，此時不要用 generate_ppt.py 或 --backend codex 負責出圖，直接用原生工具生成圖片，最後只複用本倉庫的 md 轉換 / PPTX 打包邏輯即可。

關鍵邊界：Python 腳本運行在子行程裡，拿不到當前 agent 會話裡的原生 tool。generate_ppt.py --backend codex 能做的只有再啟動一個 codex exec 子行程，讓另一個 Codex 去出圖；它不是「複用當前 Codex 的 image_generation tool」。所以當前 agent 已經能原生出圖時，出圖動作必須由 agent 本身完成，而不是交給 generate_ppt.py。

如何判斷

你能存取 image_generation tool，並且不需要手動配 OPENAI_API_KEY 就能出圖——滿足這兩個條件就走原生路徑。若當前 Codex 會話沒有這個 tool，就按普通 agent 處理：走 API 直連、--backend codex 備用後端，或讓使用者補齊環境。

出圖流程（Codex 原生路徑）

1. 準備 slides 資料

如果還沒有 slides_plan.json，先按下面「生成流程」第 2-3 步寫 slides_plan.md → python3 scripts/md_to_plan.py ... 轉 json。

2. 用統一執行時期準備 prompt

不要手工復刻 generate_prompt()。運行 --prepare-only，讓 API 直連和 Codex 原生路徑共享同一個 RuntimeProfile、layout routing 和 prompt compiler：

python3 scripts/generate_ppt.py \
  --plan slides_plan.json \
  --style styles/<collection>/<id>.md \
  --prepare-only \
  --output outputs/<timestamp>

該命令不呼叫圖片 API，也不打包 PPTX；它會生成 prompts.json、逐頁 prompt 文字和 metadata.json。只做單頁冒煙時同時傳 --slides 1。

3. 讀取每頁編譯結果

從 outputs/<timestamp>/prompts.json 讀取每頁 prompt、reference_image、asset_reference_image 和 layout_id。不要根據 Markdown 重新拼一份 Prompt，否則會繞過結構化 layout bank。

4. 調 image_generation tool 出圖

對每頁調你的 image_generation tool：

• prompt: prompts.json 中該頁已經編譯好的完整 prompt
• output_format: png
• 如果記錄了 reference_image / asset_reference_image，按原順序作為圖片 reference 傳入
• 將回傳的圖片儲存到 outputs/<timestamp>/images/slide-NN.png（NN 為兩位頁碼）

可以並發（建議 ≤4 並發，避免限流）。

5. 打包 PPTX

如果本 deck 沒有外部真實圖片物件，可以用下面的簡易整頁 PNG 打包。如果任一頁有 external_image / image_overlay / external_image_placeholder 且指向真實圖片，不能用這個簡易打包片段，否則真實圖片會被合進整頁背景 PNG，使用者無法在 PowerPoint 裡單獨選中拖動。此時必須走 generate_ppt.py 的標準打包邏輯，或在已有 session 中呼叫 generate_pptx(..., metadata=metadata)，讓真實圖片作為獨立 picture object 疊在背景上。

python3 -c "
from pptx import Presentation
from pptx.util import Inches
prs = Presentation()
prs.slide_width = Inches(13.333)
prs.slide_height = Inches(7.5)
blank = prs.slide_layouts[6]
import os, glob
for p in sorted(glob.glob('outputs/<timestamp>/images/slide-*.png')):
    slide = prs.slides.add_slide(blank)
    slide.shapes.add_picture(p, 0, 0, width=prs.slide_width, height=prs.slide_height)
prs.save('outputs/<timestamp>/<title>.pptx')
print('done')
"

外部真實圖片頁的正確 PPTX 結構應是：

• 第 1 層：images/slide-XX.png 作為整頁背景圖（包含模型生成的背景和文字）。
• 第 2 層：source 指向的真實圖片作為獨立 PPT picture object，按 slide_spec 座標貼在背景上，可在 PowerPoint 裡選中、拖動、縮放。

模板克隆模式（Codex 原生路徑）

你自己就是多模態 agent——直接 Read 模板每頁 PNG 抽取視覺風格，寫成 template_profile.json（schema 見 template_analyzer.py 裡的 TemplateProfile，每個 layout 寫上 reference_image），再用 --template-profile template_profile.json --template-strict --prepare-only 編譯每頁 Prompt 和 reference；不要手工選擇另一套 Prompt 拼接邏輯。

不需要配 VISION_*——你就是 vision。

與下面「--backend codex」的區別

	原生路徑（本節）	--backend codex
適用場景	你就是 Codex agent	你是 Claude Code / 其他 agent，借用本機 codex CLI
呼叫方式	直接調 image_generation tool	spawn codex exec --full-auto 子行程
出圖層數	1