AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
docs(readme): restructure landing narrative around a Product Positioning section
hugohe31630036415ff
diff --git a/README.md b/README.mdindex b5e29b1e..fa9326bd 100644--- a/README.md+++ b/README.md@@ -1,6 +1,6 @@# PPT Master — AI generates natively editable PPTX from any document-[](https://github.com/hugohe3/ppt-master/releases)+[](https://github.com/hugohe3/ppt-master/releases)[](https://opensource.org/licenses/MIT)[](https://github.com/hugohe3/ppt-master/stargazers)[](https://atomgit.com/hugohe3/ppt-master)@@ -36,9 +36,7 @@ English | [中文](./README_CN.md)</details>-> [!IMPORTANT]-> ### This is a tool, not a wishing well-> Don't expect it to hand you a finished, perfect deck in one shot. Its real value is taking most of the tedious work off your plate; the polishing that's left is yours — a natively editable deck exists precisely so you can keep working on it, not a flat image you can't touch. The cheaper the model, the more there is to do. How good the result turns out comes down to your skill with this project and with PowerPoint.+> **AI generates your deck — it doesn't fill in a template.** PPT Master is a workflow that runs inside AI IDEs (Claude Code, Cursor, VS Code + Copilot, etc.): hand the AI your PDF / DOCX / web pages, and it produces a real PowerPoint on your machine — every element editable in PowerPoint, your data stays local, no platform or model lock-in. How it works and where the limits are → [Product Positioning](#product-positioning).<p align="center"><a href="https://hugohe3.github.io/ppt-master/"><strong>Live Demo</strong></a> ·@@ -48,7 +46,6 @@ English | [中文](./README_CN.md)</p><h3 align="center">Download the new <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_attention_is_all_you_need/exports/attention_is_all_you_need_narrated.pptx">narrated <em>Attention Is All You Need</em> deck</a> — play it in PowerPoint and every slide reads itself out loud. That's just the tip of what PPT Master can do.</h3>-<h3 align="center">Of course, you can also download any of the six example decks below — opening the raw .pptx in PowerPoint is the fastest way to see this project's real capability ceiling.</h3><table><tr>@@ -88,29 +85,16 @@ English | [中文](./README_CN.md)</table><p align="center">- <sub>Generated with Claude Opus 4.7 + <code>gpt-image-2</code>. <a href="https://hugohe3.github.io/ppt-master/">Flip through all examples online →</a> · <a href="./examples/"><code>examples/</code> directory</a> · <a href="./docs/why-ppt-master.md">Why PPT Master?</a></sub>+ <sub>All examples above were generated in a single pass, with no manual polish (Claude Opus 4.7 + <code>gpt-image-2</code>). Downloading any .pptx and opening it in PowerPoint is the fastest way to feel the capability ceiling.<br/><a href="https://hugohe3.github.io/ppt-master/">Flip through all examples online →</a> · <a href="./examples/"><code>examples/</code> directory</a> · <a href="./docs/why-ppt-master.md">Why PPT Master?</a></sub></p>----Drop in your source material and get back a **real PowerPoint**: directly editable, with native slide transitions and entrance animations, speaker notes you can turn into audio narration, and the option to follow your own PPT template — a complete deck you can present as-is and keep editing. How to use each capability → [Getting Started](./docs/getting-started.md).--> **⚠️ PPT Master is a harness, not a complete agent.** `harness + model = agent` — the tool owns the workflow; the model sets the ceiling. To form a genuinely high-quality agent, use **Claude with a large context window (~1M tokens) + AI image generation (`gpt-image-2`)**. Other models can run the pipeline but cannot reach the same quality ceiling. If results disappoint, upgrade the model — don't blame the harness.--> **How it works** — PPT Master is a workflow (a "skill") that works inside AI IDEs like Claude Code, Cursor, VS Code + Copilot, or Codebuddy. You chat with the AI — "make a deck from this PDF" — and it follows the workflow to produce a real editable `.pptx` on your computer. No coding on your side; the IDE is just where the conversation happens.->-> **What you'll do**: install Python, install an AI IDE, drop in your material.--> **Why it's shaped this way** — knowing how to use Python and AI agents will matter more and more. This project is meant to show how far you can go with just those two things. There's a learning curve if you're starting cold, but it's the curve worth climbing. Making a deck is just the excuse — what I'm really pushing is Python and agents.--PPT Master is different:+Drop in your source material, and the deck you get back is **more than just editable**: it has native slide transitions and entrance animations, speaker notes that can become audio narration, and it can follow your own PPT template — a complete deck you can present as-is and keep refining. How to use each capability → [Getting Started](./docs/getting-started.md).-- **Real PowerPoint** — if a file can't be opened and edited in PowerPoint, it shouldn't be called a PPT. Every element PPT Master outputs is directly clickable and editable-- **Transparent, predictable cost** — the tool is free and open source; the only cost is your AI model usage. As AI tools move to usage-based billing, you pay exactly what you consume — no separate PPT subscription added on top-- **Data stays local** — your files shouldn't have to be uploaded to someone else's server just to make a presentation. Apart from AI model communication, the entire pipeline runs on your machine-- **No platform lock-in** — your workflow shouldn't be held hostage by any single company. Works with Claude Code, Cursor, VS Code Copilot, and more; supports Claude, GPT, Gemini, Kimi, and other models+## Product Positioning-AI presentation tools roughly fall into four categories. PPT Master only does the last one:+**If a file can't be opened and edited in PowerPoint, it shouldn't be called a PPT.** AI presentation tools roughly fall into four categories, and PPT Master only does the last one:| Category | Output | Editable element-by-element in PowerPoint? ||---|---|:---:|@@ -119,13 +103,19 @@ AI presentation tools roughly fall into four categories. PPT Master only does th| HTML presentation | Web-based deck | ❌ not a PPTX || **Native editable (PPT Master)** | **Real DrawingML shapes, text boxes, charts** | ✅ click any element to edit |----+In form, it's not a website or an app but a workflow (a "skill") that runs inside AI IDEs like Claude Code, Cursor, VS Code + Copilot, or Codebuddy: you tell the AI in the IDE's chat — "make a deck from this PDF" — and it follows the workflow to produce a genuinely editable `.pptx` on your machine. No coding on your side; you do exactly three things — install Python, install an AI IDE, drop in your material.-## The person using it matters more+This form buys three promises that other tools struggle to make at the same time:-The examples above were all made in a single pass — I didn't even refine them; spend some time polishing and it's a different story entirely. With the same PowerPoint, a designer can produce something stunning while most people only ever touch a few basic features — the difference isn't the tool, it's the person using it. If you can't get there yet, it's most likely that you haven't learned the workflow — start with [Getting Started](./docs/getting-started.md) and the example projects.+- **Transparent, predictable cost** — the tool is free and open source; the only cost is your AI model usage. You pay exactly what you consume — no separate PPT subscription added on top+- **Data stays local** — your files shouldn't have to be uploaded to someone else's server just to make a presentation. Apart from AI model communication, the entire pipeline runs on your machine+- **No platform lock-in** — your workflow shouldn't be held hostage by any single company. Works with Claude Code, Cursor, VS Code Copilot, and more; supports Claude, GPT, Gemini, Kimi, and other models-The best results do need Claude. Before you call it expensive, think about what it would cost to hire someone to produce a deck at the same level. The project also supports GPT, Gemini, Kimi, and other models — the results simply differ. Expecting top-tier output while paying the lowest possible cost was never reasonable to begin with.+> [!IMPORTANT]+> ### This is a tool, not a wishing well+> `harness + model = agent` — PPT Master only owns the workflow; the model sets the ceiling. Recommended: **Claude with a large context window (~1M tokens) + AI image generation (`gpt-image-2`)**; other models can run the pipeline, with a quality gap.+>+> And don't expect a finished, perfect deck in one shot. The tool's value is taking most of the tedious work off your plate; the polishing that's left is yours — a natively editable deck exists precisely so you can keep working on it, not a flat image you can't touch. The cheaper the model, the more there is to do; if results disappoint, upgrade the model first, then check your usage against [Getting Started](./docs/getting-started.md) and the example projects.---@@ -133,19 +123,15 @@ The best results do need Claude. Before you call it expensive, think about whatI'm a finance professional (CPA · CPV · Consulting Engineer (Investment)) who regularly reviews and edits presentation decks. I wanted AI-generated slides to remain editable in PowerPoint, not flattened into images — so I built this.+Knowing how to use Python and AI agents will matter more and more, and this project is also meant to show how far you can go with just those two things. There's a learning curve if you're starting cold, but it's the curve worth climbing — making a deck is just the excuse; what I'm really pushing is Python and agents.+---## Quick Start### 1. Prerequisites-**You only need Python.** Everything else is installed via `pip install -r requirements.txt`.--| Dependency | Required? | What it does |-|------------|:---------:|--------------|-| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **Yes** | Core runtime — the only thing you actually need to install |--> **TL;DR** — Install Python, run `pip install -r requirements.txt`, and you're ready to generate presentations.+**All you need to install is [Python](https://www.python.org/downloads/) 3.10+.** Everything else comes with one line — `pip install -r requirements.txt` — after you download the project in Step 3.<details open><summary><strong>Windows</strong> — see the dedicated step-by-step guide ⚠️</summary>@@ -154,7 +140,7 @@ Windows requires a few extra steps (PATH setup, execution policy, etc.). We wrot**📖 [Windows Installation Guide](./docs/windows-installation.md)** — from zero to a working presentation in 10 minutes.-Quick version: download Python from [python.org](https://www.python.org/downloads/) → **check "Add to PATH"** during install → `pip install -r requirements.txt` → done.+Quick version: download Python from [python.org](https://www.python.org/downloads/) → **check "Add to PATH"** during install → done; dependencies are installed in Step 3.</details><details>@@ -163,11 +149,9 @@ Quick version: download Python from [python.org](https://www.python.org/download```bash# macOSbrew install python-pip install -r requirements.txt# Ubuntu / Debiansudo apt install python3 python3-pip-pip install -r requirements.txt```</details>@@ -277,7 +261,16 @@ The AI handles everything — content analysis, visual design, SVG generation, aTwo paths for non-user images, mixable per row in the same deck:-For API-backed features, put credentials in `.env`. Clone installs can use `cp .env.example .env`; skill marketplace installs should use a persistent user config:+**A) AI generation** — `image_gen.py`. Set `IMAGE_BACKEND` plus the provider's `*_API_KEY` (`OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.), and the pipeline calls it automatically. Run `python3 skills/ppt-master/scripts/image_gen.py --list-backends` for the full backend list. `gpt-image-2` is currently the best default.++**B) Web image search** — `image_search.py`. **Zero-config works**; configure `PEXELS_API_KEY` / `PIXABAY_API_KEY` (both free) for consistently higher-quality results:++- Without keys, search uses Openverse / Wikimedia Commons only — useful as a fallback, but image quality can be uneven because many results are ordinary user uploads+- With keys, the default provider chain also appends Pexels / Pixabay, which materially improves modern stock photography, people, workplace, lifestyle, and illustration coverage+- Licensing is handled automatically: CC0, Public Domain, Pexels / Pixabay no-attribution licenses, CC BY, and CC BY-SA are all considered together, and Executor adds a small inline credit whenever the selected image requires attribution. Use `--strict-no-attribution` only when a slide cannot tolerate any credit line+- For high-impact covers, product shots, portraits, and branded scenes, prefer this order: user-provided high-resolution assets / AI generation > web search with Pexels / Pixabay keys > zero-config web search++The API keys above all live in `.env`. Clone installs can use `cp .env.example .env`; skill marketplace installs should use a persistent user config:```bashmkdir -p ~/.ppt-master@@ -286,10 +279,6 @@ cp /path/to/installed/ppt-master/.env.example ~/.ppt-master/.envPPT Master reads the current process environment first, then the first `.env` found in this order: current working directory, skill directory (e.g. `~/.agents/skills/ppt-master/.env`), clone repo root, `~/.ppt-master/.env`.-**A) AI generation** — `image_gen.py`. Set `IMAGE_BACKEND` plus the provider's `*_API_KEY` (`OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.), and the pipeline calls it automatically. Run `python3 skills/ppt-master/scripts/image_gen.py --list-backends` for the full backend list. `gpt-image-2` is currently the best default.--**B) Web image search** — `image_search.py`. **Zero-config works**, but configure `PEXELS_API_KEY` / `PIXABAY_API_KEY` (both free) for higher-quality results. Without keys, search uses Openverse / Wikimedia Commons only; this is useful as a fallback, but image quality can be uneven because many results are ordinary user uploads. With keys, the default provider chain also appends Pexels / Pixabay, which materially improves modern stock photography, people, workplace, lifestyle, and illustration coverage. The default is quality-first: CC0, Public Domain, Pexels / Pixabay no-attribution licenses, CC BY, and CC BY-SA are considered together, and Executor adds a small inline credit whenever the selected image requires attribution. Use `--strict-no-attribution` only when a slide cannot tolerate any credit line. For high-impact covers, product shots, portraits, and branded scenes, prefer this order: user-provided high-resolution assets / AI generation > web search with Pexels / Pixabay keys > zero-config web search.-> Full reference: [`image-generator.md`](./skills/ppt-master/references/image-generator.md) (AI) · [`image-searcher.md`](./skills/ppt-master/references/image-searcher.md) (web).---@@ -324,7 +313,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.## Related Tools-[cc-switch](https://github.com/farion1231/cc-switch) — a cross-platform desktop app to manage and one-click switch API providers across Claude Code, Codex, Gemini CLI and more. Handy when running PPT Master inside any of these agents.+[cc-switch](https://github.com/farion1231/cc-switch) — one-click switching of API providers across Claude Code / Codex / Gemini CLI and more.## Contact & Collaborationdiff --git a/README_CN.md b/README_CN.mdindex 46ab627a..ba2de022 100644--- a/README_CN.md+++ b/README_CN.md@@ -1,6 +1,6 @@# PPT Master — AI 生成原生可编辑 PPTX,支持任意文档输入-[](https://github.com/hugohe3/ppt-master/releases)+[](https://github.com/hugohe3/ppt-master/releases)[](https://opensource.org/licenses/MIT)[](https://github.com/hugohe3/ppt-master/stargazers)[](https://atomgit.com/hugohe3/ppt-master)@@ -36,9 +36,7 @@</details>-> [!IMPORTANT]-> ### 这是一个工具,不是一个许愿池-> 别指望一把就给你一份完美的成品 PPT。它真正的价值是帮你把大部分枯燥的活儿干掉,剩下的打磨交给你——做原生可编辑的 PPT,本就是为了让你接着改,而不是甩给你一张改不动的图。模型越便宜,要补的人工就越多。成品好不好,最终取决于你操作这个项目和 PPT 的能力。+> **AI 生成 PPT,不是 AI 套模板。** PPT Master 是一套在 AI IDE(Claude Code / Cursor / VS Code + Copilot 等)里运行的工作流:把 PDF / DOCX / 网页等材料交给 AI,它在你本机生成一份真正的 PowerPoint——每个元素都能在 PowerPoint 里点开修改,数据不出本地,不锁定任何平台和模型。工作原理与能力边界 → [产品定位](#产品定位)。<p align="center"><a href="https://hugohe3.github.io/ppt-master/"><strong>在线预览</strong></a> ·@@ -48,7 +46,6 @@</p><h3 align="center">下载这份<a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_attention_is_all_you_need/exports/attention_is_all_you_need_narrated.pptx">带音频旁白的 <em>Attention Is All You Need</em> 论文精读 deck</a>,在 PowerPoint 里直接放映,每一页都会自己"读"给你听 —— 这只是 PPT Master 能力的冰山一角。</h3>-<h3 align="center">当然,你也可以下载下面六份示例 .pptx 中的任意一份,在 PowerPoint 里打开是最快感受这个项目能力边界的方式。</h3><table><tr>@@ -88,7 +85,7 @@</table><p align="center">- <sub>生成模型:Claude Opus 4.7 + <code>gpt-image-2</code>。<a href="https://hugohe3.github.io/ppt-master/">在线翻看全部示例 →</a> · <a href="./examples/"><code>examples/</code> 目录</a> · <a href="./docs/zh/why-ppt-master.md">为什么选 PPT Master?</a></sub>+ <sub>以上示例均为一次性生成、未经精修(生成模型:Claude Opus 4.7 + <code>gpt-image-2</code>)。下载任意一份 .pptx 在 PowerPoint 里打开,是感受能力边界最快的方式。<br/><a href="https://hugohe3.github.io/ppt-master/">在线翻看全部示例 →</a> · <a href="./examples/"><code>examples/</code> 目录</a> · <a href="./docs/zh/why-ppt-master.md">为什么选 PPT Master?</a></sub></p><p align="center">@@ -97,24 +94,11 @@----丢进你的原材料,拿回的是一份**真正的 PowerPoint**:可以直接修改,有 PPT 原生的转场与入场动画,演讲者备注能合成音频旁白,还能参考你自己的 PPT 模板——一份能直接拿去讲、回头还能改的真 PPT。每项能力怎么用 → [快速入门](./docs/zh/getting-started.md)。--> **⚠️ PPT Master 是 harness,不是完整的 agent。** `harness + model = agent`——工具负责工作流,模型决定上限。要组成真正高质量的 agent,推荐组合是:**Claude 大上下文窗口(~100 万 token)+ AI 生图(`gpt-image-2`)**。其他模型能跑流程,但达不到同等质量上限。效果不理想,请先换模型,不要质疑 harness。--> **运作方式** —— PPT Master 是一套在 AI IDE(Claude Code / Cursor / VS Code + Copilot / Codebuddy 等)里运行的工作流(一个 "skill")。你在 IDE 的对话框里跟 AI 说"用这份 PDF 做一份 PPT",AI 按这套工作流在你本机生成一个真正可编辑的 `.pptx`。你不写任何代码——IDE 只是你和 AI 对话的地方。->-> **你要做的**:装 Python、装一个 AI IDE、把资料放进来。--> **为什么是这种形态** —— 未来,使用 Python 和 AI agent 的能力会越来越重要。这个项目就是要展示:仅凭这两样,你能走多远。代价是零基础上手有一段学习曲线,但走完这段,你就接上了未来。做 PPT 只是个借口——我真正想推广的是 Python 和 agent。--PPT Master 不一样:+丢进原材料,拿回的这份 PPT **不只是能改**:它有 PPT 原生的转场与入场动画,演讲者备注能直接合成音频旁白,还能参考你自己的 PPT 模板来设计——一份能直接拿去讲、回头还能改的成品。每项能力怎么用 → [快速入门](./docs/zh/getting-started.md)。-- **真正的 PPT** — 如果一个文件在 PowerPoint 里打不开、不能编辑,它就不应该被叫做 PPT。PPT Master 输出的每个元素都能直接点击修改-- **成本透明可控** — 工具免费开源,唯一成本是你自己的 AI 模型用量。当前主流 AI 工具都已转向按量计费,你用多少付多少——PPT Master 不在此之外增加任何额外订阅费用-- **数据不出本地** — 你的文件不应该为了做一份 PPT 就被上传到别人的服务器。除与 AI 模型的对话外,全流程在你的电脑上完成-- **不锁定平台** — 你的工作流不应该被任何一家公司绑架。Claude Code、Cursor、VS Code Copilot 等均可驱动;Claude、GPT、Gemini、Kimi 等模型均可使用+## 产品定位-市面上的 AI PPT 工具大致分四类,PPT Master 只做最后一类:+**一个文件如果在 PowerPoint 里打不开、改不动,就不该被叫做 PPT。** 市面上的 AI PPT 工具大致分四类,PPT Master 只做最后一类:| 类型 | 产物形态 | 能在 PowerPoint 里逐元素改吗 ||---|---|:---:|@@ -123,13 +107,19 @@ PPT Master 不一样:| HTML 演示 | 网页演示 | ❌ 不是 PPTX || **原生可编辑(PPT Master)** | **真 DrawingML 形状、文本框、图表** | ✅ 每个元素都能点开改 |----+形态上,它不是网站也不是 App,而是一套在 AI IDE(Claude Code / Cursor / VS Code + Copilot / Codebuddy 等)里运行的工作流(一个 "skill"):你在 IDE 的对话框里说"用这份 PDF 做一份 PPT",AI 按这套工作流在你本机生成真正可编辑的 `.pptx`。你不写任何代码,要做的只有三件事——装 Python、装一个 AI IDE、把资料放进来。-## 会用的人,比工具更关键+这个形态换来三个别的工具很难同时给出的承诺:-上面这些示例都是我用它一次性做出来的,甚至都没有精修——如果再花时间精修,那就是另一番样子了。同一个 PowerPoint,设计师能做出令人惊叹的作品,多数人只用到几个基础功能——差别不在工具,在用工具的人。如果你暂时做不到,多半是还没摸熟用法,请先翻一翻 [快速入门](./docs/zh/getting-started.md) 和示例工程。+- **成本透明可控** — 工具免费开源,唯一成本是你自己的 AI 模型用量,你用多少付多少,不在此之外增加任何订阅费用+- **数据不出本地** — 你的文件不应该为了做一份 PPT 就被上传到别人的服务器。除与 AI 模型的对话外,全流程在你的电脑上完成+- **不锁定平台** — 你的工作流不应该被任何一家公司绑架。Claude Code、Cursor、VS Code Copilot 等均可驱动;Claude、GPT、Gemini、Kimi 等模型均可使用-最好的效果确实需要 Claude。觉得贵之前,先想想同等水准的 PPT 请人做要花多少钱?项目本身也支持 GPT、Gemini、Kimi 等模型,只是效果有差异——想要顶配的产出、又只付最低的成本,本就不合常理。+> [!IMPORTANT]+> ### 这是一个工具,不是一个许愿池+> `harness + model = agent`——PPT Master 只负责工作流,产出上限由模型决定。推荐 **Claude 大上下文窗口(~100 万 token)+ AI 生图(`gpt-image-2`)**;其他模型能跑通流程,但有质量差距。+>+> 也别指望一把就拿到完美成品。它的价值是帮你把大部分枯燥的活儿干掉,剩下的打磨交给你——做原生可编辑的 PPT,本就是为了让你接着改,而不是甩给你一张改不动的图。模型越便宜,要补的人工就越多;效果不理想,先升级模型,再对照[快速入门](./docs/zh/getting-started.md)和示例工程检查用法。---@@ -137,19 +127,15 @@ PPT Master 不一样:我是何雨果(Hugo He),投融资领域从业者(注册会计师 · 资产评估师 · 咨询工程师(投资)),工作中经常审阅和修改 PPT。我希望 AI 生成的幻灯片仍然能在 PowerPoint 里继续编辑,而不是被压成一张张图片——所以做了这个。+未来,使用 Python 和 AI agent 的能力会越来越重要,这个项目也想展示:仅凭这两样,你能走多远。零基础上手有一段学习曲线,但走完这段,你就接上了未来——做 PPT 只是个借口,我真正想推广的是 Python 和 agent。+---## 快速开始### 1. 前置条件-**只需装 Python 即可。** 其余依赖通过 `pip install -r requirements.txt` 一次装齐。--| 依赖 | 是否必须 | 用途 |-|------|:--------:|------|-| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **必需** | 核心运行时——唯一真正需要安装的东西 |--> **一句话总结** — 装好 Python,跑一行 `pip install -r requirements.txt`,就可以开始生成 PPT 了。+**只需安装 [Python](https://www.python.org/downloads/) 3.10+。** 其余依赖在第 3 步下载好项目后,用一行 `pip install -r requirements.txt` 装齐。<details open><summary><strong>Windows</strong> — 请看专门的手把手安装指南 ⚠️</summary>@@ -158,7 +144,7 @@ Windows 需要一些额外步骤(PATH 设置、执行策略等)。我们为**📖 [Windows 安装指南](./docs/zh/windows-installation.md)** — 从零到跑通第一份 PPT,10 分钟搞定。-简要流程:从 [python.org](https://www.python.org/downloads/) 下载 Python → **安装时勾选 "Add to PATH"** → `pip install -r requirements.txt` → 完成。+简要流程:从 [python.org](https://www.python.org/downloads/) 下载 Python → **安装时勾选 "Add to PATH"** → 完成,依赖安装见第 3 步。</details><details>@@ -167,11 +153,9 @@ Windows 需要一些额外步骤(PATH 设置、执行策略等)。我们为```bash# macOSbrew install python-pip install -r requirements.txt# Ubuntu / Debiansudo apt install python3 python3-pip-pip install -r requirements.txt```</details>@@ -285,18 +269,23 @@ AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。非用户自带图片有两条路径,可在同一份 deck 里按行混用:-需要 API 的功能统一通过 `.env` 配置。clone 安装可以用 `cp .env.example .env`;skill marketplace 安装建议使用持久的用户级配置:+**A) AI 生图** — `image_gen.py`。设置 `IMAGE_BACKEND` 和对应 `*_API_KEY`(`OPENAI_API_KEY`、`GEMINI_API_KEY` 等),流程会自动调用。`python3 skills/ppt-master/scripts/image_gen.py --list-backends` 查看完整后端清单。`gpt-image-2` 目前综合质量最佳。++**B) 网络图片搜索** — `image_search.py`。**零配置**可用;建议配置 `PEXELS_API_KEY` / `PIXABAY_API_KEY`(都免费申请)以获得稳定的高质量结果:++- 不配置时只使用 Openverse / Wikimedia Commons,适合作为兜底,但容易出现构图随意、清晰度不稳定的图片+- 配置后默认搜索链会追加 Pexels / Pixabay,现代商业摄影、人物、办公、生活方式和插画类图片质量明显更稳定+- 许可自动处理:默认把 CC0、公有领域、Pexels / Pixabay 免署名许可、CC BY、CC BY-SA 一起纳入候选;选中需署名的图片时,Executor 会在该幻灯片自动添加小字署名。只有明确不能出现署名时,才使用 `--strict-no-attribution` 限制为免署名图片+- 对视觉要求高的封面、产品图、人物图和品牌场景,优先级建议:用户自带高清素材 / AI 生图 > 配置 Pexels / Pixabay 的网络搜索 > 零配置网络搜索++上面提到的 API Key 统一通过 `.env` 配置。clone 安装可以用 `cp .env.example .env`;skill marketplace 安装建议使用持久的用户级配置:```bashmkdir -p ~/.ppt-mastercp /path/to/installed/ppt-master/.env.example ~/.ppt-master/.env```-PPT Master 会优先读取当前进程环境变量,然后按顺序读取第一个存在的 `.env`:当前工作目录、clone 仓库根目录、`~/.ppt-master/.env`。--**A) AI 生图** — `image_gen.py`。设置 `IMAGE_BACKEND` 和对应 `*_API_KEY`(`OPENAI_API_KEY`、`GEMINI_API_KEY` 等),流程会自动调用。`python3 skills/ppt-master/scripts/image_gen.py --list-backends` 查看完整后端清单。`gpt-image-2` 目前综合质量最佳。--**B) 网络图片搜索** — `image_search.py`。**零配置**可用,但高质量使用建议配置 `PEXELS_API_KEY` / `PIXABAY_API_KEY`(都免费申请)。不配置时只使用 Openverse / Wikimedia Commons,适合作为兜底,但容易出现普通用户上传、构图随意、清晰度不稳定的图片;配置后默认搜索链会追加 Pexels / Pixabay,现代商业摄影、人物、办公、生活方式和插画类图片质量会明显更稳定。默认以图片质量和匹配度优先,直接把 CC0、公有领域、Pexels / Pixabay 免署名许可、CC BY、CC BY-SA 一起纳入候选;如果选中的图片需要署名,Executor 会在该幻灯片自动添加小字署名。只有明确不能出现署名时,才使用 `--strict-no-attribution` 限制为免署名图片。对视觉要求高的封面、产品图、人物图和品牌场景,优先级建议是:用户自带高清素材 / AI 生图 > 配置 Pexels / Pixabay 的网络搜索 > 零配置网络搜索。+PPT Master 会优先读取当前进程环境变量,然后按顺序读取第一个存在的 `.env`:当前工作目录、skill 安装目录(如 `~/.agents/skills/ppt-master/.env`)、clone 仓库根目录、`~/.ppt-master/.env`。> 完整说明:[`image-generator.md`](./skills/ppt-master/references/image-generator.md)(AI)·[`image-searcher.md`](./skills/ppt-master/references/image-searcher.md)(网络)。@@ -332,7 +321,7 @@ PPT Master 会优先读取当前进程环境变量,然后按顺序读取第一## 相关工具-[cc-switch](https://github.com/farion1231/cc-switch) —— 跨平台桌面应用,统一管理并一键切换 Claude Code、Codex、Gemini CLI 等工具的 API 供应商。在这些 agent 里跑 PPT Master 时很顺手。+[cc-switch](https://github.com/farion1231/cc-switch) —— 一键切换 Claude Code / Codex / Gemini CLI 等工具的 API 供应商。## 联系与合作