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/ 下，使用方式完全相同。需要查看风格封面展示时，读取 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。

模板克隆模式

直接给 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 渲染后端。

检查方式：

macOS：优先检查 /Applications/Keynote.app，否则检查 which libreoffice || which soffice
Windows：优先检查本机 PowerPoint；否则 where libreoffice 2>nul & where soffice 2>nul
Linux：which libreoffice || which soffice

如果都没有可用后端，先告知用户模板渲染需要安装 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 的渲染后端按优先级自动挑：

Windows：PowerPoint COM（本机有 Office 时优先，直出 PNG，跳过 PDF 步骤）> LibreOffice
macOS：Keynote AppleScript（本机有 Keynote 时优先，直出 PNG）> LibreOffice
Linux：LibreOffice / soffice 命令
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`	LibreOffice 一次渲染长期复用
模板风格分析	`<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 git@github.com: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 fallback。脚本不会向上递归读取调用者项目目录里的 .env，避免误吃业务项目密钥。

如果你就是 Codex agent（原生 image_generation 出图 — 推荐）

如果你自己就是 Codex（正在运行本 skill 的 agent 就是 Codex CLI / Codex TUI），并且当前环境提供 image_generation tool 和 ChatGPT 登录态，此时不要用 generate_ppt.py 或 --backend codex 负责出图，直接用原生工具生成图片，最后只复用本仓库的 md 转换 / PPTX 打包逻辑即可。

如何判断

你能访问 image_generation tool，并且不需要手动配 OPENAI_API_KEY 就能出图——满足这两个条件就走原生路径。若当前 Codex 会话没有这个 tool，就按普通 agent 处理：走 API 直连、--backend codex 备用后端，或让用户补齐环境。

出图流程（Codex 原生路径）

1. 准备 slides 数据

如果还没有 slides_plan.json，先按下面「生成流程」第 2-3 步写 slides_plan.md →

gpt-image2-ppt