# PPtYoda

**Repository Path**: pingtoumou/PPtYoda

## Basic Information

- **Project Name**: PPtYoda
- **Description**: 一个强大的、由 AI 驱动的演示文稿（PPt）自动化生成工具，真正生产化的工具，全流程可控，帮助用户快速制作出符合需求的 PPt。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-09-14
- **Last Updated**: 2025-12-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PPt Yoda - 智能演示文稿生成工具

[![Python Version](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/)
[![Django Version](https://img.shields.io/badge/django-5.2.4-green.svg)](https://www.djangoproject.com/)
[![Next.js Version](https://img.shields.io/badge/next.js-15.3-black.svg)](https://nextjs.org/)

真正生产化的 AI PPt 工具，全流程可控，帮助用户快速制作出符合需求的 PPt。

PPt Yoda 是一个强大的、由 AI 驱动的演示文稿（PPt）自动化生成工具。它旨在解决市面上现有工具内容质量不高、版式僵化、缺乏高级元素（如表格、图表）等痛点。本项目通过结合先进的语言模型、知识库和灵活的模板引擎，实现了从概念到成品的完整自动化、可干预流程。

您可以先通过 [设计理念](#设计理念) 了解本项目的设计理念和核心理念，再决定是否继续。

## 核心功能

PPT Yoda 将整个创作过程流水线化，每一步都支持 AI 辅助和人工微调：

1.  **任务理解与大纲生成**: AI 首先会分析用户的核心目标、受众和场景，生成一个逻辑清晰的演示大纲。
2.  **素材收集与整合**: 系统能够根据大纲，从用户提供的本地文件或知识库中检索、整合相关信息。
3.  **全文内容创作**: 基于大纲和素材，AI 会撰写每一页的详细讲稿，包括文字、数据要点等。
4.  **智能分页与布局**: AI 会根据内容的逻辑层级和信息密度，自动将全文切分成独立的页面。
5.  **模板应用与生成**: 最后，系统会将分页后的内容精确地填充到用户指定的 PPT 模板中，生成最终的演示文稿。

重点功能模块包括：

- **📚 素材管理**: 支持用户对 PPt 相关素材内容进行管理，并提供素材收集任务的管理功能。
- **🤖 内容生成**: 基于强大的语言模型（LLM），可自动生成演示文稿的**大纲**和**逐页讲稿**；支持直接插入模板中的页面或章节。
- **🎨 多媒体生成**：基于多模态大模型，根据材料需求，完成图片、图标等内容的自动生成。
- **🎆 PPt 生成**: 用户可以上传自己的 `.pptx` 文件作为母版，AI 将在此基础上进行内容填充和布局，完美保留原始设计风格。
- **🌐 Web 用户界面**: 提供一个基于 Next.js 的现代化界面，支持多用户管理，每个用户可以创建自己的项目空间，上传素材、选择模板并启动生成任务。
- **🗂️ 项目化管理**: 将每一次演示文稿的创建过程作为一个独立项目进行管理，清晰地追踪从 `想法 -> 素材 -> 大纲 -> 全文 -> 最终PPt` 的每一个阶段。

你也可以通过项目生成的[示例 PPt](docs/PPtYoda介绍.pptx) 直观感受一下效果，或者看一下操作视频，了解一下具体功能:

https://github.com/user-attachments/assets/246649fa-e378-43ec-a8b9-263efb68b106

https://github.com/user-attachments/assets/08c40451-8815-42bd-96dd-501a73a0b133

https://github.com/user-attachments/assets/8ab8ddcc-78bd-4aeb-ae8c-ab6f92bd6562

https://github.com/user-attachments/assets/99a1efb1-3dd5-4fd1-80e8-d9cbb65feb07

https://github.com/user-attachments/assets/cc3190ba-35eb-488e-b4bc-57e90991fc70

## 快速开始

### 环境准备

在开始之前，请确保您的系统已安装以下软件：

- [Git](https://git-scm.com/)
- [Python 3.13+](https://www.python.org/)
- [Node.js](https://nodejs.org/) (包含 npm)
- [uv](https://github.com/astral-sh/uv): 一个极速的 Python 包安装工具。
- [cairo](https://www.cairographics.org/): 一个 2D 图形库，用于处理图标（windows 上可以直接安装编译好的[GTK](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer)）。

### 安装步骤

**a. 克隆仓库**
```bash
git clone https://github.com/maquedexiju/PPtYoda.git
cd PPtYoda
```

**b. 安装后端依赖**
```bash
# 使用 uv 根据 pyproject.toml 安装依赖
uv pip install -e .
```

**c. 安装前端依赖**
```bash
cd frontend
npm install
cd ..
```

**d. 初始化项目**
运行安装脚本来生成配置文件、初始化数据库并导入默认模板。
```bash
# 该脚本会自动创建 config.ini, 初始化数据库, 并创建超级用户
python install.py
```
> 注意：默认存在一个超级用户，用户名: `ppt_killer`，密码: `pt_12345`。

### 配置

**a. 后端配置**
安装脚本会自动从 `config.ini.example` 复制生成 `config.ini` 文件。您需要编辑此文件，填入您的 LLM API 密钥等信息。
```ini
[LLM]
LLM_BASE_URL = ...
LLM_API_KEY = sk-YourAPIKeyHere
LLM_MODEL = ...
...
```

### 启动项目

我们提供了一个便捷的脚本，可以同时启动后端和前端服务。
```bash
python runserver.py
```
启动后：
- 🚀 **后端 Django 服务** 将运行在 `http://localhost:8810`
- 🚀 **前端 Next.js 服务** 将运行在 `http://localhost:3000`

现在，您可以打开浏览器访问 `http://localhost:3000` 开始使用。
您可以通过 `http://localhost:8810/admin/` 进行后台管理，默认用户名 `ppt_killer`，密码 `pt_12345`。

我们创建了一个演示项目，来说明项目的使用方法。

当然真正的使用过程中，通常需要你上传自己的 PPt 模板，关于模板的要求，详见 [自定义模板](#自定义模板)。

## 自定义模板

你可以上传 PPt 材料到模板库当中，随后就可以选择模板来创建项目。上传 PPt 后，程序会读取每一页下方的备注，来判断页面类型。
可以参考 `ppt_templates_files` 目录下的模板，直观了解自定义 PPt 模板的一些基本要求。

### 模板中的页面

基本来说，PPt 模板可以包含三类页面：

* 组件页：用于定义 PPt 中一些可复用的组件，例如目录项、基本的文字样式等
  * 没有在页面备注中添加任何信息的页面，会被认为是组件页。关于组件的概念和使用，详见 [组件与容器](#组件与容器)
  * **注意！** 自定义的模板也必须要 toc 和 text 两个组件，一个用于生成目录，一个用于定义默认文本内容的样式。
* 样式页：用于在PPT生成的过程中给大语言模型作为设计布局的参考依据，例如三模块布局、左右布局等
  * 样式页位于 templates 章节下，或者无章节，需要至少有一行页面备注信息
    * 命名：备注中的第一行为样式页的名称，剩下为样式页的备注信息，用于为大语言模型选择样式提供更多信息。
    * 内容：页面中可以包含多个[占位符](#占位符)，用于定义样式页的内容。
  * **注意！** 模板中必须有以下四种样式页
    * 封面：用于定义 PPt 首页
    * 目录：用于定义目录的样式
    * 一级章节：用于定义一级章节的样式
    * 二级章节：用于定义二级章节的样式
    * 空白：用于定义空白页的样式
* 预置内容：作为可复用的内容，直接插入到制作的 PPt 当中，例如公司介绍、成员介绍等
  * 预置内容需要放到 PPt 的“章节”中
  * 创建章节的方法可以参考：找到想要分节的第一张幻灯片，点击其左侧的缩略图将其选中。接着，在 “开始” 选项卡下，找到 “幻灯片” 组，点击 “节” 按钮，在下拉菜单中选择 “添加节”。新节创建后会自动命名为 “无标题节”，右键点击节名可进行重命名。

### 占位符

什么是占位符？占位符是一种特殊的标记，占位符可能会出现在组件或者样式页中，但是在组件页中，用于在 PPt 模板中表示一个位置，在大语言模型生成 PPt 时，会根据在占位符的位置填充内容。

`@title` 就是一个占位符，`@img-block_icon：模块 1 的图标` 也是一个占位符。占位符的定义方法很容易理解，具体规则如下：

* 占位符的标识与命名：，占位符以 `@` 标志开头，例如 `@title` 就是名称为 `title` 的占位符，占位符的命名不能出现空格或中划线。
* 占位符的类型：需要在占位符的名称前添加类型，用 `-` 隔开，例如 `@img-title` 就是类型为 `img` 的占位符，默认占位符类型为 text 目前占位符的类型包括：
  * `text`：文本占位符
  * `img`：图片占位符
  * `icon`：图标占位符，从图标库中选择图标
  * `diy`：自定义占位符，生成 PPt 时，会根据需要，自主选择填充类型
  * `container`：容器占位符，详见下一节介绍
* 占位符的描述：如果你希望给占位符添加一些描述，例如占位符支持的字符数、占位符大小等信息，可以在占位符名称后增加，中间用 `:` 隔开，例如 `@text-block1：容纳 60-80 个字`，就会提醒大语言模型，尽量以 60-80 个字符填充这个占位符。
* 占位符样式：主要用于 `container` 类型的占位符，见下一节内容。

### 组件与容器

想要理解组件，最简单的方法就是通过案例模板中的 toc 组件。

在生成 PPt 目录时，我们需要在目录页插入若干个“目录项”，每个目录项可能有多个内容块，同时目录项的数量也是不固定的。

所以我们把“目录项”抽象为组件，这是一个预置的内容块，可以在页面中插入多次，具体插入次数可以由大语言模型决定。
组件的定义需要一个 group（编组）形状，group 下仅包含两个元素：

* 一个是组件的名称，是一个文本框或形状，内容需要以 `#` 开头，后面跟随组件名称，例如 `#toc` 就表示目录组件。
* 一个是组件的内容，一般是一个 group，其中一般包含了一个或多个[占位符](#占位符)

组件需要插入到容器（即 container 类型占位符）中。container 一般是一个矩形的形状，并且需要为 container 中的组件插入形式定义布局模式，我们仍以目录举例：

我们定义了一个目录组件，目录组件的名称为 `#toc`，目录组件的内容是一个 group，group 下包含了 `@number` 和 `@title` 两个占位符，以及修饰性的背景矩形。

同时我们创建了一个“目录”样式页，样式页中插入了一个矩形，并添加文字 `@container-toc(max_n-6 direction-l-r align-c valign-c gap-10)：目录容器`，这个矩形就是我们定义的目录组件的容器。

我们看到这个容器定义有 4 个部分的内容：

* `@conatianer`：声明这是一个容器类型的占位符（固定）
* `toc`：容器名称，必须和组件名称一致
* `max_n-6 direction-l-r align-c valign-c gap-10`： 括号里的这部分定义了容器内组件的布局模式
  * `max_n-x`：表示容器最多包含 x 个组件
  * `direction-l-r`：表示容器内组件的布局方向为从左到右，也可以是 `t-b`，表示从上到下
  * `align-c`：表示容器内组件水平居中对齐方式，包括 `c` 居中、`l` 左对齐、`r` 右对齐、`j` 两端对齐
  * `valign-c`：表示容器内组件垂直居中对齐方式，包括 `c` 居中、`t` 顶部对齐、`b` 底部对齐、`j` 两端对齐
  * `gap-x`：表示容器内组件之间的最小间距为 x 个单位
* `目录容器`：给大语言模型提供信息的备注

按照上述的方法，你就可以定义自己的组件，并在样式页中通过 `container` 占位符，进行组件的插入。

## 使用指南

### 图片生成

现阶段通过 AI 进行图片生成依然是一个比较有挑战的事情，尤其是直接通过 AI 为图片设置合适的描述，并一次性生成可用的图片。

以目前专业 AI 生成工具的交互模式，通常也是通过多轮对话来完成的。

所以我们也提供了类似的交互方式，兼顾便利性、效率和质量：

* 首先，我们会把图片进行编号，这个编号会像蒙版一样遮挡在生成的图片上方，对于刚刚生成的图片，编号后面会有一个 `-g` 标记
* 其次，我们会把相应编号的 prompt 放到幻灯片下方的备注框里，包裹在 `@img-编号` 和 `@endimg` 之间，记得这两个标记都是需要独占一行的
* 当完成一次素材生成后，你可以对不满意的图片进行如下操作：
  * 根据需要，修改备注框中的 prompt
  * 去掉 `-g` 标记，告诉我们的程序，这是一张需要重新生成的图片
* 当所有素材都完成了标记和调整后，可以将 ppt 保存，并上传给我们的程序，程序会对没有 `-g` 标记的图片进行重新生成

当然这依然非常考验你的 prompt 编写能力。

### 图标生成

现阶段大语言模型生成 svg 图标的能力非常拉胯，尤其是细节很多的图标，生成的图标 95% 都是无法直接使用的。

因此针对图标，我们仍然选择了让模型从现成图标库中选择的模式，而不是直接生成 svg 图标。


当前，项目没有针对单个用户提供图标库，而是使用了一个公共的图标库，所有用户都可以使用这个图标库（即位于 `icons` 目录下的图标）。

如果用户有自己的图标库，也可以把图标库放到 `icons` 目录下，程序会根据图标库中的图标名称，进行匹配。


图标其实很难覆盖所有场景需求，所以当生成 PPt 时，如果我们的程序没有找到对应的图标，会在 icon 的位置保留一个矩形，并把图标建议的搜索关键词放到矩形中。

您可以找到图标后直接进行替换，或者把图标添加到 `icons` 目录下，重新生成素材时，程序会自动识别并使用（你不需要关注 `info.json` 文件）。

## AI 空间小助手

在进行素材收集和内容创作的过程中，通常需要多轮对话交互，甚至是需要联网进行信息检索，我们没有在项目中集成多轮对话功能，因为想要做好相关的功能确实需要投入大量精力。

所以我们用了一个讨巧的小办法——借助成熟的 AI 对话平台，来完成多轮对话交互。例如 DeepSeek、ChatGPT、豆包等，而我们要做的则是想个办法，把 AI 对话平台上生成的内容快速收集到我们的平台上。
因此我们提供了类似油猴脚本的方式，本地启动一个浏览器，并支持在打开页面时进行一些简单的 JS 注入，从而快速完成文本内容的复制和收集。

在项目的 `materials/tools` 目录下，我们提供了若干个助手，你可以：

* 参考 `doubao_launcher.py` 这个文件，来了解如何编写一个 AI 空间的启动和程序注入小助手
* 参考 `doubao_helper.js` 了解素材收集脚本的编写
* 参考 `doubao_fulltext_edit.js` 了解页面全文内容编辑的脚本编写方式

## 设计哲学

### 为什么开始这个项目

我试用了非常多市面上用于生成 PPt 的工具，目前市面上的生成工具往往都有一些问题：

1. 内容质量不高：缺少细节和必要内容，乍一看内容还挺多，尤其是文件大纲目录比我想的还要完整，但是实际的内容质量不高。
2. 缺少必要的元素：比如图片、图表、表格、公式等，这些元素对于 PPt 的展示效果非常重要。
3. 版式固定：基本都只有“三段论”、“四段论”、“标题”等几种版式，无法满足不同主题的需求。
4. 字体和母版有问题：虽然有的工具支持自行上传母版，但通过 AI 编辑后的 PPt，会丢失母版信息，同时自己也会出现字体问题。
5. 生成 的 PPt 无法下载，只能在浏览器中查看，本地下载的只能是 PDF。

所以我决定自己写一个 PPt 生成工具，来解决这些问题。

### 设计理念

我希望我的 PPt 生成工具能够满足以下几个方面的需求：

1. 内容质量高：通过 AI 生成的 PPt，内容质量高，细节丰富，符合我的需求。
2. 元素丰富：支持图片、图表、表格、公式等元素，能够满足不同主题的需求。
3. 版式灵活：支持自定义版式，能够满足不同主题的需求。
4. 字体和母版问题：支持上传母版，能够解决字体和母版问题。
5. 生成 的 PPt 可以下载，也可以通过浏览器预览，兼容 PPt 的同时，支持一些 JS 动画。

### 如何理解 PPt 创作的过程

相比于平铺的内容，PPt 的优势在于适配屏幕尺寸，给出更好的排版，通过动画等方式更加形象地展示内容。

所以我们可以简单地把 PPt 创作拆解成两个过程：

`内容创作`+`PPt 布局`

* 关于`内容创作`，和基本 AI 创作的模式是一致的，最后应该形成具有良好层级结构的内容，包含表格、图表和图片，markdown 或者 json 都是不错的承载形式。
* 而 `PPt 布局`则需要考虑 PPt 的特有属性，把平铺的内容拆分成一个一个的页面，根据页面内容添加必要的图片、动画，根据内容的多少、元素之间的关系进行合理布局。

### AI 创建 PPt 的过程

1. 了解任务背景：首先明确 PPt 演示的主题、受众、场合、时长等基本信息，并明确通过材料希望达成的目标等。
2. 确定内容大纲：根据任务背景，分为哪些具体的章节，每个章节希望达到什么目的。注意这个“内容大纲”和“PPt大纲”并不等同。内容大纲更关注内容，而 PPt 大纲更关注 PPt 的结构。
3. 素材与信息收集：收集信息的方式，可以包括网络数据检索，本地现有材料挖掘，或者自行创作等。
4. 完成内容创作：根据内容大纲，结合收集到的信息，完成内容创作，包括文字、列表、图表、表格、公式等，确保内容的质量和准确性。
5. 进行内容分页：根据内容创作的结果，综合考虑信息层级、内容字数等，对内容进行“分页”
6. 完成页面设计：完成“分页”后，对每一页的内容进行分析，选择合适的布局，并添加必要的图片、动画等，确保 PPt 的质量和效果。
7. 完成素材创作：材料中存在大量的图片、图表、表格、公式等，需要根据页面内容，对这些素材进行创作。

其中 1-4 是内容创作的过程，可以由 AI 辅助；5-6 是 PPt 布局的过程；7 是素材创作的过程。

值得注意的是：

* 在真实的场景下，2、3、4 步骤实际上是一个穿插的过程，当我们收集了一定的素材，我们可能会希望重新调整大纲，或者给每一页做内容调整。
* 理论上步骤 5、6 的过程中，也可能不仅包括内容的删除和重组，可能也会为了页面的需求，增加一部分新的内容，但目前我们先不考虑。

### AI 和人应该是协同的

在实际的任务重，每一步都可以借助 AI 的能力来完成，也可以由人来完成，或根据之前的历史经验来确认。

例如某些场景下，已经规定了自己的 PPt 大纲框架，例如内部汇报、解决方案材料等，那么直接使用现成的大纲即可。

因此，根据创建 PPt 的过程，每一步都可以形成一个独立的任务，交给 AI 来完成，同时支持人工监督或信息补充。形成格式化的成果，并供下一个任务使用。

## 待办清单

* [ ] 多语言与国际化
* [ ] 支持更多 LLM 供应商
* [ ] 多媒体与素材管理
  * [ ] 提供浏览器插件，快速从网站中获取素材
  * [ ] 支持通过 MCP 服务，从对话内容中提取素材
  * [ ] 支持知识库对接和素材生成
  * [ ] 支持通过本地文件上传形成素材
  * [ ] 支持图片素材的管理
  * [ ] 支持 svg 图标的管理
* [ ] 内容创作
  * [ ] 支持插入表格
  * [ ] 提升框架图生成质量
  * [ ] 支持段内的加粗、强调等样式

## 项目结构

```
/
├── frontend/                   # Next.js 前端项目
├── ppt_template/               # Django App: PPt 模板管理
├── users/                      # Django App: 用户管理
├── project_manage/             # Django App: 项目管理
├── materials/                  # Django App: 素材管理
├── ppt_page/                   # Django App: PPt 页面内容管理
├── knowledge_base/             # Django App: 知识库管理（待开发）
├── ppt_killer/                 # Django 主项目配置
├── prompts/                    # 存放用于与 LLM 交互的 Prompt 模板
├── ppt_templates_files/        # 存放示例 PPt 模板文件
├── install.py                  # 初始化安装脚本
├── runserver.py                # 一键启动脚本
└── pyproject.toml              # Python 项目配置与依赖
```

## 贡献指南

> 我们欢迎任何形式的贡献！您可以：
> 1.  Fork 本仓库
> 2.  创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
> 3.  提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
> 4.  推送到分支 (`git push origin feature/AmazingFeature`)
> 5.  开启一个 Pull Request

## 许可证

本项目基于 MIT 许可证开源，您可以在遵守许可证条款的前提下自由使用、修改和分发本项目的代码。