# pptx-builder

**Repository Path**: zdsiyan/pptx-builder

## Basic Information

- **Project Name**: pptx-builder
- **Description**: ppt生成器skill，特别针对国内常用的带有矩形框的业务域设计，通过上下文自动生成，并支持PPT二次编辑。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pptx-builder
生成PPT项目方案的skill，针对中国传统信息化系统的技术架构、业务架构图有适配。本人开发环境为Windows+WPS+LibreOffice+Python, 其他环境没测试过。

**用一份 JSON 生成整套可编辑的 PPT** —— 内置干净默认主题，不依赖任何外部模板文件。

面向 AI Agent（CodeBuddy / Claude Code / Cursor 等）设计的 Skill：把对话上下文、需求、大纲直接变成 `.pptx`，输出的是原生文本框、形状和表格，可以继续在 PowerPoint / WPS 里改。

![预览](docs/preview.png)

> 上图为 `pptx-builder/test/specs/01_project_report.json` 的实际渲染结果（**通用示例内容，非真实项目**；含封面 / 目录 / 章节页 / KPI / 卡片 / 流程 / 表格 / 结尾）。
> 仓库内所有示例内容均为**虚构**，仅用于演示版式。

---

## 解决的问题

让 AI 生成 PPT 的常见做法是「写 python-pptx 脚本」或「套一个模板文件」，前者每次都要重写排版代码、质量不稳定，后者强依赖模板存在且结构固定。

这个 Skill 把**版式逻辑固化成脚本**、把**内容交给 JSON 规格**，于是：

- 内容与排版解耦：AI 只需要产出结构化内容，不需要关心坐标和字号
- 质量可复现：同一份规格在任何机器上生成的结果一致
- 生成后强制自检：渲染成图逐张核对，避免"文字溢出/元素重叠"却看不见

## 特性

- **18 种版式 + 1 套通用图形引擎**（52 个类型名，含别名）：封面、目录、章节页、要点、卡片、指标、流程图、泳道图、时间轴、分层架构图、拓扑图、集成关系图、**通用图形（`diagram`）**、表格、双栏、对比、图文、金句、结尾、空白
- **图形能力分两层**：
  - **通用引擎 `diagram`** —— 任意嵌套容器 + 5 种自动布局（`row`/`col`/`grid`/`radial`/`manual`）+ 自动路由连线（`straight`/`elbow`/`curve`）+ 100 余种形状 + 自定义多边形。配套《选型方法论》《40+ 惯用式图鉴》《引擎字段参考》三份文档，可按业务现场拼装任意架构图
  - **四个高频快捷预设** —— `arch` 分层框图、`swimlane` 泳道图、`topology` 部署拓扑、`hub` 集成关系图，内容完全吻合时可省事
  - 全部用形状与连接线绘制，不依赖 mermaid 之类的外部渲染
- **纯代码默认主题**：深蓝 + 琥珀配色，16:9，统一页眉（标题 + 强调线）与页脚（分隔线 + 页码），开箱即用
- **主题可覆盖**：一条 `theme_overrides` 换配色 / 字体 / 版心 / 页脚
- **中文字体正确处理**：显式写入 `latin` / `ea` / `cs` 三处 typeface，避免中文回落到宋体导致字体不一致
- **轻量富文本**：`**加粗**`、`<c>强调色</c>`
- **自动适配**：要点过多自动压缩字号与行距，步骤过多自动转竖向，图片缺失自动降级为纯文本排版
- **零模板依赖**：不需要 `template.pptx`
- **内置自检闭环**：`render_preview.py` 自动调用本机 WPS / PowerPoint / LibreOffice 渲染为逐页 PNG

## 页面类型

| 类型 | 用途 | 关键字段 |
|---|---|---|
| `cover` | 封面 | `title` `subtitle` `tag` `author` `date` `org` |
| `toc` | 目录 | `items` `columns` |
| `section` | 章节过渡 | `index` `title` `subtitle` |
| `bullets` | 并列要点 | `items[]`（支持 `level`）`compact` |
| `cards` | 模块 / 能力 / 成果 | `cards[]` `columns` `tone` |
| `kpi` | 关键数字 | `items[]`：`value` `unit` `label` `desc` |
| `process` | 步骤 / 流程 | `steps[]` `direction` |
| `timeline` | 时间轴 / 路线图 | `items[]`：`time` `title` `desc` |
| `arch` | 分层架构 / 业务域 / 能力矩阵 | `layers[]` `top_bar` `label_width` |
| `swimlane` | 跨职能泳道流程图 | `lanes[]` `steps[]`（`lane`/`col`）`links[]` |
| `topology` | 部署 / 网络拓扑图 | `zones[]`（可嵌套）`nodes[]` `links[]` |
| `hub` | 系统集成关系（中枢辐射） | `center` `groups{top/bottom/left/right}` `arrows[]` |
| **`diagram`** | **任意图形（通用引擎）** | `nodes[]`（可嵌套）`edges[]` `layout` |

## 主题库（13 套）

`assets/themes/` 内置 13 套成品主题，按代号引用即换风格：`{ "theme": "navy-gold" }`。

| 浅底（9 套） | 深底（4 套） |
| --- | --- |
| `navy-gold` 藏蓝+金 · `navy-white` 深蓝+白 · `navy-orange` 深蓝+橙 · `red-gold` 红金 · `mono` 黑白 · `royal-yellow` 宝蓝+黄 · `forest-gold` 墨绿+金 · `wine-navy` 酒红+藏蓝 · `truffle-cream` 棕+米白 | `black-gold` 黑金 · `black-red` 黑红 · `charcoal-neon` 深灰+荧光绿 · `purple-gold` 紫+金 |

- 色值与场景对照：`references/theme-catalog.md`（**配色的唯一依据**）
- 规范与颜色角色契约：`references/theme-spec.md`
- 体检：`python scripts/check_themes.py`（逐套验对比度，13 套必须全绿）
- 深浅只换代号，**不改任何页面字段**——这是主题契约的核心价值

## PPTX DSL v1.0

JSON 规格不是"随手定的格式"，而是**有版本的契约**：`spec.json` 是源文件，pptx 是构建产物。

| 产物 | 作用 |
| --- | --- |
| `references/dsl-spec.md` | 规范正文：合规等级 L1/L2/L3、语法与类型系统、MUST/SHOULD 规则、诊断码表、版本兼容策略 |
| `assets/spec.schema.json` | 机器可读契约（JSON Schema draft-07），供编辑器校验与模型结构化输出 |
| `scripts/validate_spec.py` | 契约执行器：结构 + 语义 + **干跑布局实测越界**，输出诊断码与退出码 |
| `scripts/build_pptx.py` | 编译器：spec → 原生可编辑 pptx |

工作流固定为 **写 spec → 校验（闸门①）→ 编译 → 渲染看图（闸门②）→ 交付**。
两道闸门性质不同：① 查"规格是否合法"，② 查"看起来对不对"。
| `table` | 结构化数据 | `header` `rows` `col_widths` |
| `two_col` | 双栏并列 | `left` `right` |
| `compare` | 前后 / 优劣对比 | `left` `right` |
| `image_text` | 图文并排 | `image` `image_side` `text[]` |
| `quote` | 金句强调 | `text` `source` |
| `closing` | 结尾页 | `title` `subtitle` `contact` |
| `blank` | 空白页 | `background` |

完整字段说明见 [`pptx-builder/references/spec-schema.md`](pptx-builder/references/spec-schema.md)。

## 环境准备（安装清单）

### 1. 依赖一览

| 类别 | 组件 | 最低版本 | 用途 | 不装的后果 |
|---|---|---|---|---|
| **必需** | Python | 3.9 | 运行时 | 无法运行 |
| **必需** | [`python-pptx`](https://pypi.org/project/python-pptx/) | 0.6.21 | 生成 pptx | 无法运行 |
| 生成图片页时需要 | [`pillow`](https://pypi.org/project/Pillow/) | 9.0 | `image_text` 图片等比缩放 | 含图片的页面报错 |
| 预览时需要（二选一） | [`pypdfium2`](https://pypi.org/project/pypdfium2/) | 4.0 | 把渲染出的 PDF 转成 PNG（**推荐**，BSD-3-Clause / Apache-2.0） | 无法自动预览自检 |
| 预览时需要（二选一） | [`pymupdf`](https://pypi.org/project/PyMuPDF/) | 1.23 | 同上（备选，**AGPL-3.0**，未装 `pypdfium2` 时自动回退到它） | 无法自动预览自检 |
| 预览时需要 | WPS 演示 / Microsoft PowerPoint / LibreOffice | 任一 | 把 pptx 渲染为 PDF | 无法自动预览自检 |
| 字体（按系统） | Microsoft YaHei（Windows）/ PingFang SC（macOS）/ Noto Sans CJK SC（Linux） | — | 中文字体 | 中文被替换为其他字体 |

> 只生成 pptx、不需要预览图片时，**实际只需 `python-pptx`**；`Pillow` 仅在页面里带图片时才用到。

### 2. 安装命令

```bash
# 最小安装（只生成 pptx，不含图片、不自检）
pip install "python-pptx>=0.6.21"

# 推荐安装（生成 + 预览自检）
pip install "python-pptx>=0.6.21" "pillow>=9.0" "pypdfium2>=4.0"

# 若已有 pymupdf 且不想再装：也可用它替代（许可为 AGPL-3.0）
# pip install "python-pptx>=0.6.21" "pillow>=9.0" "pymupdf>=1.23"
```

渲染后端按系统任选其一安装：

| 系统 | 推荐 | 安装方式 |
|---|---|---|
| Windows | WPS Office 或 Microsoft Office | 官网安装包，安装后自动注册 COM，无需额外配置 |
| macOS | LibreOffice | `brew install --cask libreoffice` |
| Linux | LibreOffice | `sudo apt install libreoffice-impress`（Debian/Ubuntu）<br>`sudo dnf install libreoffice-impress`（RHEL/Fedora） |

中文字体：

| 系统 | 字体 | 说明 |
|---|---|---|
| Windows | Microsoft YaHei | 系统自带，无需安装 |
| macOS | PingFang SC | 系统自带；需覆盖主题字体，见下 |
| Linux | Noto Sans CJK SC | `sudo apt install fonts-noto-cjk` |

非 Windows 系统需在规格里覆盖字体（主题默认值为 Microsoft YaHei）：

```json
"theme_overrides": { "fonts": { "cjk": "PingFang SC" } }
```

### 3. 验证环境

安装完成后运行自检脚本，逐项确认依赖、渲染后端与字体：

```bash
python pptx-builder/scripts/check_env.py
```

输出示例：

```
pptx-builder 环境自检
========================================================
[OK] Python 3.12.2  (Windows AMD64)

-- Python 依赖 --
[OK] python-pptx    1.0.2      (必需) 生成 pptx（必需）
[OK] pillow         12.3.0     (可选) image_text 图片等比缩放
[OK] pymupdf        1.28.2     (可选) 渲染预览图（render_preview.py）

-- 渲染后端（仅 render_preview.py 需要，生成 pptx 不需要）--
[OK] WPS 演示  ..\wpp.exe
[!] Microsoft PowerPoint COM 已注册，但未找到 powerpnt.exe，可能无法启动
[OK] LibreOffice  ..\soffice.exe

-- 中文字体 --
[OK] 主题中文字体 "Microsoft YaHei" 存在: ..\msyh.ttc

========================================================
核心依赖就绪，可以生成 pptx。
```

`[OK]` 通过、`[!]` 警告（可继续，但对应能力不可用）、`[X]` 失败（必须修复）。

### 4. 无需安装的东西

- **无需** Office 或模板文件即可生成 pptx（生成过程是纯 Python 写 XML）
- **无需**联网：全流程离线，不调用任何云服务、不上传文件
- **无需** Node.js / Java / 数据库等运行时

## 快速开始

### 1. 安装到 skills 目录

```bash
# 仅当前项目可用
mkdir -p .codebuddy/skills && cp -r pptx-builder .codebuddy/skills/

# 或：所有项目可用
cp -r pptx-builder ~/.codebuddy/skills/
```

> 其他 Agent（Claude Code / Cursor 等）把 `pptx-builder` 整个目录放到它自己的 skill 目录下即可，
> 目录结构不用改。

### 2. 直接调用脚本（不依赖 Agent）

```bash
# 依赖安装见上方「环境准备」

# 校验规格
python pptx-builder/scripts/build_pptx.py deck/spec.json --check

# 生成
python pptx-builder/scripts/build_pptx.py deck/spec.json -o deck/output.pptx

# 渲染预览图（自检）
python pptx-builder/scripts/render_preview.py deck/output.pptx -o deck/preview
```

### 3. 在 AI Agent 里使用

安装后直接说需求即可，例如：

> 根据这些内容做一份立项汇报 PPT

Agent 会读取 `SKILL.md` 的工作流：提炼结构 → 写 JSON 规格 → 生成 → 渲染自检 → 交付。

### 最小规格示例

```json
{
  "slides": [
    { "type": "cover", "title": "2026 年度复盘", "subtitle": "业务增长与组织效能",
      "author": "战略部", "date": "2026 年 12 月" },
    { "type": "bullets", "title": "三个结论",
      "items": [
        { "text": "**营收增长 32%**，主要由海外市场贡献" },
        { "text": "交付周期缩短 18%", "level": 1 }
      ] },
    { "type": "cards", "title": "关键举措", "columns": 3,
      "cards": [ { "index": "01", "title": "渠道下沉", "desc": "新增 120 个县域网点" } ] },
    { "type": "closing", "title": "谢谢" }
  ]
}
```

## 目录结构

```
├── README.md
├── .gitignore
├── docs/preview.png                     # 首页配图
└── pptx-builder/
    ├── SKILL.md                         # Agent 入口：触发条件 + 工作流 + 约束
    ├── assets/
    │   ├── theme.json                   # 默认主题（配色 / 字体 / 版心 / 页脚）
    │   ├── spec.schema.json             # DSL 的机器可读契约（JSON Schema）
    │   └── themes/*.json                # 13 套成品主题 + index.json
    ├── references/
    │   ├── dsl-spec.md                  # DSL 语言规范（语法 / 类型 / 诊断码 / 版本）
    │   ├── spec-schema.md               # 规格字段说明
    │   ├── diagram-method.md            # 图形选型方法论
    │   ├── diagram-catalog.md           # 40+ 种惯用式图鉴
    │   ├── diagram-ir.md                # 通用图形引擎字段参考
    │   ├── theme-catalog.md             # 配色 × 场景对照
    │   └── theme-spec.md                # 主题契约
    ├── scripts/
    │   ├── build_pptx.py                # 核心生成器
    │   ├── diagram.py                   # 通用图形引擎（容器 / 布局 / 连线路由）
    │   ├── validate_spec.py             # 契约校验（含干跑布局实测越界）
    │   ├── upgrade_spec.py              # 规格版本迁移
    │   ├── dryrun.py                    # 布局测量（校验器内部使用）
    │   ├── render_preview.py            # 渲染为逐页 PNG（自检）
    │   ├── check_env.py                 # 环境与依赖自检
    │   └── check_themes.py              # 13 套主题对比度体检
    └── test/
        ├── README.md
        ├── run_tests.py                 # 冒烟测试入口
        ├── specs/*.json                 # 11 个测试规格
        └── specs_legacy/                # 旧版本规格迁移用例
```

> `test/out/`（渲染产物）与 `dist/`（打包 zip）为本地生成物，已在 `.gitignore` 中排除，不入库。

## 自定义主题

改 `pptx-builder/assets/theme.json`，或在规格里局部覆盖：

```json
"theme_overrides": {
  "colors": { "primary": "0F3D2E", "accent": "E8B44A" },
  "fonts": { "cjk": "Microsoft YaHei", "latin": "Arial" },
  "footer": { "text": "XX 公司 · 内部资料", "show_page_number": true }
}
```

可用颜色键：`primary` `primary_light` `primary_soft` `accent` `accent_soft` `text` `text_light` `muted` `bg` `bg_soft` `border` `good` `warn`。

## 自检机制

`render_preview.py` 按顺序尝试三种渲染后端，全部离线：

1. **WPS 演示 COM**（Windows，`KWPP.Application`）
2. **Microsoft PowerPoint COM**（Windows）
3. **LibreOffice**（跨平台，`soffice --headless`）

渲染出逐页 PNG 后由人工/Agent 逐张核对：文字溢出、元素重叠、表格截断、空页、页码连续性。

这套闭环是刻意设计的 —— 只验证"文件生成成功"会漏掉绝大多数排版问题。

## 测试

```bash
python pptx-builder/test/run_tests.py              # 生成 + 渲染预览
python pptx-builder/test/run_tests.py --no-render  # 只生成
python pptx-builder/test/run_tests.py --check-only # 只校验规格
```

11 个规格共 61 页，覆盖全部 52 个类型名（含别名）与边界情况（要点压缩、窄列卡片、多种底色、竖向流程、宽表、缺图降级、字段别名、深底主题、规格版本迁移）。详见 [`pptx-builder/test/README.md`](pptx-builder/test/README.md)。

> 示例数据（公司名、项目名、金额、指标）全部为虚构，仅用于演示版式效果。

## 已知限制

- **图形边界**：`diagram` 引擎覆盖**二维结构图**；三维 / 透视图、手绘有机风格、UML / BPMN 严格记法不在范围内
- **节点规模**：连线不做交叉最小化，超过约 30 个节点的强连通图建议拆页
- **两类页面**：图形页走引擎按现场拼装；其余版式（要点 / 卡片 / 指标 / 表格…）仍是固定模板，需要新样式请扩展 `build_pptx.py` 并补测试用例
- 表格不支持合并单元格、单元格内多段文本
- 图片按外框等比缩放居中，不提供裁剪 / 蒙版
- 预览渲染依赖本机 Office 软件，纯 Linux 服务器环境需装 LibreOffice
- 自动适配只做"压缩字号 / 换布局方向"这类保守处理，内容严重超量时仍需拆页

## 贡献

欢迎提 Issue / PR。扩展新版式请遵循：

1. 在 `scripts/build_pptx.py` 实现 `r_xxx()` 并注册到 `RENDERERS` 与 `REQUIRED`
2. 在 `test/specs/` 补用例，覆盖边界（空数组、超长文本、最大条目数）
3. 运行 `python test/run_tests.py`，**逐张查看预览图**确认无溢出/重叠
4. 同步更新 `references/spec-schema.md` 与本 README 的类型表

## License

[MIT](LICENSE) © 2026 &lt;版权所有者&gt;

可自由使用、修改、分发（含商业用途），只需保留版权声明与许可证副本；无任何担保。

### 第三方依赖

本项目自身不含第三方源代码，运行时依赖各自遵循其许可证：

| 依赖 | 许可证 | 用途 |
|---|---|---|
| [`python-pptx`](https://pypi.org/project/python-pptx/) | MIT | 生成 pptx（**必需**） |
| [`Pillow`](https://pypi.org/project/Pillow/) | MIT-CMU | 图片等比缩放（含图片页时可选） |
| [`pypdfium2`](https://pypi.org/project/pypdfium2/) 或 [`pymupdf`](https://pypi.org/project/PyMuPDF/) | BSD-3-Clause / Apache-2.0　或　**AGPL-3.0** | PDF 转 PNG（仅预览自检，可选） |
| WPS 演示 / Microsoft PowerPoint / LibreOffice | 各自许可 | pptx 转 PDF（仅预览自检） |

> PDF 转 PNG 优先使用 `pypdfium2`（宽松许可）；未安装时回退到 `pymupdf`。
> 两者都由**使用者自行安装**、不随本项目分发，因此不影响本项目的 MIT 授权。
> 但若你要把本项目部署为**网络服务**且使用 `pymupdf`，请注意 AGPL 第 13 条关于对外提供源码的要求——
> 装 `pip install pypdfium2` 即可完全规避。