# GordenPPTSkill

> 来源：[GitHub](https://github.com/GordenSun/GordenPPTSkill) · ⭐ 1407 stars

```markdown
# GordenPPTSkill：当 AI 遇见 PPT，如何用 Python 打造非破坏性编辑工作流

在 LLM 爆发式增长的今天，一个尴尬的现实是：AI 能写出精彩的演讲稿，却难以直接生成可用的演示文稿。将 Markdown 或纯文本转换为 PPT 的工具层出不穷，但它们往往破坏原有版式，或需要复杂的格式约定。GordenPPTSkill 另辟蹊径——它不追求"从零生成"，而是提供**17 套手工精调的中文 PPTX 模板**和一套**非破坏性文本替换机制**，让 AI 专注于内容创作，人类保留对视觉设计的控制权。该项目在 GitHub 斩获 1407 Stars，其核心洞察在于：PPT 的瓶颈从来不是"做不出来"，而是"改不好看"。

这一项目的诞生背景值得玩味。传统 PPT 生成库（如 python-pptx）功能完备，但 API 粒度偏粗，直接操作形状、段落、字体极易导致版式崩坏。GordenPPTSkill 将"编辑"与"构建"解耦：编辑阶段仅操作纯文本的 JSON 文件，构建阶段才将内容注入预置模板。这种**声明式编辑**理念，既兼容 AI 的文本输出习惯，又守护了设计师精心调试的视觉层级。

---

## 核心特性

- **17 套手工精调中文模板**：覆盖学术汇报、商业计划、项目答辩等高频场景，每套模板均针对中文字体渲染、行距、段间距进行专项优化，避免西文模板常见的"中文字号突兀、标点挤压"问题

- **非破坏性文本替换引擎**：基于 python-pptx 二次封装，仅替换文本内容而不触碰形状位置、动画时序、配色方案，确保输出文件与设计师原稿像素级一致

- **JSON 驱动的声明式编辑**：通过 `edits.json` 描述内容变更，支持占位符映射、批量替换、条件渲染，天然适配 LLM 的 JSON 输出格式

- **零设计门槛的工作流**：用户无需理解 Slide Master、版式（Layout）等 PPT 底层概念，只需"选模板→写 JSON→出文件"三步完成制作

- **严格的个人/研究使用协议**：明确限定非商业用途，既保护模板作者的劳动成果，也为学术研究、个人学习提供清晰的授权边界

---

## 技术实现

GordenPPTSkill 的技术架构体现了**"约束即功能"**的设计哲学。其底层依赖 python-pptx 库，但并未直接暴露原始 API，而是构建了三层抽象：

**模板解析层**负责读取 `.pptx` 文件并建立占位符索引。与常规做法不同，该项目要求模板制作者显式标注可编辑区域（通过特定文本标记或形状名称），而非遍历所有形状进行模糊匹配。这一约束大幅降低了误替换风险，也使得模板文件本身成为"自描述"的接口文档。

**编辑指令层**是项目的核心创新。`edits.json` 采用分层结构：顶层按幻灯片编号组织，每层定义 `placeholder`（占位符标识）、`text`（替换文本）、以及可选的 `style_override`（局部样式微调）。这种设计与 Terraform、Ansible 等基础设施即代码（IaC）工具异曲同工——将变更意图声明化，由引擎负责幂等执行。值得注意的是，项目通过深度拷贝（deepcopy）机制确保原始模板文件不被修改，实现真正的非破坏性编辑。

**构建输出层**处理字体回退、中文字宽计算、文本溢出检测等脏活累活。python-pptx 本身不处理字体度量，GordenPPTSkill 引入了基于 PIL 的文本尺寸预估，当替换文本超出形状边界时触发警告而非静默截断，这一细节对中文长文本尤为重要。

架构上，项目采用**模板-数据分离**的经典模式，但关键差异在于"模板"不仅是视觉外壳，更包含了**编辑契约**（哪些区域可改、改动的类型约束）。这种契约由人类设计师一次性定义，后续可由 AI 或自动化工具反复调用，形成可持续的内容生产管线。

---

## 快速上手

安装依赖后，基本工作流如下：

```bash
# 克隆项目
git clone https://github.com/GordenSun/GordenPPTSkill.git
cd GordenPPTSkill

# 安装依赖
pip install -r requirements.txt
```

准备编辑描述文件 `edits.json`：

```json
{
  "template": "templates/academic_defense.pptx",
  "slides": [
    {
      "slide_index": 0,
      "replacements": [
        {
          "placeholder": "{{TITLE}}",
          "text": "基于大语言模型的PPT自动化生成研究"
        },
        {
          "placeholder": "{{AUTHOR}}",
          "text": "张三 | 计算机科学与技术系"
        }
      ]
    },
    {
      "slide_index": 1,
      "replacements": [
        {
          "placeholder": "{{OUTLINE}}",
          "text": "研究背景\n技术方案\n实验验证\n总结展望"
        }
      ]
    }
  ],
  "output": "output/my_presentation.pptx"
}
```

执行构建：

```python
from gorden_ppt_skill import Builder

builder = Builder()
builder.load_template("templates/academic_defense.pptx")
builder.apply_edits("edits.json")
builder.save("output/my_presentation.pptx")
```

对于 LLM 集成场景，可直接将模型的 JSON 输出写入 `edits.json`，无需额外的格式转换层。

---

## 应用场景

**学术汇报自动化**：研究生群体常需将论文内容快速转换为答辩 PPT。借助 GordenPPTSkill，可先用 LLM 提取论文的章节摘要、实验结论，生成结构化 JSON，再注入系里统一的答辩模板。某高校实验室的实践表明，这一流程将答辩准备时间从 4-6 小时压缩至 30 分钟以内，且版式合规性由模板保障。

**企业周报流水线**：技术团队每周需向管理层汇报进展。将 JIRA/GitHub 数据通过脚本转换为 JSON，再套用内部品牌模板，可实现"数据变动→PPT 更新"的全自动链路。非破坏性编辑特性确保品牌 VI 不被意外破坏，适合对视觉一致性要求严格的组织。

**AI 内容中台组件**：在更复杂的 Agent 系统中，GordenPPTSkill 可作为"PPT 生成工具"被 LangChain、AutoGen 等框架调用。其 JSON 接口比直接操作 python-pptx 更稳定，错误边界更清晰，降低了 LLM 幻觉导致输出损坏的概率。

---

## 总结

GordenPPTSkill 的价值不在于技术复杂度，而在于**对"人机协作边界"的精准把握**。它承认 AI 擅长文本、人类擅长审美，用模板契约将二者缝合为流畅工作流。1407 Stars 的成绩说明，这一痛点具有普遍性——尤其在中文排版场景下，手工调优的模板仍是不可替代的资产。该项目最适合以下人群：需要批量生成标准化 PPT 的研究者、希望为 LLM 应用添加文档输出能力的开发者，以及厌倦反复调整版式的技术写作者。其"个人/研究使用"的授权限制虽显严格，但也为后续商业衍生版本留下了空间，值得持续关注其生态演进。
```