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(faq): expand FAQ with issues-based content and improve discoverability
hugohe32be464d8f6ac
diff --git a/README.md b/README.mdindex a84dc88d..0263ad53 100644--- a/README.md+++ b/README.md@@ -117,6 +117,8 @@ The AI handles everything — content analysis, visual design, SVG generation, a> **AI lost context?** Ask it to read `skills/ppt-master/SKILL.md`.+> **Something went wrong?** Check the **[FAQ](./docs/faq.md)** — it covers model selection, layout issues, export problems, and more. Continuously updated from real user reports.+### 5. AI Image Generation (Optional)```bash@@ -146,7 +148,7 @@ Run `python3 skills/ppt-master/scripts/image_gen.py --list-backends` to see tier| 🛠️ | [Scripts & Tools](./skills/ppt-master/scripts/README.md) | All scripts and commands || 💼 | [Examples](./examples/README.md) | 15 projects, 229 pages || 🏗️ | [Technical Design](./docs/technical-design.md) | Architecture, design philosophy, why SVG |-| ❓ | [FAQ](./docs/faq.md) | Cost, editing, custom templates |+| ❓ | [FAQ](./docs/faq.md) | Model selection, cost, layout troubleshooting, custom templates |---diff --git a/README_CN.md b/README_CN.mdindex e2518ae4..34e0ba95 100644--- a/README_CN.md+++ b/README_CN.md@@ -117,6 +117,8 @@ AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。> **AI 迷失上下文?** 让它先读 `skills/ppt-master/SKILL.md`。+> **遇到问题?** 查看 **[常见问题](./docs/zh/faq.md)** — 涵盖模型选择、排版问题、导出异常等,基于真实用户反馈持续更新。+### 5. AI 生图配置(可选)```bash@@ -146,7 +148,7 @@ GEMINI_MODEL=gemini-3.1-flash-image-preview| 🛠️ | [脚本与工具](./skills/ppt-master/scripts/README.md) | 所有脚本和命令 || 💼 | [示例](./examples/README.md) | 15 个项目,229 页 || 🏗️ | [技术路线](./docs/zh/technical-design.md) | 架构、设计哲学、为什么选 SVG |-| ❓ | [常见问题](./docs/zh/faq.md) | 费用、编辑、自定义模板 |+| ❓ | [常见问题](./docs/zh/faq.md) | 模型选择、费用、排版问题排查、自定义模板 |---diff --git a/docs/faq.md b/docs/faq.mdindex fe65cc5f..e4684421 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -4,6 +4,32 @@---+## Q: What source formats does PPT Master accept?++Almost anything: **PDF**, **DOCX**, **PPTX**, **EPUB**, **HTML**, **LaTeX**, **RST**, **URLs** (including WeChat articles), **Markdown**, or just plain text pasted into the conversation. The AI agent converts your source material to Markdown automatically before generating slides.++## Q: Can PPT Master produce formats other than PowerPoint?++Yes. Besides the standard **16:9** and **4:3** presentation formats, PPT Master supports social media and marketing formats out of the box:++| Format | Use Case |+|--------|----------|+| Xiaohongshu (RED) 3:4 | Image-text sharing, knowledge posts |+| WeChat Moments / IG 1:1 | Square posters, brand showcases |+| Story / TikTok 9:16 | Vertical stories, short video covers |+| WeChat Article Header | WeChat article cover images |+| A4 Print | Print posters, flyers |++Just specify the format when starting a project (e.g., `--format xhs`). The output is still a `.pptx` file containing native shapes.++## Q: What AI tools work with PPT Master?++PPT Master works with any AI coding agent that can read files and run shell commands — **Claude Code** (CLI / VS Code / JetBrains / Web), **VS Code Copilot**, **Codex**, and others. See the cost comparison below for pricing differences.++## Q: Can I use AI-generated images in my presentation?++Yes. PPT Master includes a built-in image generation script that supports multiple providers (Gemini, OpenAI, FLUX, Qwen, Zhipu, etc.). During the Strategist phase, if you choose "AI generation" for the image approach, the pipeline will automatically generate images based on your content. You can also provide your own images — just place them in the project's `images/` folder.+## Q: Can I edit the generated presentations?Yes! Both files are saved to `exports/` with a timestamp. The native `.pptx` produces **native PowerPoint shapes** — all text, graphics, and colors are directly editable without any conversion. The `_svg.pptx` is an SVG snapshot kept as a visual reference backup. Requires **Office 2016** or later.@@ -31,6 +57,36 @@ For a complete presentation, **$0.08–$0.24 USD** is not expensive at all.Charts are rendered as **custom-designed SVG graphics** converted to native PowerPoint shapes — not Excel-driven chart objects. This gives them a polished, high-fidelity appearance that often looks better than default PowerPoint charts. However, the underlying data is not editable via PowerPoint's chart editor. If you need a live, data-driven chart (e.g., one you can update by editing a spreadsheet), you will need to manually replace it with a native PowerPoint chart after export.+## Q: Which AI model works best?++**Claude** (Opus / Sonnet) is the recommended and most tested model. SVG layout requires precise absolute-coordinate calculations (font size x character count x container width), and Claude handles this significantly better than alternatives.++**GPT series** models tend to produce more layout issues — text overflowing containers, misaligned elements, coordinate miscalculations. If you must use a non-Claude model, try enabling Fast mode and keep expectations for layout precision lower.++Other models (Gemini, GLM, MiniMax, etc.) vary in quality. In general, models with stronger frontend/visual capabilities produce better results.++## Q: Text overflows or elements are misaligned — what can I do?++This is almost always a model capability issue, not a bug in PPT Master. SVG layout is essentially manual absolute positioning — the model must calculate coordinates, font metrics, and container sizes correctly.++**Fixes to try**:+1. Switch to **Claude** (Opus or Sonnet) if you're using another model+2. Tell the AI which specific page has the problem and describe the issue — it can regenerate individual pages+3. Open the SVG source file directly and ask the AI to fix coordinates+4. Remember: the generated PPTX is a **high-quality starting point**, not a final deliverable — minor adjustments in PowerPoint are expected++## Q: How long does a presentation take to generate?++A typical 10–15 page presentation takes about **10–20 minutes** with a fast model. Generation is **intentionally serial** (one page at a time) to maintain visual consistency across slides — parallel generation was tested and produced inconsistent styles.++If generation feels slow, check your model's token throughput. The bottleneck is usually the model's output speed, not the scripts.++## Q: Can I preview or fix individual pages before the full export?++Yes. You can **interrupt the workflow at any time** — after the first few pages are generated, review them and give feedback. The AI can regenerate specific pages based on your comments. You don't need to wait until the end to make corrections.++For post-generation fixes, simply tell the AI: "Page 3 has a layout issue — the title overlaps the chart" and it will fix that specific SVG.+## Q: How do I create a custom template?Want to turn a PPT you love into a reusable template for PPT Master? Here's how:@@ -43,12 +99,14 @@ If you already have the original `.pptx` template file, you can also provide it**Step 2 — Let AI Create the Template**-Use an AI coding agent (Claude Code, Codex, etc.) and ask it to use the **PPT Master `/create-template` workflow** to convert your reference material into a template. In your prompt, provide:+Use an AI coding agent (Claude Code, Codex, etc.) and ask it to use the **PPT Master `/create-template` workflow** to convert your reference material into a template. The more context you give, the better the result — for example:++- Template name and intended use case (e.g., government reports, premium consulting)+- Desired tone and color palette (e.g., "modern and restrained, dark blue primary")+- Category preference (`brand` / `general` / `scenario` / `government` / `special`)+- Canvas format, if not the default 16:9-- The template's English name and Chinese name-- The intended use case (e.g., government reports, premium consulting, product launches)-- The desired visual effects and color palette to apply when this template is used-- Whether to enable AI image generation+You don't need to supply every detail upfront — the AI agent will ask follow-up questions to fill in anything missing (template ID, theme mode, etc.).**Step 3 — Wait for the Result**diff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex 3e812aa8..7720614d 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -4,6 +4,32 @@---+## Q: PPT Master 支持哪些源文件格式?++几乎所有常见格式都支持:**PDF**、**DOCX**、**PPTX**、**EPUB**、**HTML**、**LaTeX**、**RST**、**网页链接**(包括微信公众号文章)、**Markdown**,或者直接在对话中粘贴文字内容。AI 代理会自动将源材料转换为 Markdown 后再生成幻灯片。++## Q: 除了 PPT 还能生成其他格式吗?++可以。除了标准的 **16:9** 和 **4:3** 演示文稿格式,PPT Master 还内置了社交媒体和营销类格式:++| 格式 | 适用场景 |+|------|----------|+| 小红书 3:4 | 图文分享、知识帖 |+| 微信朋友圈 / IG 1:1 | 方形海报、品牌展示 |+| Story / 抖音 9:16 | 竖版故事、短视频封面 |+| 微信文章头图 | 公众号文章封面 |+| A4 印刷 | 印刷海报、传单 |++创建项目时指定格式即可(如 `--format xhs`)。输出仍然是包含原生形状的 `.pptx` 文件。++## Q: PPT Master 支持哪些 AI 工具?++PPT Master 可以在任何能读取文件和执行命令的 AI 编程代理中运行——**Claude Code**(CLI / VS Code / JetBrains / Web)、**VS Code Copilot**、**Codex** 等均可使用。不同工具的使用成本可参考下方的费用对比。++## Q: 能用 AI 生成配图吗?++可以。PPT Master 内置了图片生成脚本,支持多个供应商(Gemini、OpenAI、FLUX、通义千问、智谱等)。在策略师阶段选择"AI 生图"方案后,流程会根据内容自动生成配图。你也可以使用自己的图片——只需放到项目的 `images/` 目录下即可。+## Q: 生成的 PPT 可以编辑吗?可以!两个文件均以时间戳命名保存至 `exports/`。原生版 `.pptx` 包含**原生 PowerPoint 形状**,所有文字、图形、颜色均可直接编辑,无需任何转换。`_svg.pptx` 为 SVG 快照版,作为视觉参考备份保留。需要 **Office 2016** 或更高版本。@@ -31,6 +57,36 @@图表以**自定义设计的 SVG 图形**形式渲染,转换为原生 PowerPoint 形状——而不是 Excel 驱动的图表对象。这使得图表外观精良,视觉效果通常优于 PowerPoint 默认图表样式。但图表的底层数据无法通过 PowerPoint 图表编辑器修改。如果你需要可实时更新数据的图表(例如通过编辑表格来刷新数据),需要在导出后自行将其替换为原生 PowerPoint 图表。+## Q: 推荐用什么 AI 模型?++**Claude**(Opus / Sonnet)是推荐且测试最充分的模型。SVG 排版本质上是在绝对坐标系中做精确的数学计算(字号 x 字数 x 容器宽度),Claude 在这方面表现明显优于其他模型。++**GPT 系列**模型更容易出现排版问题——文字超出容器、元素错位、坐标计算失误。如果必须用非 Claude 模型,可以尝试开启 Fast 模式,但对排版精度的预期需要适当降低。++其他模型(Gemini、GLM、MiniMax 等)效果参差不齐。总体来说,前端/视觉能力越强的模型,生成效果越好。++## Q: 文字超出边框 / 元素错位怎么办?++这几乎都是模型能力问题,不是 PPT Master 的 bug。SVG 排版是纯手动绝对定位——模型必须准确计算坐标、字体度量和容器尺寸。++**解决办法**:+1. 切换到 **Claude**(Opus 或 Sonnet),如果你用的是其他模型+2. 告诉 AI 哪一页有问题、具体是什么问题——它可以单独重新生成某一页+3. 直接打开 SVG 源文件,让 AI 修正坐标+4. 记住:生成的 PPTX 是**高质量起点**,不是最终成品——在 PowerPoint 中做少量调整是正常的++## Q: 生成一份 PPT 要多久?++一份典型的 10–15 页 PPT 大约需要 **10–20 分钟**(使用吞吐较快的模型)。生成流程是**故意串行的**(逐页生成),这样才能保持前后页面的视觉一致性——并行生成方案曾经测试过,结果是各画各的、缺乏整体观。++如果感觉生成很慢,检查一下模型的 token 吞吐速度。瓶颈通常在模型的输出速度,而不是脚本本身。++## Q: 能在导出前预览或修正某一页吗?++可以。你可以**随时中断工作流**——前几页生成后就可以查看并反馈意见。AI 可以根据你的意见重新生成特定页面,不需要等到全部完成再修改。++生成后的修正也一样简单,直接告诉 AI:"第 3 页布局有问题——标题和图表重叠了",它会修正那个特定的 SVG。+## Q: 如何制作自定义模板?想把自己喜欢的 PPT 模板制作成 PPT Master 可调用的模板?按以下步骤操作:@@ -43,12 +99,14 @@**第二步 — 让 AI 创建模板**-使用 AI 编程代理(Claude Code、Codex 等),要求它使用 **PPT Master 的 `/create-template` 工作流**,将这些参考材料转换成模板。在提示中需要提供:+使用 AI 编程代理(Claude Code、Codex 等),要求它使用 **PPT Master 的 `/create-template` 工作流**,将这些参考材料转换成模板。提供的信息越详细,效果越好,例如:++- 模板名称和适用场景(如政府汇报、高端咨询、产品宣讲等)+- 期望的风格基调和配色(如"现代克制、深蓝主色调")+- 类别偏好(`brand` 品牌 / `general` 通用 / `scenario` 场景 / `government` 政务 / `special` 特殊)+- 画布格式(默认 16:9,如需其他格式请注明)-- 模板的英文名称和中文名称-- 适用场景(如政府汇报、高端咨询、产品宣讲等)-- 使用该模板时希望触发的特效和配色风格-- 是否需要启用 AI 生图+不需要一次提供所有细节——AI 代理会通过对话追问补齐缺失信息(模板 ID、主题模式等)。**第三步 — 等待完成**diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex ad499530..c72035be 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -316,3 +316,4 @@ Before switching roles, you **MUST first read** the corresponding reference file- Do NOT add extra flags like `--only` to the post-processing commands — run them as-is- Local preview: `python3 -m http.server -d <project_path>/svg_final 8000`+- **Troubleshooting**: If the user encounters issues during generation (layout overflow, export errors, blank images, etc.), recommend checking `docs/faq.md` — it contains known solutions sourced from real user reports and is continuously updated