pptfast

面向 AI agent 的稳定、可编辑 PPTX 生成工具：输入语义化 IR，输出原生 DrawingML。

English | [简体中文]

为什么

自由绘制 SVG/HTML 再转 PPTX 的链路上限很高，但下限不稳定——弱模型（或强模型状态不好时）画出来的往往是版式错乱、脱离品牌规范、甚至无法阅读的产物。pptfast 用受控词汇取代自由绘制：一份语义化 IR（zod schema）、17 个内置主题（各自打包一套 style 设计 tokens 与 brand 品牌标识元素）、带 seed 多样性的 layout/component 版式库，以及每个图形都保持可编辑的原生 DrawingML 输出——不是贴上去的一张图。

这条「可编辑」的说法有一个需要如实说清的边界：pptfast 真正产出的原生单元是图形（shape）和文字段（text run），每一个都是 PowerPoint 里可以选中、改样式、改文字的真实对象，这也包括 chart、data_table 这两类组件画出来的图形与文字。pptfast 不会产出的是原生的 PowerPoint 图表部件或表格对象：没有内嵌的图表数据，也没有 ``。图表的柱子、表格的单元格本质上是几何图形加文字，不是一个 PowerPoint 能凭新数字重新画一遍的数据绑定对象。要改数字，请去改 IR 再重新渲染，而不是在 PowerPoint 里拖动柱子或直接改单元格内容。这是为了上文说的确定性、seed 稳定输出而做的主动取舍，不是遗漏，也不影响其余每一个图形本身的可编辑性。

一份 PPT 本质上是五件事：内容模型、二维布局、视觉样式、动效、叙事。pptfast 负责后四项，内容模型交给你（或你的 agent）通过写 IR 来掌控。

安装

npm install -g @liustack/pptfast
pptfast --help

需要 Node >= 18。也可从源码构建：git clone https://github.com/liustack/pptfast.git && cd pptfast && pnpm install && pnpm build。

作为 Claude Code 插件

本仓库同时是一个 Claude Code 插件，内置整套生成流程的 skill：

/plugin marketplace add liustack/pptfast
/plugin install pptfast@pptfast
/reload-plugins

skill 依赖 CLI 驱动，请一并安装 CLI（npm install -g @liustack/pptfast）。

作为 DSH 插件

pptfast 同时是一个 DeepSeek Harness（DSH）插件，一条命令装进 DSH profile：

npx -y @deepseek-ai/dsh plugin --profile web add @liustack/pptfast@0.17.0

版本号要点名：dsh 用 pnpm 11 装插件，pnpm 11 默认压住 24 小时内发布的版本，@latest 会被静默解析到更旧的一版。对本包来说旧版是 0.16.0，里面根本没有 dsh 插件入口。点名版本号属于明确指定，pnpm 会照装。npm view @liustack/pptfast version 可查当前版本。

插件卡片显示为「pptfast」，把同一套生成流程的 skill 注册进 DSH 的技能系统。skill 驱动的 CLI 就在插件包自己里面，那里不需要单独装 CLI。卸载插件即移除技能，不留残余。

其他 agent（Codex 等）

skills/pptfast/SKILL.md 是一份自包含的 Markdown 操作手册——把它引入你的 agent 上下文（例如在 AGENTS.md 里引用），即可复用同一套 schema → 大纲 → validate → render 回路。

快速开始

写一个最小 deck，跑一遍 validate → render → preview 回路：

cat > deck.json  -o  [--theme ] [--theme-file ] [--style ] [--draft]` | 校验并渲染成 `.pptx`——`target` 可以是 IR JSON 文件、deck 项目目录，或裸名（见「Deck 项目」） |
| `validate ` | 校验 IR，输出带页码的错误信息与提示性警告——`target` 形式同 `render` |
| `audit  [--json] [--pixels]` | 确定性几何审查（溢出/越界/低对比度/重叠/内容截断/内容丢失）——`target` 形式同 `render`，一旦发现问题 exit 1（见「审查」） |
| `asset-brief  [--json]` | 为每个 `image` 组件生成一份配图简报——真实渲染框、裁切模式、建议生成尺寸、主题色板/气质、可直接粘贴的提示词（见「配图简报」） |
| `spec validate ` | 校验 deck spec 是否符合 schema 与随 strategy 变化的硬门（见「Deck 项目」） |
| `assemble  [-o ]` | 把 deck 项目目录合并成单个 IR JSON 文件 |
| `disassemble  -o ` | 把 IR JSON 文件拆成 deck 项目目录 |
| `schema [--style \| --spec]` | 输出 IR 的 JSON Schema（或 style 覆盖 schema，或 deck spec schema） |
| `themes [--json]` | 列出 17 个内置主题 |
| `brand extract  -o  [--id] [--label]` | 从 `.thmx`/`.potx`/`.pptx` 本地抽取品牌配色与字体生成主题文件（见「你自己的品牌」）——用 `--theme-file` 装载（`validate`/`audit`/`preview`/`serve` 同样支持），或作为 deck 项目的 `theme.json` |
| `narratives [--json]` | 列出具名叙事预设（strategy/pacing/audience 轴 + theme 推荐） |
| `preview  -o  [--html]` | 逐页渲染为独立 SVG（`--html` 额外写出一个自包含的 `preview.html`）——`target` 形式同 `render`，永远不受占位页拦截 |
| `serve  [--port 4400] [--no-open]` | 实时预览服务：与 `preview --html` 同款审阅页，源文件变化自动刷新，批注直接提交回 deck 目录生成 `revision-request.json` |
| `migrate  -o ` | 把 v3 IR 文件转成 v4，或把 `deck.plan.json` 项目目录转成 `deck.spec.json`——确定性转换，不调模型（见「IR」与「Deck 项目」） |
| `init` | 生成 `pptfast.config.json` 模板 |
| `check-update` / `self-update` | 检查 npm 上的新版本 / 更新全局安装 |

## IR

运行 `pptfast schema` 获取完整 JSON Schema——让模型写 IR 之前先读它。一份 deck（`PptxIR`）包含 `version`（现为 `"4"`，且省略时默认就是它）、`filename`、一个可选的 `narrative`（预设 id 字符串，或部分轴对象——详见下文「叙事」一节）、`theme`（`id` 加可选的 `style`/`brand` 覆盖）、`meta`、`assets`——均可省略、有默认值——另外还有一个独立的可选 `brand`（logo 位置）字段，以及必填的有序 `slides` 列表。每张 slide 有一个 `type`（`cover`、`chapter`、`content`、`ending`）、一个可选的 `layout`（显式指定页面版式 id，一经设置恒生效、优先于自动选型——省略则由 pptfast 自动选型，详见下文「版式选型」）、一个可选的 `arrangement`（content slide 正文的排布方式，如 `two_column`、`kpi_focus`），以及一组带类型的 `components`（`bullets`、`kpi_cards`、`image`、`chart` 等）。`assets` 的形状是 `{ images: { [id]: { src, alt? } } }`，component 通过 `asset_id` 引用图片，同一张图可以在多页复用而不必重复内嵌。

一份 deck 还可以携带一个可选的 `seed`（整数，让自动选型的版式在多次修订之间保持稳定——省略时如何生成，详见下文「版式选型」）。任意 slide 都可以设置一个稳定的 `id`（spec 的页面和校验报错都靠它引用）、`placeholder: true`（还没有内容的占位 slide——由 `assemble` 为 spec 里没人填写的页面注入，内容质量检查会跳过它，`render` 也会因它拒绝导出，除非加 `--draft`），以及一个可选的 `notes`（同义词 `note`/`speaker_notes`/`speakerNotes`），导出为原生 PowerPoint 演讲者备注——只是给主讲人自己看的内容，不会画到幻灯片画布上，也从不计入任何版式容量。模型输出里容易和 schema 对不上的字段名（跨 component 类型共 55 组同义词，例如 kpi 的 `title`→`label`、quote 的 `content`→`text`、swot 的 `strength`→`strengths`、bmc 的 `partners`→`key_partners`）会在校验时静默改写成规范名——`validate`/`render`/`preview` 会打印一条改了什么的提示，从不因此报错。这套救援机制只覆盖弱模型的同义词漂移，不覆盖 v4 之前的旧词汇。标着 v4 却仍写 `scenario`（而不是 `narrative`）、`mode`/`delivery`（而不是 `strategy`/`pacing`）、或轴值还停留在旧的 `narrative`/`text`/`presentation` 的文档，会像任何其他未识别字段或非法值一样直接硬报错，并列出当前正确的名称和取值。显式写 `version: "3"`（或 `"2"`）同样硬拒绝并给出迁移指引——见下文 `pptfast migrate`，这是旧词汇输入唯一支持的路径。

八种 component 类型是「满幅」的：`swot`（strengths/weaknesses/opportunities/threats 四象限）、`bmc`（九宫格商业模式画布）、`waterfall`（运行合计瀑布图）、`gantt`（共享数轴上的甘特条形图）、`pest`（政治/经济/社会/技术宏观环境扫描）、`five_forces`（波特五力竞争结构轮辐图）、`heatmap`（值驱动色阶网格）、`sankey`（分层且量值成比例的流向图——导出为原生可编辑矢量，而非该图表类型在别处常见的栅格图片）。各自独占整张 slide 的内容区域，必须是该 slide 唯一的 component——混入其他 component 会在校验时报错，而不是静默丢弃。

v4 IR schema 自 0.4.0 起冻结——后续演进只走加法（新增可选字段、新增枚举值），任何破坏性变更都会启用新的顶层 `version` 值，并沿用 v3 那套硬拒绝 + 迁移提示的处理方式。`pptfast migrate  -o ` 能确定性地把一份 v3 文件转成 v4（只做字段改名——theme、版式选型、内容预算与视觉输出都不变）——`deck.plan.json` → `deck.spec.json` 的姊妹转换见下文「Deck 项目」。

## 主题

主题（theme）打包了 style（设计 tokens）、brand（品牌标识元素）与每个页型各自的版式（layout）集合——以下是 17 个内置主题。每个内置主题默认对每个页型都开放全部已注册版式（每个 archetype 都会按主题的实际背景色自适应取色，所以全集在任何主题下都保持可读）。收窄集合是主题作者的主动选择，不是常态——17 个主题里没有一个收窄任何页型（早年的三主题排除已在 ink 自适应取色修复后撤销）。覆盖 style（`--style`）即可为某个主题重新配色。

| id | label |
|---|---|
| `consulting` | Business Consulting |
| `enterprise` | Enterprise |
| `academic` | Academic |
| `insight` | Financial Insight |
| `campaign` | Marketing Campaign |
| `bloom` | Soft Bloom |
| `classroom` | Classroom |
| `ink` | Ink Wash |
| `tech` | Tech |
| `runway` | Fashion Runway |
| `journal` | Editorial Journal |
| `luxe` | Luxe |
| `heritage` | Heritage |
| `pulse` | Health & Life Science |
| `terra` | Sustainability & ESG |
| `ember` | Startup Pitch |
| `vermilion` | Official Report |

### 你自己的品牌

让产出看起来像*你的公司*而不是某个内置主题，最快的路径是从你已有的模板里抽取品牌。`pptfast brand extract` 从 `.thmx` 主题、`.potx` 模板或 `.pptx` 演示文稿中读出配色与字体——**完全在本地进行，文件从不离开你的机器**（已对 macOS PowerPoint 自带的全部 39 个 Office 主题逐一验证）——并写出一个 pptfast 主题文件：

```bash
pptfast brand extract corp-template.pptx -o my-brand.theme.json
pptfast render deck.json -o deck.pptx --theme-file my-brand.theme.json