一篇从架构到踩坑的完整记录。文末附绿色包网盘下载地址与开源仓库，全部免费。
缘起
ppt-master(https://github.com/hugohe3/ppt-master) 是 GitHub 上 5.5 万 Star 的开源项目（MIT 协议）：丢给它一份 PDF、Word、网页链接甚至一个主题，它就能产出一份原生可编辑的 .pptx------不是图片拼贴，而是真正的形状、文本框、图表，每个元素都能在 PowerPoint 里点开修改。
它的原理本质是一个运行在 AI 编程工具（Claude Code / Cursor）里的 skill：LLM 读 SKILL.md 里的规范，在本地跑 Python 脚本流水线。
这带来一个门槛：你得先会装 AI 编程工具、会开终端、会配 API。我身边想用它的人，十个有八个卡在第一步。
所以动手做了一个桌面版：PPT Master Desktop。选文件 → 选风格 → 点生成，完事。
先看东西长什么样
界面上四步：选源材料、选风格与版式、点生成、预览导出。状态栏会显示当前环境是否就绪（技能包、Python、API Key）。
架构：LLM 是大脑，Python 是手脚
整个应用是一条五段流水线：
- 源材料：PDF / DOCX / XLSX / EPUB / 网页链接 / Markdown / 粘贴文本
- 文档解析 ：上游的
source_to_md.py把任何格式转成结构化 Markdown，纯本地 - LLM 设计：调 OpenAI 兼容 API（Kimi / DeepSeek / GPT / 本地 vLLM 都行），先生成全局大纲，再逐页产出 SVG 版式------14 种内置风格（MBB 咨询、学术答辩、产品发布、投资人路演......）的风格规范直接注入提示词
- 质量门禁 ：每页 SVG 过一遍上游的
svg_quality_checker.py，禁止mask、foreignObject、外部 CSS 这些 PPTX 导不出来的写法；不合格的页面带着错误报告回炉重写，最多 3 轮 - 导出 ：
svg_to_pptx.py把 SVG 翻译成 DrawingML 原生对象，支持母版继承
Electron 壳只做三件事：向导式 GUI、管理设置、用子进程调度这条 Python 管线并实时回显日志。
四个关键设计决策
① 死磕"原生可编辑"，不走图片路线。 市面上多数 AI PPT 工具输出的是网页截图或图片拼贴，看起来像那么回事，但拿去改一个字都费劲。ppt-master 的 SVG→PPTX 导出器能产出真正的 PowerPoint 对象，这是整个项目最值钱的部分，桌面版原样保留。
② 用"检查器 + 自动修复"对抗 LLM 的不稳定。 LLM 生成的 SVG 一定会有违规写法，与其祈祷它输出正确，不如让质量检查器当守门员：检查失败的页面把具体错误（哪个元素、违反哪条规则）回传给模型重写。实测绝大多数问题 1 轮就能修好。
③ 路径全部参数化。 我自己的 C 盘只剩 3G，所以所有数据目录都走一个 PPMASTER_HOME 环境变量推导，代码里没有一个写死的盘符。C 盘紧张的用户设一下变量，数据就全落 D 盘。
④ 自动更新接 GitHub Releases。 内置 electron-updater，发新版只要把安装包和 latest.yml 传上 Release，老用户的客户端启动时就会收到提示、一键升级。绿色包同样生效。
踩坑实录（这部分最有干货）
坑 1：打包后界面永远停在"检测中..."。 开发模式一切正常，一打包就废。用 npx asar list 检查包内容才发现：package.json 的 build.files 白名单里漏了 preload.js------它躺在项目根目录，不在任何子目录里，是最容易被漏掉的那个文件。preload 没进包 → window.api 是 undefined → 渲染层所有 IPC 静默失败。
教训：给渲染层加兜底 。现在 preload 缺失时界面会直接报"初始化失败"，并且主进程、渲染层日志统一写进一个 log 文件，还做了 PPMASTER_SELFTEST=1 的无头自检模式，发版前跑一次就知道包健不健康。
坑 2：ELECTRON_RUN_AS_NODE=1 污染。 某些终端环境带着这个变量，Electron 会退化成纯 Node，主进程里 require('electron') 拿到的是个字符串。解法是入口文件第一行 delete process.env.ELECTRON_RUN_AS_NODE。
坑 3：Python 解释器探测。 用户机器上可能有 N 个 Python（官方安装版、商场版、IDE 内置的便携版）。解法是分层探测：设置里指定的 → 各盘 Python* 目录 → PATH → py 启动器，并且每个候选都实际跑一次 import pptx, fitz，优先选依赖齐全的，IDE 内置的运行时降为最后兜底。
坑 4：国内网络。 Electron 二进制从 GitHub 下载必超时，.npmrc 里预置 npmmirror 镜像；上游技能包同步支持 AtomGit 镜像回退；pip 给出清华镜像命令。
怎么用
方式一：绿色包（最简单） ------ 百度网盘：点击打开下载页，提取码 fvmx （完整链接：https://pan.baidu.com/s/1O6DBJdpBENyNhUUdPU_f-w?pwd=fvmx）。解压到任意目录，双击 PPT Master Desktop.exe，不需要安装。
方式二：安装包 ------ 到开源仓库的 Releases 页下载 PPTMasterDesktop-Setup-x.y.z.exe。
方式三：源码 ------ git clone 后 npm install && npm run sync:upstream && npm start，适合想改代码的。
无论哪种方式，都需要：
- 本机装好 Python 3.10+ ，然后执行一次
python -m pip install -r <应用目录>\resources\ppt-master\requirements.txt - 在应用的「⚙ 设置」里填一个 OpenAI 兼容 API Key（默认 Kimi，改成 DeepSeek / GPT 只需要换 Base URL 和模型名）
成本与合规
工具本身完全免费，唯一的成本是模型调用：一份 10 页的 PPT 大约消耗几万到十几万 token，用 Kimi/DeepSeek 大概几毛钱人民币。
协议方面：本项目和上游都是 MIT；但上游的 PDF 解析依赖 PyMuPDF 是 AGPL，如果你要把安装包拿去商用分发，需要评估条款或者去掉 PDF 输入能力。
链接汇总
- 📦 绿色包（百度网盘） ：点击打开下载页 提取码
fvmx（完整链接：https://pan.baidu.com/s/1O6DBJdpBENyNhUUdPU_f-w?pwd=fvmx） - 💻 本项目（PPT Master Desktop） ：https://github.com/wyfirstname/PPT-Master-Desktop
- ⭐ 上游项目（ppt-master，MIT） ：https://github.com/hugohe3/ppt-master
觉得有用的话，去给上游点个 Star，这是它应得的。