# gpt-image2-ppt

Adopt this skill: https://proskills.md/skills/other/juneyaooo-gpt-image2-ppt-skills

Page: https://proskills.md/skills/other/juneyaooo-gpt-image2-ppt-skills
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 13012
upstream: https://github.com/juneyaooo/gpt-image2-ppt-skills/blob/HEAD/SKILL.md

````text
---
name: gpt-image2-ppt
description: Generate visually striking PPT slides via OpenAI's gpt-image-2 -- use any style in styles/<collection>/STYLE_ID.md or mimic a user-supplied .pptx template; outputs high-res slide PNGs and a 16:9 .pptx. Use when the user asks to make a presentation, slides, deck, pitch deck, investor PPT, magazine-style PPT, or 做一份 PPT / 生成幻灯片 / 用 gpt-image 生成 PPT / 按这个模板生成 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 给机器用”的双文件结构：

```text
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 模板，后续所有页都仿这个模板。

```bash
# 一行：自动渲染 + 模板分析 + 出图。需本机有可用 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 时优先，直出
````

## File: README.md
upstream: https://github.com/juneyaooo/gpt-image2-ppt-skills/blob/HEAD/README.md

````text
<div align="center">

# gpt-image2-ppt-skills

**用 OpenAI `gpt-image-2` 一键生成高审美、高完成度的 PPT。**

Claude Code / Codex / OpenClaw / Hermes 等支持 Skills 的 agent 均可原生使用。装进 agent 后，用一句自然语言生成 16:9 高清图片 + 打包好的 `.pptx`，也可以仿任意 `.pptx` 模板出全新内容。

它不走传统“模板填字”的路线，而是充分发挥 `gpt-image-2` 的审美、构图和排版能力，把每一页都当成完整视觉稿生成，力求让输出从封面到内页都足够精美、统一、可直接展示。

同时，项目对图片型 PPT 的后续编辑做了专门优化：默认模式仍以整页视觉稿保证 gpt-image-2 的构图与审美；如果用户明确要求文字、图形和素材可单独编辑，可以启用**默认关闭的可编辑模式**，把完整视觉稿重建为 PowerPoint 原生文本、基础图形、连接线和独立图片层。

[![GitHub stars](https://img.shields.io/github/stars/JuneYaooo/gpt-image2-ppt-skills?style=flat)](https://github.com/JuneYaooo/gpt-image2-ppt-skills/stargazers)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](./LICENSE)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Skill-orange.svg)](https://www.anthropic.com/claude-code)
[![gpt-image-2](https://img.shields.io/badge/OpenAI-gpt--image--2-black.svg)](https://platform.openai.com/docs/guides/images)

🌐 **English** → [docs/README.en.md](./docs/README.en.md)

</div>

---

## 🎬 效果演示：喂一张模板，仿出一套新内容

<table>
<tr>
<th width="50%">输入：任意一页参考模板（.pptx / 图片）</th>
<th width="50%">输出：本 skill 仿制 + 换内容</th>
</tr>
<tr>
<td><img src="docs/assets/template-demo-input.jpg" width="100%" alt="input template"></td>
<td><img src="docs/assets/template-demo-output.jpg" width="100%" alt="generated output"></td>
</tr>
<tr>
<td align="center"><sub>英文信息图模板（Mass Media Infographics）</sub></td>
<td align="center"><sub>同一版式 / 同一配色 / 同一插画语汇，内容换成「普通人怎么用 AI 做自媒体」</sub></td>
</tr>
</table>

---

## 🧩 可编辑模式示例（默认关闭）

可编辑模式不会限制 gpt-image-2 的初始设计：模型仍先生成包含完整文字与主视觉的成品页，再把已知文字、基础图形和复杂素材重建成 PowerPoint 对象。

<table>
<tr>
<th width="50%">原始完整视觉稿</th>
<th width="50%">可编辑 PPTX 的 Office 回渲染</th>
</tr>
<tr>
<td><img src="examples/editable-pptx/case05-summer-poster/original.png" width="100%" alt="editable mode original poster"></td>
<td><img src="examples/editable-pptx/case05-summer-poster/rendered.png" width="100%" alt="editable PPTX rendered result"></td>
</tr>
</table>

这个示例的 PPTX 实测包含 **13 个可选对象**：5 个原生文本、6 个原生 shape、1 个 clean plate，以及 1 个可移动、可缩放的毛绒角色与粽子冰淇淋独立图片层。文字和基础图形可以直接在 PowerPoint 中修改，复杂主视觉仍保留 gpt-image-2 的完整质感。

- [下载 Case 05 可编辑 PPTX](examples/editable-pptx/case05-summer-poster/editable.pptx)
- [查看完整 Case 05：原图、拆层素材、边缘检查和质量报告](examples/editable-pptx/case05-summer-poster/)

需要可编辑交付时，可以直接这样说：

> 帮我生成一份可编辑模式的 PPT。文字和基础图形要能在 PowerPoint 里直接修改，复杂主视觉要能单独移动，同时尽量保留 gpt-image-2 的完整设计感。

只有明确提出“可编辑模式”“文字可以改”“元素可以拆开”或类似要求时，Skill 才会执行对象级重建。如果不特别说明，默认仍走视觉效果优先的整页图片模式。

> ⚠️ **可编辑模式需要本机具备 PPTX 回渲染能力。** 与模板克隆模式相同，运行前必须有可执行的 Windows PowerPoint、macOS Keynote 或 LibreOffice。用户无需执行检查命令，只要像上面那样用自然语言说明需要可编辑交付；Skill 会自动检查环境，生成后把 `-editable.pptx` 回渲染到 `editable_renders/page-XX.png`，再由多模态 AI 逐页看图验收。没有可用渲染后端时，不会把未经回渲染检查的可编辑文件标记为成功。

可编辑重建采用**效果优先、生成轮次受控**的策略：允许多轮本地预检和回渲染；优先用字体、坐标、裁切等确定性修复，其次进行原像素提取与遮挡补全，只对失败的复杂图层进行 AI 重绘，只有整体构图失败时才重新生成整页。这样不会为了追求单轮而牺牲效果，也不会因为局部问题反复重做整页。

---

## 🚀 快速开始

### 1. 让 AI 安装 Skill

把下面这段话发给 Claude Code、Codex、OpenClaw、Cursor、Trae、Hermes Agent，或其他支持 Skills 的 AI 助手：

> 帮我安装 gpt-image2-ppt-skills：<br>
> https://github.com/JuneYaooo/gpt-image2-ppt-skills

AI 会根据当前环境完成安装并提示你重启。

### 2. 安装后直接说需求

**普通生成**

> 帮我做一份关于「AI 如何改变内容创作」的 6 页 PPT，先生成一页封面给我确认，整体风格要有高级科技感。

**仿模板**

> 我上传了 `company-template.pptx`，请参考它的版式、配色和视觉语言，做一份关于「年度产品战略」的 8 页 PPT。

如果手头没有现成模板，也可以打开 [SlideCraft Template Gallery](https://slidecraft-template-gallery.vercel.app)，在网页中浏览并复制喜欢的模板，再把复制的模板内容直接发给 AI 使用。

**可编辑交付**

> 帮我生成一份可编辑模式的 PPT。文字和基础图形要能直接修改，复杂主视觉要能单独移动，同时尽量保留 gpt-image-2 的完整设计感。

AI 会整理内容、先做单页视觉确认、再生成完整 PPT，并把图片、PPTX 和输出目录交给你。

---

## ✨ 能做什么

- 🎨 **在线模板画廊** — 集中展示目前收录的模板，可按场景和风格搜索、筛选，复制喜欢的模板 Prompt 后直接交给 AI 使用
- 🧬 **模板质量验证** — 候选模板会实际生成封面、章节、内容和数据页，检查整套一致性、可读性和布局效果后再入库
- 🧭 **Prompt Recipes 示例库** — `examples/` 提供产品发布、融资路演、周报、课程课件、论文答辩、读书分享等常见场景的 `slides_plan.md` 起步模板
- 🪄 **模板克隆模式** — 丢一个 `.pptx` 进去，AI 会参考原模板的版式、配色和插画语汇，像上面那张图一样换成新内容
- 🎯 **自然语言精准编辑** — 直接说“改第 3 页副标题”“删掉页脚”“把三个数据换成新数字”，AI 会通过图生图只重生成目标页，尽量保持原风格和版式不变
- 🎮 **双产出** — 每页 PNG 高清原图 + 16:9 `.pptx` 直接用
- ⚡ **默认 10 路并发出图** — 10 页 ~30 秒出完
- 🧪 **先看一页再跑全量** — 默认建议先出封面给你确认，满意后再生成整套
- 🧾 **可追踪、可回滚** — 修改过哪些页、生成过哪些版本都能追踪，方便继续改
- 🖼️ **真实素材双模式** — 用户给的真实图默认保真嵌入；用户明确允许时，也可以作为参考图融合重绘
- 🧩 **可编辑模式（默认关闭）** — 用户明确要求时，把文字、基础图形、连接线和复杂主视觉拆成可单独编辑的 PowerPoint 对象

## ✅ 适合哪些用户场景

| 场景 | 适合程度 | 说明 |
| --- | --- | --- |
| 从主题生成一套新 PPT | 很适合 | 适合汇报、路演、培训、课程、产品介绍。 |
| 按公司模板仿一套新内容 | 很适合 | 上传 `.pptx` 模板，先出封面确认，再跑全量。 |
| 改标题、副标题、日期、页脚 | 很适合 | 当前最稳定的编辑场景。 |
| 更新数据卡片和关键数字 | 适合 | 可批量改，但交付前要逐项核对数字。 |
| 只改复杂多页 PPT 的某一页 | 适合 | 只更新目标页，其他页不重新生成。 |
| 密集表格、财报、法务长文 | 不建议直接承诺 | 小字和数字需要更严格人工验收。 |

## 🎨 在线模板画廊

目前收录的模板统一通过 [SlideCraft Template Gallery](https://slidecraft-template-gallery.vercel.app) 展示。你可以按场景和风格搜索、筛选，查看模板的真实生成效果；选中喜欢的模板后，复制 Prompt 并直接交给 Codex、Claude Code 或其他 AI 助手使用。

[![SlideCraft Template Gallery：浏览并复制喜欢的 PPT 模板](docs/assets/template-gallery.jpg)](https://slidecraft-template-gallery.vercel.app)

点进任意模板后，可以逐页预览整套版式，并复制模板 ID 或完整 Prompt：

[![SlideCraft Template Gallery 模板详情页：逐页预览并复制 Prompt](docs/assets/template-gallery-detail.jpg)](https://slidecraft-template-gallery.vercel.app/templates/abstract-art-showcase)

> 点击图片进入对应页面。模板会持续补充，README 不再维护容易过时的完整模板清单。

模板库不只看单张封面：新模板会用封面、章节、内容和数据等多类页面验证整套效果，并与现有版本对照。只有整体质量更好且关键页面没有明显退步时才会更新正式模板。

使用画廊风格时，复制喜欢的 Prompt 交给 AI 即可；需要沿用自己的品牌模板时，直接上传 `.pptx`，建议先生成一页确认效果，再生成整套 PPT。

---

## 🧪 修改能力测评

如果你关心“到底能不能稳定改 PPT”，先看这份面向用户的图文测评：

- **[`docs/edit_guide.md`](./docs/edit_guide.md)** — 标题替换、日期修改、删除页脚、数据更新、新增 logo、复杂多页只改一页，以及当前不足和交付前检查清单

核心结论：

| 能力 | 当前表现 |
| --- | --- |
| 改短文本 | 稳定，适合日常交付。 |
| 改多个明确元素 | 可用，建议一次说清楚“其他不要动”。 |
| 改数据页 | 可用，但必须核对数字。 |
| 加小图标 / logo | 可用；真实品牌 logo 需要提供素材。 |
| 原生 PPT 对象级编辑 | 默认模式仍是整页图片；明确启用可编辑模式后，可输出原生文本、shape、connector 和独立图片层。 |

<details>
<summary>开发者：查看内部编辑机制示意图</summary>

<img src="docs/assets/architecture_cn.jpg" width="100%" alt="system architecture">

</details>

---

## 🛠 手动安装与高级配置

普通用户优先使用上面的自然语言安装方式。需要自己管理仓库和环境时，可以手动安装：

```bash
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
```

脚本会把 skill 装到对应 agent 的目录：

- Claude Code: `~/.claude/skills/gpt-image2-ppt-skills/`
- Codex: `~/.codex/skills/gpt-image2-ppt-skills/`

<details>
<summary><strong>API 直连与密钥配置</strong></summary>

如果你走 API 直连模式，需要给 agent 注入环境变量。推荐使用当前 agent 框架的标准配置，而不是把密钥写进业务项目根目录 `.env`：

- Claude Code：用户级 `~/.claude/settings.json`，或项目级 `.claude/settings.local.json`
- OpenClaw / 自定义 Agent：用 `apiKey` / env reference 引用系统环境变量
- CI / 服务器：用系统环境变量、Docker Compose、Kubernetes Secret 或 CI Secret
- standalone CLI：可设置 `GPT_IMAGE2_PPT_ENV=/path/to/private.env`，或使用 skill 安装目录下的 `.env` fallback

```bash
# 变量名如下：
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
```

配置优先级固定为：当前进程环境变量 > 平台注入的 `gpt-image2-ppt_*` 变量 > `GPT_IMAGE2_PPT_ENV` / skill 目录下的 `.env`；`JULING_GPT_IMAGE2_*` 只作为没有对应 `OPENAI_*` 配置时的兼容 fallback，不会覆盖显式配置。

> 在 **Codex** 里如果当前 agent 自带原生图片生成能力，可以直接走 `SKILL.md` 里的原生路径，**不必配置 `OPENAI_API_KEY`**。
>
> 🔒 **不会误吃密钥**：脚本只读取当前进程环境、平台注入变量、显式 `GPT_IMAGE2_PPT_ENV` 和 skill 安装目录 `.env` fallback，**不会**向上递归读调用者项目目录的 `.env`。
>
> 🪄 模板克隆模式和可编辑模式都需要本机可执行的 PPTX 渲染后端（Windows PowerPoint / macOS Keynote / LibreOffice）。模板克隆需要先把模板转成图片供 AI 看版式；可编辑模式需要把交付文件重新转成图片供 AI 验收。`render_template.py --check` 会执行一个最小真实转换，而不是只检查程序版本；如果当前环境不支持，AI 会提示安装可用后端。模板克隆还可以改用手动导出的模板页面图片。

</details>

<details>
<summary><strong>模板克隆的 Vision 分析</strong></summary>

模板克隆模式下，skill 需要先"看懂"你的 `.pptx` 模板的视觉风格。**如果你的 AI 助手本身就是多模态的**（Claude Code 走 Claude Opus/Sonnet，Codex 走 GPT 多模态等），agent 会直接自己看图抽取风格，生成带 `reference_image` 的 `template_profile.json` 后通过 `--template-profile` 传给 CLI，**不需要额外配置**。

只有当你用的 agent 是纯文本模型时（例如只接入 DeepSeek 文本模型），才需要配下面这组环境变量，走一个独立的多模态模型来分析模板：

```bash
# 可选：模板克隆的 vision 分析
````
