---
name: pptx
description: 做 PPT / 幻灯片 / 演示文稿 / 路演稿 / 汇报材料, 或用户提到 .pptx 时用这个: 怎么把一个主题变成一份能直接放映、看着像设计过的 .pptx(配图、图表、动画都有), 用 render_image 画图、write_document 一次出文件。
---

# 做一份 PPT

这台机器上出 .pptx 只有一条路: `write_document`, 路径以 .pptx 结尾, 内容用 Markdown 写, 一行 `---` 开始新的一页。
不用找别的程序, 不用装任何库。**版式由每页的内容形状决定**(下面"六种版式"一节), 你写出对应的形状, 它就排成对应的样子; 字号、间距、页码、颜色、渐变底色、淡入切换和卡片逐个入场的动画都是内置的, 不用写也写不了。

## 先想清楚再动手

1. 一句话写下这份 PPT 要让听众相信什么(结论)。整份片子都为它服务。
2. 定听众和场合: 汇报给领导 / 对外路演 / 内部培训 / 课堂讲解, 决定语气和细节深浅。
3. 定页数: 5 分钟 5~7 页, 15 分钟 10~15 页, 30 分钟不超过 25 页。一页只讲一件事。
4. 列大纲(每页一行标题 + 打算用哪种版式 + 这页的视觉元素是什么), 再往每页填内容。大纲不顺, 先改大纲。
5. 选主题(theme, 见下)。用户点名了风格就必须照选; 没点名按题材选。
6. 先取图再写稿: 大纲定了, 先把要配的图一张张取来(照片和图标用 `fetch_image`, 示意图用 `render_image`, 下面"配图"一节), 拿到路径再写 Markdown。

## 六种版式: 写成什么形状, 就排成什么样子

| 版式 | 这页写什么 | 排出来是什么 | 什么时候用 |
|---|---|---|---|
| 封面 | 第一页: 一个一级标题 + 一行副标题(谁 / 日期 / 场合) + 一张照片 | 照片铺满右半幅, 大字靠左; 没照片就大字居中加光晕圆弧 | 第一页, 必须; 照片用 fetch_image 取 |
| 章节页 | 只有一个二级标题, 可以加一张照片, 别的什么都不写 | 左上大序号 01 / 02 + 标题; 有照片同封面铺右半幅 | 三部分以上的片子, 每部分开头一页 |
| 数字卡 | 二级标题 + 一张**只有表头和一行数据**的表, 2~5 列 | 一列一张大卡片: 大数字 + 小标签, 逐张入场 | 三个关键数(营收 / 增幅 / 客户数) |
| 卡片格 | 二级标题 + 2~6 条要点, **每条以加粗短语开头**, 后面接一句说明, 不嵌套; 加粗前面放 ![](图标.png) | 每条一张卡片, 淡色圆里一个图标(没图标就是序号球), 逐张入场; 1~3 条一行, 4 条 2×2, 5~6 条 2×3 | 并列的几件事 / 几个步骤 / 几个卖点 |
| 双栏 | 二级标题 + 两个三级标题, 各自下面放要点或一段话 | 左右两块面板, 小标题用强调色 | 对比: 自研 vs 外采, 改前 vs 改后, 利 vs 弊 |
| 金句 | 二级标题(可省) + 只有一段 > 引用 | 大引号 + 大字斜体 | 结论页、客户原话、一句话总结 |

不是上面任何一种的页, 就是普通内容页: 标题在上, 要点在下; 有图或图表 → 字左图右(没字就整页); 有表(两行以上数据) → 整张表。

**节奏**: 相邻两页别用同一种版式; 一份 10 页的片子里, 数字卡、卡片格、双栏至少各出现一次, 图或图表至少三页; 纯要点页不超过三分之一。
一页只有标题 + 三五条短要点, 是最没人看的页, 能改成卡片格、数字卡或配一张图就改。

## 配图: 三种来源, 先取图再写稿

| 要什么 | 用哪个工具 | 写进哪一页 |
|---|---|---|
| 真实照片: 设备 / 产品 / 场景 / 城市 / 人群 | `fetch_image`, path 以 .jpg 结尾, query 写具体(品牌 + 型号 + 场景) | 封面一张, 章节页各一张: 那页只有标题(封面多一行副标题)加 ![说明](figures/x.jpg) |
| 图标: 卡片格每条一个 | `fetch_image`, kind 填 icon, path 以 .png 结尾, color 填主题强调色, query 用英文名词 | 卡片格每条写成 ![](figures/icon.png) **引题** 说明 |
| 示意图 / 流程图 / 架构图 | `render_image`, 自己用 SVG 画, 结果是 PNG | 内容页: 两三句话 + ![说明](figures/flow.png), 字左图右 |

- **每份 PPT**: 封面一张照片; 卡片格的页每条一个图标; 讲流程 / 架构的页一张自己画的示意图; 图或图表至少三页。
- **照片的 query 写具体**: NVIDIA DGX Spark on a desk 比 电脑 好; 中文也行, 但英文品牌型号最准。拿回来的图会给你看, 不对题就换更具体的词再取一次(加 close-up / dark background / office)。结果里带来源, 片子要对外发布时告诉用户一句。
- **图标**: color 填主题的强调色(tech #22D3EE, clean #0F766E, warm #B85042, forest #2C5F2D, berry #E0A458); 选近似正方形的图标(server / shield / chart-bar / phone / cloud), 品牌 logo 太宽, 不放卡片里。想要彩色的, set 填 fluent-emoji-flat; 结果里列了别的候选, 用 name 指定。
- **自己画**: 尺寸 1600×900(放在页面右边刚好); body 的背景色自己定, 和主题一致(tech 用深蓝 #0B1220, clean / forest 用白, warm 用 #FBF7F2, berry 用 #2B0F1E); 文字颜色和主题正文一致(深色主题用浅字), 线条和填充用主题的强调色和两三个邻近色; 字用系统字体, 中文可以直接写; 留 5% 边距, 别顶边。画流程图(圆角框 + 箭头)、架构图(分层方块)、信息图(大图标 + 一个数), 别画写实的人和物, 矢量画不像。
- **路径**: 结果里的路径原样写进 Markdown。用户给的图在 inbox/ 里, 同样写相对路径。没取也没给的图, 不要编路径(路径不存在会出错)。

## 图表: 表头第一格写图型名, 这张表就变成原生图表

数据页用原生图表(PowerPoint / WPS 里能改数、跟主题配色), 写法就是一张 Markdown 表, 只多一条规矩: **表头第一格写 bar(柱) / line(折线) / pie(饼)**, 后面每格一个系列名; 数据行第一格是类别, 后面是数字(可以带千分位逗号、% 和单位, 只取数)。最多 12 个类别、4 个系列; 饼图只画第一个系列。第一格不是这三个词的表照常排成表格。

例子(三个季度两条柱):

| bar | 营收(万元) | 毛利(万元) |
|---|---|---|
| Q1 | 1,100 | 410 |
| Q2 | 1,240 | 474 |
| Q3 | 1,385 | 555 |

图表和图片一样放在页面右边, 上面两三句话说这张图证明了什么; 一页只放一个图表, 不和图片或别的表同页。

## 每一页怎么写

- **标题是一句有观点的话**: 写"成本比去年降 18%", 不写"成本情况"。不超过 20 个字, 不用句号结尾。
- **要点 3~5 条, 每条不超过两行**; 一页不超过 6 条。要点里真正要强调的数字或结论用 **加粗**, 它会变成强调色, 一页最多两处。
- **卡片格的每条**: 加粗短语 2~6 个字(渠道下沉 / 产品提价), 空一格再写说明; 说明一句话, 不超过 30 个字。
- **数字卡的表**: 表头写标签(营收 / 毛利率), 数据行写数字带单位(1,385 万 / 40.1%); 数字 2~8 个字符最好看。
- **表格**: 最多 5 列 8 行; 表上面一行字说这张表证明了什么。
- **讲稿**: 每页末尾用一段 HTML 注释写讲稿(30~80 字), 它会进"演讲者备注", 放映时听众看不到。
- **最后一页 = 结论 / 下一步 / 请求**: 把第一步写的那句话放回来, 加上希望听众做什么。写成金句版式或卡片格; 不写"谢谢观看"页。

## 主题(theme): 五套, 按用户的话和题材选

| 用户的话 / 题材 | theme | 长什么样 |
|---|---|---|
| 科技 / AI / 产品发布 / 酷一点 / 深色 / 现代 | tech | 深海军蓝渐变底, 青色强调, 浅色字 |
| 温暖 / 生活 / 教育 / 餐饮 / 亲切 | warm | 浅沙底, 赤陶红强调 |
| 环保 / 农业 / 健康 / 可持续 / 自然 | forest | 白底, 深绿标题, 森林绿强调 |
| 文化 / 艺术 / 品牌 / 庆典 / 高端 | berry | 莓红深底, 金色强调, 米色字 |
| 商务 / 正式 / 简洁, 或没说 | clean | 白底, 近黑标题, 一点青绿 |

主题名只有这五个, 别的名字会报错。用户点名要某种风格时, 不许留在 clean。要"更炫"的效果不在这五套里的, 如实说明只有这五种。

## 写法上的规矩

- 全篇用用户这条消息的语言。
- 一级标题只给封面; 每一页第一个标题就是这页的标题, 用二级标题; 三级标题只在双栏页里用, 且正好两个。
- 要点用 - 开头, 最多两级; 卡片格和数字卡的页里不要再放别的东西(最多在标题下加一句引言)。
- 别在一页里同时放图和表, 也别同时放图和图表。

## 交出去

1. 图先画好, 内容全部写好后, 一次调用 `write_document` 出 .pptx(不要先写 .md 再转, 多一轮没有意义; 除非用户要改第二版, 那时从工作区里已有的 .md 用 source 参数转)。
2. 结果里有页数、主题和嵌进去的图片数; 页数和大纲对不上就查哪页漏了 `---`, 图片数不对就查路径。
3. 用 share 把文件交给用户, 并用两三句话说明这份片子的结构和建议的讲法。

## 参考

- reference/example-deck.md: 一份 12 页的示例, 六种版式、照片、图标、示意图和图表各出现至少一次(示例里的图片路径是示意, 真做时先用 fetch_image / render_image 取出来), 照它的结构套。