如何在 Windows 上安装 PPT Master 并跑通最小生成测试
【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master
这篇文章解决的任务是：在一台 Windows 机器上装好 PPT Master，然后用一次最小规模的快速生成跑通整个环境，确认产出的.pptx能在 PowerPoint 中打开并逐元素编辑。前提有两个：Python 3.10+（文档说明这是唯一的硬性依赖），以及一个支持 Agent 的 AI 工具（Claude Code、Codex、Cursor、VS Code agent 等，需要已安装并完成认证，能读写文件并执行 shell 命令）。整个流程在 Windows 安装指南 中给出的预期时间约 10 分钟。
准备一：安装 Python 并验证
- 从 python.org/downloads 下载Python 3.10+安装包。
- 安装时务必勾选 "Add python.exe to PATH"。文档明确标注这是 Windows 上最常见的失误，不勾选的话后续每一步都会出问题。
- 安装后打开 PowerShell（开始菜单搜索「PowerShell」）执行：
python --version文档示例输出为Python 3.12.x——只要显示 3.10 及以上即通过。如果提示「Python was not found」或弹出 Microsoft Store，跳到常见问题一节。Anaconda / Miniconda 安装的 Python 同样可用，判断标准同样是python --version显示 3.10+。
准备二：获取项目并安装依赖
两种获取方式，二选一。
方式 A — 下载 ZIP（最简单）：在 ppt-master 项目页面（GitHub，或中国大陆可用的 AtomGit 镜像）点击Code → Download ZIP，解压到例如C:\Users\你的用户名\ppt-master。
方式 B — Git Clone（需要 Git，适合长期使用）：
git clone https://github.com/hugohe3/ppt-master.git # 中国大陆可用 AtomGit 镜像： git clone https://atomgit.com/hugohe3/ppt-master.git然后进入项目目录（cd后面的路径替换为你实际的解压/克隆位置）：
cd C:\Users\你的用户名\ppt-master pip install -r requirements.txt如果pip无法识别，改用python -m pip install -r requirements.txt。安装成功的标志是命令结束时输出Successfully installed ...。仓库根目录的 requirements.txt 只是转发到技能内部的依赖清单，两种入口装出来的依赖一致。
验证核心依赖
依赖装完后，在 PowerShell 中执行文档给定的导入检查：
python -c "import pptx; import fitz; print('All core dependencies OK')"- 输出
All core dependencies OK→ 核心环境没问题，进入下一步。 - 报错 → 到常见问题中按现象对照处理。
跑通最小生成测试
这一步用 AI 工具驱动，而不是命令行。在支持 Agent 的 AI 工具中打开ppt-master目录（完整仓库克隆时，仓库根目录就是工作文件夹；agent 会在其下创建projects/<生成的项目名>/作为活动项目），然后在聊天面板输入 Windows 安装指南 给出的最小测试指令：
请快速生成一个 3 页测试 PPT，封面 + 内容页 + 封底，主题"Hello World"，不用跟我确认这里显式要求快速生成是关键：agent 会走quick-generateprofile，跳过策略分析和设计确认的来回，直接创作并导出。默认的 Default Generate 流程会先停下来跟你确认设计规范——做正式 deck 时需要，但只是验证环境时太慢。
跑完后的判断标准（文档原样给出）：
- 活动项目的
exports/下出现一个原生 DrawingML 的.pptx（由转换器从svg_output/生成，文件名形如<项目名>_<时间戳>.pptx，agent 会报告确切路径）； - 该文件能在 PowerPoint 中打开，且可以逐元素编辑。
这两点满足即表示环境跑通。有一点需要提前知道，避免误判：快速生成会跳过finalize_svg.py，所以不会生成svg_final/预览目录——那是默认流程的产物，没有它不代表失败。
常见问题速查
以下现象与解法全部来自 Windows 安装指南 的 Troubleshooting 一节：
python未找到或弹出 Microsoft Store
原因是 Python 不在系统 PATH。三种修复，按顺序尝试：
- 重新运行 Python 安装程序 →Modify→ 勾选 "Add Python to environment variables"。
- 手动加 PATH：先在 PowerShell 执行
where python找到实际路径（如C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\python.exe），在开始菜单搜索「Environment Variables」，编辑Path，把该路径所在目录及其Scripts子目录加入，然后重启 PowerShell。 - 改用
python3或py命令试试。
python3命令失败（exit 49 / 弹出 Microsoft Store）
python.org 的安装包只提供python.exe，不提供python3.exe。把命令里的python3换成python即可，AI agent 遇到这种情况通常也会自行切换继续。
pip install权限错误
pip install --user -r requirements.txt或者以管理员身份运行 PowerShell 再装。
pip install网络失败
文档给出两条命令（清华 PyPI 镜像，或走代理，代理地址替换为你自己的）：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple pip install -r requirements.txt --proxy http://your-proxy:portModuleNotFoundError
说明pip装到了另一个 Python 环境。用python -m pip install -r requirements.txt重装，保证 pip 与当前python是同一个。
import fitz失败
- 先升级 pip：
python -m pip install --upgrade pip - 强制使用预编译 wheel：
pip install PyMuPDF --only-binary :all: - 仍然失败则安装 Visual C++ Build Tools（Microsoft 官网提供下载）。
PowerShell 提示"running scripts is disabled"
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser可选增强：Pandoc（大多数情况可跳过）
装好 Python 和requirements.txt后，生成 PPT 所需的全部功能已经就绪；PPTX 导出直接写原生 DrawingML 形状，不需要 CairoSVG、GTK 或额外的 SVG 栅格化环境。唯一需要额外装的是 Pandoc，且仅在你要转换.doc、.odt、.rtf、.tex、.rst、.org或.typ这类旧格式文档时才装——.docx/.html/.epub/.ipynb由 Python 原生处理，不需要 Pandoc。安装.msi后用pandoc --version验证。
装完之后的边界说明
- 快速生成测试通过只证明环境链路（依赖、导入、SVG 创作、导出）可用，不代表正式 deck 的质量下限；做正式 deck 时改用默认流程，它会先与你确认设计规范。
- 后续更新方式取决于安装方式：Git clone 用
python3 skills/ppt-master/scripts/update_repo.py；ZIP 没有 Git 历史，需下载最新 ZIP 后把旧的.env和projects/目录拷入新目录再重装依赖（见 FAQ）。 - 更多生成行为（模板、动画、旁白等）见 Getting Started 与 FAQ。
【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
