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: add Windows installation guide and restructure prerequisites
hugohe304fc71d9ce85
diff --git a/README.md b/README.mdindex bd73be21..8455ffa9 100644--- a/README.md+++ b/README.md@@ -69,7 +69,27 @@ This project is my attempt to bridge the gap between **domain expertise** and **### 1. Prerequisites-**Required:** [Python](https://www.python.org/downloads/) 3.10+ · **Optional:** [Node.js](https://nodejs.org/) 18+ (for WeChat page conversion) · [Pandoc](https://pandoc.org/) (for DOCX/EPUB conversion)+| Dependency | Required? | What it does | If you skip it |+|------------|:---------:|--------------|----------------|+| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **Yes** | Core runtime — everything depends on this | Nothing works |+| [Node.js](https://nodejs.org/) 18+ | ❌ Optional | Converts WeChat articles and complex web pages to Markdown | You can still use PDF, DOCX, plain text, and simple URLs as source |+| [Pandoc](https://pandoc.org/) | ❌ Optional | Converts DOCX, EPUB, HTML, LaTeX, RST to Markdown | You can still use PDF, plain text, and URLs as source |+++> **TL;DR** — Install Python, run `pip install -r requirements.txt`, and you're ready to generate presentations. Install the rest only when you need them.++<details open>+<summary><strong>Windows</strong> — see the dedicated step-by-step guide ⚠️</summary>++Windows requires a few extra steps (PATH setup, execution policy, etc.). We wrote a **step-by-step guide** specifically for Windows users:++**📖 [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.+</details>++<details>+<summary><strong>macOS / Linux</strong> — install and go</summary>```bash# macOS@@ -77,13 +97,12 @@ brew install pythonbrew install node # optional — for WeChat page conversionbrew install pandoc # optional — for DOCX/EPUB conversion-# Ubuntu/Debian+# Ubuntu / Debiansudo apt install python3 python3-pipsudo apt install nodejs npm # optionalsudo apt install pandoc # optional--# Windows — download from python.org, nodejs.org, pandoc.org```+</details>### 2. Pick an AI Editor@@ -169,6 +188,7 @@ Run `python3 skills/ppt-master/scripts/image_gen.py --list-backends` to see tier| | Document | Description ||---|----------|-------------|| 🆚 | [Why PPT Master](./docs/why-ppt-master.md) | How it compares to Gamma, Copilot, and other AI tools |+| 🪟 | [Windows Installation](./docs/windows-installation.md) | Step-by-step setup guide for Windows users || 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | Core workflow and rules || 📐 | [Canvas Formats](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9, Xiaohongshu, WeChat, and 10+ formats || 🛠️ | [Scripts & Tools](./skills/ppt-master/scripts/README.md) | All scripts and commands |diff --git a/README_CN.md b/README_CN.mdindex 51ec7530..0450ed13 100644--- a/README_CN.md+++ b/README_CN.md@@ -69,7 +69,27 @@ PPT Master 源于一个真实的痛点:在投融资和咨询工作中,我每### 1. 前置条件-**必需:** [Python](https://www.python.org/downloads/) 3.10+ · **可选:** [Node.js](https://nodejs.org/) 18+(微信公众号转换)· [Pandoc](https://pandoc.org/)(DOCX/EPUB 转换)+| 依赖项 | 是否必需 | 作用 | 不装会怎样 |+|--------|:--------:|------|-----------|+| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **必需** | 核心运行时——一切都依赖它 | 什么都跑不了 |+| [Node.js](https://nodejs.org/) 18+ | ❌ 可选 | 将微信公众号文章、复杂网页转换为 Markdown | 仍可用 PDF、DOCX、纯文本、简单 URL 作为素材 |+| [Pandoc](https://pandoc.org/) | ❌ 可选 | 将 DOCX、EPUB、HTML、LaTeX、RST 转换为 Markdown | 仍可用 PDF、纯文本、URL 作为素材 |+++> **一句话总结** — 装好 Python,跑一行 `pip install -r requirements.txt`,就可以开始生成 PPT 了。其余的用到时再装。++<details open>+<summary><strong>Windows</strong> — 请看专门的手把手安装指南 ⚠️</summary>++Windows 需要一些额外步骤(PATH 设置、执行策略等)。我们为 Windows 用户写了一份**手把手安装指南**:++**📖 [Windows 安装指南](./docs/zh/windows-installation.md)** — 从零到跑通第一份 PPT,10 分钟搞定。++简要流程:从 [python.org](https://www.python.org/downloads/) 下载 Python → **安装时勾选 "Add to PATH"** → `pip install -r requirements.txt` → 完成。+</details>++<details>+<summary><strong>macOS / Linux</strong> — 安装即用</summary>```bash# macOS@@ -77,13 +97,12 @@ brew install pythonbrew install node # 可选——用于微信公众号等网页转换brew install pandoc # 可选——用于 DOCX/EPUB 转换-# Ubuntu/Debian+# Ubuntu / Debiansudo apt install python3 python3-pipsudo apt install nodejs npm # 可选sudo apt install pandoc # 可选--# Windows — 从 python.org、nodejs.org、pandoc.org 下载安装```+</details>### 2. 选择 AI 编辑器@@ -173,6 +192,7 @@ GEMINI_MODEL=gemini-3.1-flash-image-preview| | 文档 | 说明 ||---|------|------|| 🆚 | [为什么选 PPT Master](./docs/zh/why-ppt-master.md) | 与 Gamma、Copilot 等工具的对比 |+| 🪟 | [Windows 安装指南](./docs/zh/windows-installation.md) | Windows 用户手把手安装教程 || 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | 核心流程与规则 || 📐 | [画布格式](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9、小红书、朋友圈等 10+ 种格式 || 🛠️ | [脚本与工具](./skills/ppt-master/scripts/README.md) | 所有脚本和命令 |diff --git a/docs/windows-installation.md b/docs/windows-installation.mdnew file mode 100644index 00000000..98ec0f20--- /dev/null+++ b/docs/windows-installation.md@@ -0,0 +1,151 @@+# Windows Installation Guide++This guide walks you through installing PPT Master on Windows step by step. Follow along and you'll have a working setup in under 10 minutes.++---++## Step 1 — Install Python (Required)++Python is the only hard requirement.++1. Go to **[python.org/downloads](https://www.python.org/downloads/)** and download the latest **Python 3.10+** installer.++2. **⚠️ CRITICAL: Check "Add python.exe to PATH"** during installation — this is the single most common mistake on Windows. Skipping this will break every step that follows.++ ++3. After installation, open **PowerShell** (search "PowerShell" in Start menu) and verify:++ ```powershell+ python --version+ ```++ You should see `Python 3.12.x` or similar. If you see "Python was not found" or it opens the Microsoft Store, see [Troubleshooting](#python-was-not-found-or-opens-microsoft-store) below.++> **💡 Tip**: Python installed via Anaconda or Miniconda works too — just make sure `python --version` shows 3.10+.++---++## Step 2 — Download the Project++**Option A — Download ZIP** (easiest):++1. Go to [github.com/hugohe3/ppt-master](https://github.com/hugohe3/ppt-master)+2. Click the green **Code** button → **Download ZIP**+3. Unzip to `C:\Users\YourName\ppt-master`++**Option B — Git Clone** (requires [Git](https://git-scm.com/downloads)):++```powershell+git clone https://github.com/hugohe3/ppt-master.git+cd ppt-master+```++---++## Step 3 — Install Dependencies++```powershell+cd C:\Users\YourName\ppt-master # ← adjust to your actual path+pip install -r requirements.txt+```++> If `pip` is not recognized, try `python -m pip install -r requirements.txt`.++Wait for it to finish. You should see `Successfully installed ...` at the end.++---++## Step 4 — Verify Your Setup++```powershell+python -c "import pptx; import fitz; print('All core dependencies OK')"+```++✅ Output: `All core dependencies OK` → you're good.++❌ Error → see [Troubleshooting](#troubleshooting) below.++---++## Step 5 — Run a Minimal Example++Open your AI editor (Cursor, VS Code + Copilot, etc.), open the `ppt-master` folder, and type in the chat:++```+Please create a simple 3-page test PPT with a cover, one content page, and a closing page. Topic: "Hello World".+```++If a `.pptx` file appears in `exports/` that opens in PowerPoint — **you're done.**++---++## Step 6 — Optional Dependencies (install when needed)++| Dependency | How to install | Verify |+|------------|----------------|--------|+| **Node.js** — WeChat articles / complex web pages | Download LTS from [nodejs.org](https://nodejs.org/) | `node --version` → v18+ |+| **Pandoc** — DOCX / EPUB conversion | Download `.msi` from [pandoc.org](https://pandoc.org/installing.html) | `pandoc --version` |+| **CairoSVG** — higher quality PNG fallbacks | Install [GTK3 Runtime](https://github.com/nickvdp/gtk3/releases), then `pip install cairosvg` | `python -c "import cairosvg"` |++> Skip CairoSVG if unsure. PPT Master auto-falls back to `svglib` (already installed via `requirements.txt`), which works fine for most cases.++---++## Troubleshooting++### `python` was not found or opens Microsoft Store++**Cause**: Python isn't in your system PATH.++**Fix 1** — Re-run the Python installer → **Modify** → check **"Add Python to environment variables"**.++**Fix 2** — Manually add to PATH:+1. Run `where python` in PowerShell first to find the actual path (e.g. `C:\Users\YourName\AppData\Local\Programs\Python\Python312\python.exe`)+2. Search "Environment Variables" in Start menu+3. Find `Path` → **Edit** → add the **directory** from step 1 and its `Scripts` subfolder:+ ```+ C:\Users\YourName\AppData\Local\Programs\Python\Python312+ C:\Users\YourName\AppData\Local\Programs\Python\Python312\Scripts+ ```+4. Click OK, then **restart PowerShell**++**Fix 3** — Try `python3` or `py` instead.++### `pip install` fails with permission errors++```powershell+pip install --user -r requirements.txt+```++Or run PowerShell as Administrator.++### `pip install` fails due to network issues++```powershell+pip install -r requirements.txt --proxy http://your-proxy:port+```++### `ModuleNotFoundError`++`pip` installed to a different Python. Use `python -m pip install -r requirements.txt` to match.++### `import fitz` fails++1. Upgrade pip: `python -m pip install --upgrade pip`+2. Pre-built wheel: `pip install PyMuPDF --only-binary :all:`+3. Still failing → install [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)++### PowerShell says "running scripts is disabled"++```powershell+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser+```++---++## Still stuck?++- 📖 [FAQ](./faq.md)+- 🐛 [GitHub Issues](https://github.com/hugohe3/ppt-master/issues) — include your Python version, Windows version, and full error message+- 💬 [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions)diff --git a/docs/zh/windows-installation.md b/docs/zh/windows-installation.mdnew file mode 100644index 00000000..0908b46a--- /dev/null+++ b/docs/zh/windows-installation.md@@ -0,0 +1,158 @@+# Windows 安装指南++本指南将手把手教你在 Windows 上安装 PPT Master。按顺序操作,10 分钟内即可跑通第一份 PPT。++---++## Step 1 — 安装 Python(必须)++Python 是唯一的硬性要求。++1. 前往 **[python.org/downloads](https://www.python.org/downloads/)**,下载最新的 **Python 3.10+** 安装包。++2. **⚠️ 关键步骤:安装时务必勾选 "Add python.exe to PATH"** — 这是 Windows 上最常见的安装失误,不勾的话后面每一步都会出问题。++ ++3. 安装完成后,打开 **PowerShell**(在开始菜单搜索「PowerShell」)并验证:++ ```powershell+ python --version+ ```++ 应该看到 `Python 3.12.x` 之类的输出。如果提示「未找到」或弹出 Microsoft Store,见下方[常见问题](#python-未找到或弹出-microsoft-store)。++> **💡 提示**:Anaconda / Miniconda 安装的 Python 也可以用,只要 `python --version` 显示 3.10+ 即可。++---++## Step 2 — 下载项目++**方式 A — 下载 ZIP**(最简单):++1. 打开 [GitHub](https://github.com/hugohe3/ppt-master)(或 [AtomGit 镜像](https://atomgit.com/hugohe3/ppt-master),国内更快)+2. 点击绿色 **Code** 按钮 → **Download ZIP**+3. 解压到 `C:\Users\你的用户名\ppt-master`++**方式 B — Git Clone**(需要 [Git](https://git-scm.com/downloads)):++```powershell+# GitHub+git clone https://github.com/hugohe3/ppt-master.git+# AtomGit(国内更快)+git clone https://atomgit.com/hugohe3/ppt-master.git+cd ppt-master+```++---++## Step 3 — 安装依赖++```powershell+cd C:\Users\你的用户名\ppt-master # ← 替换为你的实际路径+pip install -r requirements.txt+```++> 如果 `pip` 无法识别,用 `python -m pip install -r requirements.txt`。++等待安装完成,最后看到 `Successfully installed ...` 就行。++---++## Step 4 — 验证安装++```powershell+python -c "import pptx; import fitz; print('All core dependencies OK')"+```++✅ 输出 `All core dependencies OK` → 核心环境没问题。++❌ 报错 → 见下方[常见问题](#常见问题)。++---++## Step 5 — 跑一个最小示例++打开你的 AI 编辑器(Cursor、VS Code + Copilot 等),打开 `ppt-master` 目录,在聊天面板输入:++```+请创建一个 3 页测试 PPT,封面 + 内容页 + 封底,主题"Hello World"+```++`exports/` 下出现 `.pptx` 且能在 PowerPoint 中打开 → **搞定了。**++---++## Step 6 — 可选依赖(用到时再装)++| 依赖 | 安装方式 | 验证 |+|------|---------|------|+| **Node.js** — 微信公众号 / 复杂网页转换 | [nodejs.org](https://nodejs.org/) 下载 LTS 版安装 | `node --version` → v18+ |+| **Pandoc** — DOCX / EPUB 转换 | [pandoc.org](https://pandoc.org/installing.html) 下载 `.msi` 安装 | `pandoc --version` |+| **CairoSVG** — 更高质量 PNG 后备图 | 安装 [GTK3 Runtime](https://github.com/nickvdp/gtk3/releases) 后 `pip install cairosvg` | `python -c "import cairosvg"` |++> CairoSVG 不确定就跳过。PPT Master 会自动用 `svglib`(已随 `requirements.txt` 安装),大多数情况够用。++---++## 常见问题++### `python` 未找到或弹出 Microsoft Store++**原因:** Python 没有加入系统 PATH。++**方法 1** — 重新运行 Python 安装程序,选择 **Modify**,确保勾选 **"Add Python to environment variables"**。++**方法 2** — 手动添加 PATH:+1. 先在 PowerShell 中运行 `where python`,记下输出的路径(如 `C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\python.exe`)+2. 开始菜单搜索「环境变量」+3. 找到 `Path` → **编辑** → 新增上面路径的**目录部分**及其 `Scripts` 子目录:+ ```+ C:\Users\你的用户名\AppData\Local\Programs\Python\Python312+ C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\Scripts+ ```+4. 确定,**重启 PowerShell**++**方法 3** — 试试 `python3` 或 `py` 命令。++### `pip install` 报权限错误++```powershell+pip install --user -r requirements.txt+```++或以管理员身份运行 PowerShell。++### `pip install` 网络问题++```powershell+# 清华镜像(国内推荐)+pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple++# 代理+pip install -r requirements.txt --proxy http://your-proxy:port+```++### `ModuleNotFoundError`++`pip` 装到了另一个 Python 环境。用 `python -m pip install -r requirements.txt` 确保对应同一个。++### `import fitz` 失败++1. 升级 pip:`python -m pip install --upgrade pip`+2. 预编译包:`pip install PyMuPDF --only-binary :all:`+3. 仍失败 → 安装 [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)++### PowerShell「脚本运行被禁用」++```powershell+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser+```++---++## 还是搞不定?++- 📖 [常见问题 (FAQ)](./faq.md)+- 🐛 [GitHub Issues](https://github.com/hugohe3/ppt-master/issues) — 附上 Python 版本、Windows 版本和完整报错+- 💬 [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions)