# PPT-Master-Desktop

**Repository Path**: devai/PPT-Master-Desktop

## Basic Information

- **Project Name**: PPT-Master-Desktop
- **Description**: PPT-Master的桌面版
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://www.cnblogs.com/wyang/p/23539934
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-04
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PPT Master Desktop

把开源项目 [hugohe3/ppt-master](https://github.com/hugohe3/ppt-master)（MIT）的「AI 生成 PPT」能力，做成一个**双击即用的 Windows 桌面应用**：不用配 Claude Code / Cursor 之类的 AI 编程工具，选文件 → 选风格 → 点生成，直接拿到**原生可编辑的 .pptx**。

输出的是真正的 PowerPoint 对象（形状、文本框、表格、图表），每一页都能在 PowerPoint 里点开修改，不是截图拼图。

> 支持输入：PDF / DOCX / PPTX / XLSX / EPUB / Markdown / 网页链接 / 直接粘贴文本

## ⬇️ 直接下载（免安装绿色包）

- **百度网盘（绿色包，免安装）**：[点击下载](https://pan.baidu.com/s/1O6DBJdpBENyNhUUdPU_f-w?pwd=fvmx) 　提取码：**`fvmx`**
  `https://pan.baidu.com/s/1O6DBJdpBENyNhUUdPU_f-w?pwd=fvmx`
- **GitHub Releases（安装包）**：[PPTMasterDesktop-Setup-x.y.z.exe](https://github.com/wyfirstname/PPT-Master-Desktop/releases)

下载绿色包 → 解压到任意目录 → 双击 `PPT Master Desktop.exe`，**不需要 Node、不需要编译**。只差一步 Python 依赖安装，详见 [安装方式一](#安装方式一下载绿色包普通用户)。

---

## 目录

- [功能特性](#功能特性)
- [系统要求](#系统要求)
- [安装方式一：下载绿色包（普通用户）](#安装方式一下载绿色包普通用户)
- [安装方式二：从源码运行（开发者）](#安装方式二从源码运行开发者)
- [安装方式三：自己打包安装包](#安装方式三自己打包安装包)
- [首次配置：填 API Key](#首次配置填-api-key)
- [使用流程](#使用流程)
- [数据存放位置](#数据存放位置)
- [目录结构](#目录结构)
- [自动升级与发版](#自动升级与发版)
- [常见问题](#常见问题)
- [许可](#许可)

---

## 功能特性

- **原生可编辑 PPTX**：基于 Office Open XML / DrawingML 生成真实形状与文本，保留母版与版式继承
- **向导式界面**：4 步流程（选源材料 → 选风格/画布/页数 → 生成 → 预览导出），不需要写提示词
- **14 种内置风格**：MBB 咨询、学术答辩、产品发布、投资人路演、科技极简、政务汇报等，直接读上游 styles 规范注入模型
- **质量门禁**：每页 SVG 先过上游 `svg_quality_checker.py`，不合格的页面自动回炉让模型修复（最多 3 轮）后再导出
- **多画布**：16:9 / 4:3 等，可在设置里切换
- **数据本地化**：文档解析、PPTX 导出全在本机完成，只有文本片段发给模型 API
- **自动升级**：内置 `electron-updater`，接 GitHub Releases，启动时检查并一键更新
- **任意 OpenAI 兼容模型**：Kimi / DeepSeek / GPT / 本地 vLLM 都能用，只改 Base URL 和模型名

---

## 系统要求

| 项目 | 要求 | 说明 |
|---|---|---|
| 操作系统 | Windows 10 / 11 x64 | 目前只出 Windows 构建；源码本身跨平台，macOS/Linux 需自行 `electron-builder` 打 |
| Node.js | **18 或以上** | 仅从源码运行 / 打包时需要，装安装包的用户不需要 |
| Python | **3.10 – 3.13（含 pip）** | 必装，安装时记得勾选 *Add python.exe to PATH* |
| Git | 任意版本 | 仅源码运行 / 同步上游技能包时需要 |
| 网络 | 能访问模型 API | 国内网络建议按下面的镜像说明配置 |
| 硬盘 | 约 1.5 GB | 依赖 + 内置技能包（图标/字体素材约 64 MB） |
| 大模型 API Key | 必需 | 生成大纲和每页设计都要调模型 |

检查你的环境：

```bash
node -v          # 需 >= v18
python --version # 需 3.10 ~ 3.13
git --version
```

---

## 安装方式一：下载绿色包（普通用户）

**不用装 Node、不用打包、不用会写代码。** 直接下免安装绿色包，解压双击就能用：

> **⬇️ 绿色包下载（百度网盘）**
> 链接：[https://pan.baidu.com/s/1O6DBJdpBENyNhUUdPU_f-w?pwd=fvmx](https://pan.baidu.com/s/1O6DBJdpBENyNhUUdPU_f-w?pwd=fvmx)
> 提取码：**`fvmx`**

1. 打开上面链接，下载压缩包并解压到任意目录（建议放非系统盘，例如 `D:\Apps\PPT Master Desktop`，解压后约 300 MB）
2. 双击目录里的 **`PPT Master Desktop.exe`** 启动（免安装，不写注册表，删目录即卸载）
3. **首次使用还需装一次 Python 依赖**（绿色包里不含 Python 运行时，请先确保装了 Python 3.10+）：

```bash
python -m pip install -r "<解压目录>\resources\ppt-master\requirements.txt"
```

> 国内网络可加镜像加速：`python -m pip install -r "<解压目录>\resources\ppt-master\requirements.txt" -i https://pypi.tuna.tsinghua.edu.cn/simple`

4. 启动应用 → 右上角「⚙ 设置」→ 填 API Key（见[首次配置](#首次配置填-api-key)）

> 绿色包也是可以自动升级的：应用启动时会检查 GitHub Releases，有新版本会提示一键更新。
> 如果你的网络下不了百度网盘，用下面的安装包或源码方式。

### 备选：NSIS 安装包

1. 打开仓库的 [Releases](https://github.com/wyfirstname/PPT-Master-Desktop/releases) 页，下载最新的 `PPTMasterDesktop-Setup-x.y.z.exe`
2. 双击安装（可以改安装目录，默认装在用户目录下，不需要管理员权限）
3. 同样需要执行第 3 步的 Python 依赖安装，路径为 `<安装目录>\resources\ppt-master\requirements.txt`
4. 启动应用 →「⚙ 设置」→ 填 API Key

两个渠道都没有现成包时，按[安装方式三](#安装方式三自己打包安装包)自己打一个。

---

## 安装方式二：从源码运行（开发者）

```bash
# 1. 克隆
git clone https://github.com/wyfirstname/PPT-Master-Desktop.git
cd PPT-Master-Desktop

# 2. 安装 Node 依赖（Electron 二进制较大，国内网络请确保 .npmrc 里的镜像生效）
npm install

# 3. 拉取上游 ppt-master 技能包到 vendor/ppt-master（约 64 MB，不打进本仓库）
npm run sync:upstream

# 4. 安装 Python 依赖
python -m pip install -r vendor/ppt-master/requirements.txt
# 国内加速：python -m pip install -r vendor/ppt-master/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 5. 启动
npm start
```

**关于镜像**：仓库自带 `.npmrc`，已把 Electron 二进制指向 npmmirror（国内直连 GitHub 下不下来的常见报错就是这里）。海外网络可以删掉 `.npmrc` 或改成官方源。

**`npm run sync:upstream` 做了什么**：浅克隆上游仓库到 `.upstream-cache/`，再把 `skills/ppt-master` 复制到 `vendor/ppt-master`。再次执行即更新到上游最新版本。GitHub 不通时会自动回退到 AtomGit 镜像（`atomgit.com/hugohe3/ppt-master`）。

---

## 安装方式三：自己打包安装包

```bash
npm run dist     # 产出 dist/PPTMasterDesktop-Setup-0.1.0.exe（NSIS 安装包）
npm run pack     # 只产出免安装目录 dist/win-unpacked/，调试用
```

打包前确认 `vendor/ppt-master/` 已存在（否则内置技能包为空，应用会报“未找到技能目录”）。

---

## 首次配置：填 API Key

打开应用后点右上角「⚙ 设置」：

| 字段 | 说明 | 示例 |
|---|---|---|
| API Base URL | OpenAI 兼容端点 | `https://api.moonshot.cn/v1` |
| API Key | 你的密钥 | `sk-...` |
| 模型 | 模型名 | `kimi-k3` / `deepseek-chat` / `gpt-4.1` |
| Python 路径 | 留空自动探测 | `C:\Python313\python.exe` |
| 项目输出目录 | 留空用默认目录 | `D:\PPTMaster\projects` |

常见组合：

```text
Kimi       https://api.moonshot.cn/v1        kimi-k3
DeepSeek   https://api.deepseek.com/v1       deepseek-chat
OpenAI     https://api.openai.com/v1         gpt-4.1
本地 vLLM  http://127.0.0.1:8000/v1          <你的模型名>
```

设置保存在 `%PPMASTER_HOME%\appdata\settings.json`（默认 `%USERPROFILE%\PPTMaster\appdata\settings.json`），API Key 只存本机、不加密，请勿把该文件提交到任何仓库。

---

## 使用流程

1. **选择源材料**：拖入 PDF / DOCX / XLSX / Markdown / 网页链接，或直接粘贴文本
2. **选择风格**：风格模板 + 画布比例 + 页数
3. **点击生成**：日志实时滚动，依次执行「解析源材料 → 生成大纲 → 逐页设计 SVG → 质量检查 → 导出 PPTX」
4. **预览导出**：生成完成后可直接打开 PPTX 或定位到项目文件夹（含每页 SVG 源码，便于二次修改）

一次生成的成本主要来自模型调用：页数越多、修复轮次越多，token 越多。

---

## 数据存放位置

默认根目录 `~/PPTMaster`（Windows 即 `C:\Users\<你>\PPTMaster`）。想放到别的盘（比如 C 盘紧张），**设置环境变量 `PPMASTER_HOME` 即可**，重启应用生效：

```powershell
[Environment]::SetEnvironmentVariable('PPMASTER_HOME', 'D:\PPTMaster', 'User')
```

```text
<PPMASTER_HOME>
├── appdata\    # 设置、Electron 缓存（settings.json 在这里）
└── projects\   # 每次生成一个 proj-<时间戳> 文件夹：svg_output\*.svg + notes\ + 最终 pptx
```

日志写在 `%TEMP%\pmd.log`（启动链路、渲染层错误、Python 解析结果都会记录），排查问题先看它。

---

## 目录结构

```text
main/                 主进程
├── main.js           应用入口、窗口、IPC、启动自检
├── pipeline.js       编排管线：源→MD→大纲→SVG→质量检查→PPTX
├── llm.js            OpenAI 兼容 API 客户端（流式、重试）
├── store.js          设置持久化
├── paths.js          所有路径推导（PPMASTER_HOME / 临时目录）
└── updater.js        electron-updater 自动升级
renderer/             渲染进程（原生 JS，无框架）
├── index.html        4 步向导界面
├── css/app.css
└── js/app.js
preload.js            contextBridge 暴露的安全 API
scripts/
└── sync-upstream.mjs 拉取上游技能包到 vendor/
vendor/ppt-master/    上游技能包（不提交，由 sync:upstream 生成）
```

技术栈：Electron 33 + 原生前端 + Python 3（上游脚本）。LLM 只负责“想”（大纲、每页 SVG），Python 负责“做”（文档解析、SVG→PPTX 转换），这是它能输出原生可编辑 PPT 的关键。

---

## 自动升级与发版

应用用 `electron-updater` 检查本仓库的 GitHub Releases。发新版：

```bash
# 1. 改 package.json 的 version
# 2. 配置 GitHub Token（需要 repo 写权限）
set GH_TOKEN=ghp_xxx
npm run dist
npx electron-builder --publish always
```

产物里的 `latest.yml` 与 `*.blockmap` 必须一起上传，旧版本客户端才能校验并增量下载。设置里关掉「启动检查更新」可跳过检查。

---

## 常见问题

**界面一直显示“检测中...”**
渲染层没拿到主进程信息，通常是自己改过 `package.json` 的 `build.files` 白名单，把 `preload.js` 漏掉了。`preload.js` 必须在白名单里，改完重新 `npm run pack`。

**提示“Python 依赖缺失”**
探到的解释器没装 `python-pptx` / `PyMuPDF`。应用会依次探测「设置里的路径 → 各盘 Python 安装目录 → PATH → py 启动器」并优先选依赖齐全的那个。也可以直接在设置里手动指定 `python.exe` 绝对路径。

**`npm install` 卡住或 Electron 下载失败**
国内网络访问 GitHub Releases 会超时。确认 `.npmrc` 里的 `electron_mirror` 生效，或手动执行：

```powershell
$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
npm install
```

**`npm run sync:upstream` 克隆失败**
GitHub 被墙时脚本会自动切 AtomGit 镜像；两个都不通就手动下载上游 zip，把其中的 `skills/ppt-master` 整个复制到 `vendor/ppt-master`。

**生成到一半报 SVG 质量检查不通过**
这是上游的门禁在拦截不合规 SVG（用了 `<foreignObject>`、`mask`、外部 CSS 等）。应用会自动把问题回传给模型重写，最多 3 轮；仍失败时保留项目目录，可打开 `validation/svg_quality_report.json` 看具体是哪条规则。

**想验证打包产物是否健康（不弹窗）**

```powershell
$env:PPMASTER_SELFTEST="1"
& "dist\win-unpacked\PPT Master Desktop.exe"
# 结果写入 %TEMP%\pptmaster-selftest.json
```

输出包含 `skillDir`、`python`、`pythonDeps`、`styles`、`preload`、`projectsDir`，任意一项异常即为该产物不合格。

---

## 许可

本项目 MIT。上游 [ppt-master](https://github.com/hugohe3/ppt-master) 亦为 MIT，需保留其署名。

⚠️ 注意：上游依赖里的 **PyMuPDF 是 AGPL-3.0**（PDF 解析用）。若要把安装包用于商业分发，请先评估 AGPL 条款，或去掉 PDF 输入能力（移除 `fitz` 依赖）。